|
#define FONT_WRITE_DEFAULT 0
#define FONT_WRITE_CENTERED_X 1
#define FONT_WRITE_CENTERED_Y 2
#define FONT_WRITE_PIXELIZED 256
*** Very useful
Write text on the screen.
Using this function one can easily do the following
1. write text to the screen that would show for a specific time limit
2. Switch off old text that was written to the screen
3. Replace old messages with new ones
4. Create effects such as moving the text
Parameters:
font_handle:
a handle to a 3DSTATE font. Use to obtain a handle
for example: font_handle=STATE_font_create("Ariel", 14, FONT_CREATE_DEFAULT);
text:
The text itself for writing on the screen
x,y:
The location on the screen where the text will be placed.
0,0 denotes the top left corner
100,100 denotes the bottom right corner
This means that the size of the rendering window is not important
alpha:
use this to control the level of transparency of the text
255 means opaque. 0 means totally transparent
red, green, blue:
The color of the text
flags:
any of the following:
FONT_WRITE_DEFAULT,
FONT_WRITE_CENTERED_X,
FONT_WRITE_CENTERED_Y,
FONT_WRITE_PIXELIZED
By default the x,y given is the top left corner of the text.
Use FONT_WRITE_CENTERED_X or FONT_WRITE_CENTERED_Y to change it
Use FONT_WRITE_PIXELIZED for making ugly looking text (pixelized)
Use | ot + to combine several flags together. for example FONT_WRITE_CENTERED_X | FONT_WRITE_CENTERED_Y
number_of_renderes:
When calling STATE_font_write_text() the text doesn't appear immediately but only after STATE_engine_render() is called
Using this parameter one can tell the engine to resubmit the text for rendering also in the next x renders
There are three common situations where we write text:
A- Text that keeps changing and is written before (or after) each render
for example (in a game) the plane altitude, time left etc ...
In this case call with number_of_renderes==1
B- Writing the text once with the atention that it will
be displayed for a long period of time or uknown period of time.
Example "Gear: Manual", "Auto pilot: Off", "Copyright my company 2003"
in this case use number_of_renderes==INT_MAX (see Example A)
If you later want to change the text simply
call STATE_font_write_text() again giving the same x,y just with different text
if you later want to switch off this text simply call
again with the same text and x,y just with number_of_renderes==0
C- Writing text for a period of time
for example "1000 points bonus", "Extra life" etc ...
in this case use number_of_renderes==1000 or any other number ...
note that on different computers there is different FPS rate (frames per second rate)
To make the text appear the same period time on all computers use
STATE_engine_get_computer_speed_factor()
Return Value:
The function returns a handle to the text created (or NULL if failed)
currently there is nothing to do with this handle. In the future this handle will
be used by the STATE_text_ API.
General remarks:
1. This function is very fast since it is using the 3D graphic accelerator
to write the text. This is ~1000 faster then using the Windows GDI ...
2. 3DSTATE 2D text writing mechanism has some important advantage over
traditional 2D text mechanism.
For example there is no need to add spaces when writing text with varying length
One can switch off old text messages etc ...
3. To make the text moving on the screen simply call the function before (or after) each render
with modified x,y. Set the number_of_renderes to 1. See example 3
4. To make a text message appear for specific duration measured in seconds (rather in number of renders)
use STATE_engine_get_computer_speed_factor() to help you calculate the number of rendered needed
See also:
STATE_object_create_from_text(), creats an 3D object from the given letters
STATE_engine_get_computer_speed_factor(),
STATE_font_write_text_scaled()
Example A:
DWORD ariel14=STATE_font_create("Ariel", 14, FONT_CREATE_DEFAULT);
STATE_font_write_text(ariel14, "Test123", 10, 10, 255, 255, 255, 120, FONT_WRITE_DEFAULT, INT_MAX);
Example B:
Switching off (removing ) the text message from example A by
using the same text and x,y but with number_of_renderes==0
STATE_font_write_text(ariel14, "Test123", 10, 10, 255, 255, 255, 120, FONT_WRITE_DEFAULT, 0);
Example C:
animating text. Simply call the function before (or after) each render
with modified x,y. Set the number_of_renderes to 1
STATE_font_write_text(ariel14, "Test123", x, 10, 255, 255, 255, 120, FONT_WRITE_DEFAULT, 1);
x++;
|