GAME PROGRAMMING RESOURCES

HOW TO PRINT TEXTS

Open, compile and test the TextStrings project by following the procedure described in the Quick Start Tutorial for the BallGame project.

The demo will simply print 'HELLO' on your screen.

The source code is fully commented and examining it is strongly recommended!

Don't forget to refer to Reference document for details on all functions called in the source code!

STRINGS

1. The source code is a very simple program that works as follows:

  • When the engine executable is launched, the compiled .dll is loaded and 20 bytes are allocated for the TextString string.


  • When the engine calls the Init() callback, the TextString string contains random data. Technically, TextString is an array of variables of type 'char'. In memory, physically, it is a sequence of 20 bytes like


    Each value in the string is rendered as a character when printed on the string.


  • The string cannot be printed unless it contains a byte set to 0. The zero byte marks the end of the printable text in the string. So, in the Init() code we need to reset the string to some default text by calling a Windows function named 'strcpy()'.

    strcpy(TextString,"HELLO");

    It basically copies some meaningful text into our garbage-filled string. The string becomes


    Where 72 is the code for H, 69 is the code for E, 76 is the code for L and so on.


  • When the engine calls the Run() callback, the string is passed to the iPrintCentered() function that prints it to the screen.


    • 2. Uncomment the sprintf() function call in the Run() callback by removing the // preceding it, so that it is compiled and executed.

    Re-compile your .dll ([Ctrl]+[F5] for VisualC or [F9] for Dev-C++). Now the code works as follows:

  • As seen above, when the engine calls the Run() callback for the first time, after exiting the Init() callback, the string is like


    but the sprintf() function immediately overwrites its content with a new text now.


  • The new text is formed by 'TIME: ' followed by the text version of the value in the variable named 'Seconds'. Basically, the sprintf() is used to build strings by concatenating other strings and values converted to strings. For example, after a sprintf() call, our string is like


    that prints to

    TIME: 4.361202


    • 3. Keep in mind that the Run() callback is entirely executed again and again, 75 times per second. It means that the sprintf() is executed again and again, so the TextString string is updated (overwritten) every 75th of second and the printed text shows the value in the Seconds variable real-time.

    4. The sprintf() function wants the string to write into as the first parameter.

    Make sure that the destination string is big enough for the operation!

    If you provide a string that is smaller than the string built by sprintf(), the compiler will not warn you but your compiled dll will crash.

    This is a very common mistake and causes bugs that aren't always easy to find!

    The string size is set when the string is defined. In our example, the string is named 'TextString', is 20 characters long and is defined at the beginning of the listing.

    5. The second parameter for the sprintf() function is a string layout. It is used as a reference when building the final string.

    Normal text provided in the layout string is used as is in the destination string, while the %f code is replaced with a value.

    In our example, the layout string is

    TIME: %f

    Which means that we want to insert a value in place of %f

    The value is taken from the first float variable passed as parameter after the layout string. In our example it is the variable named 'Seconds'. The resulting string is then like

    TIME: 4.361202

    6. The following are valid ways to use sprintf()

    sprintf(TextString,"TIME: %06.2f",Seconds);

    formats the value so that its total number of characters is 6, three before the decimal point, one for the dot and and two after the decimal point. The 0 preceding the 6 means that zeros are used to ensure that the value is 6 characters long (e.g. 002.23).

    sprintf(TextString,"M: %03.0f S: %04.1f",Seconds*2.0f,Seconds);

    replaces the first %f code with the first parameter after the layout string and replaces the second %f with the second parameter after the layout string.

    char tempstring[200];
    strcpy(tempstring,"text");
    sprintf(TextString,"%s %f %s",tempstring,Seconds,tempstring);

    builds a mixed string. Unlike %f, the %s code is replaced with the contents of a string variable, and not a float variable.

    REMARKS

  • The sprintf() function is a powerful one. To know more about it, please refer to documentation available on the Web. Try searching the Internet for something like 'sprintf usage'.

  • The strcpy() function is just one of the functions that you can use for string manipulation. Try searching the Web for something like 'string manipulation strcpy strcat'.

  • Keep in mind that sprintf() DOES NOT print (render) the string. It only builds it. The string is rendered by iPrintCentered() in our example. Please refer to Reference document for details about iPrint() and iPrintCentered() functions.