STATE_font_write_text

 

 


#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++;
  

 

 

Go to page 1      Select API

 

Copyright © 2007 3DSTATE Corporation. www.3dstate.com