STATE_layer_create

 

 



   *** very useful
   A very useful and easy to use function.
   The function returns a handle to a polygon which is the created layer.
   After calling this function the created layer is immediately visible.
   (no need to call STATE_engine_add_polygon() )

   Using STATE_layer_create() one can easily create a square polygon
   with a bitmap on it. The first four parameters define the layer size and position.
   No matter what is the size of the window which you render on the
   top left corner is always 0,0 and the bottom right corner is 100,100
   For example if the four numbers 0,0,50,100 are given as the first 4 parameters
   then the layer will occupied the half left of the rendered screen
   If there are two or more polygon layers that overlap then the one which was 
   first created will be on top. Use STATE_layer_set_depth()to control the order and the depth in which the
   layer are rendered.
  
   Return value
  		The function returns a handle to a polygon which is used for the layer.
  		
  
  	Parameters:
  		left_x, top_y:
  				The top left corner of the created layer.
  				Any number in range [0-100]. (0,0) is the top left corner
  				while (100,100) is the bottom right corner
  
  		right_x, bottom_y:
  				The bottom right corner of the created layer.
  				Any number in range [0-100]. (0,0) is the top left corner
  				while (100,100) is the bottom right corner
  
  
  		Note that after the a layer is created it is possible
  		to change/move the points using the Polygon and Point APIs
  		one can also call STATE_layer_set_shape() to change the shape of
  		the layer
  
  
  		bitmap_handle: A handle to a bitmap that will be used.
  				Give NULL if your layer will use color fill.
  				Note that after the layer is created, one can use STATE_polygon_set_bitmap_fill()
  				to change the bitmap.
  
  		glass_type:
  				Using this parameter one can determine if the layer will be
  				opaque or translucent. Use any of the values possible with
  				the STATE_polygon_set_translucent() function.
  				To precisely control the level of translucency 
  				call STATE_polygon_set_light(layer_handle, translucent_level_rgb);
  		
  
   Remarks:
   --------
  
  	A very convenient way to work with layer polygons is
  	to create them all at the beginning of the program and then to disable those
  	which should not be visible right away.
  	Then during the program run, enable layer polygons according to the need.
  	There is no time penalty for having many layer polygons which are disabled
  	Only those which are drawn consume time. Layers are very fast to draw since
  	they exploit the 3D card hardware. The time it takes to draw a layer
  	depends on its size. If the layer covers the whole rendering window\fullscreen
  	then the slowdown in FPS might be measurable.
  
   Examples:
  
  	Example 1:
  		  Creating a layer on the whole window
  		DWORD my_bitmap=STATE_bitmap_load("binocular", -1);
  		if(my_bitmap==NULL) return(VR_ERROR);
  		DWORD layer_polygon=STATE_layer_create(0,0, 100, 100, my_bitmap, FILTER_GLASS);
  		  After the next render the layer will be shown on the screen
  
  	Example 2:
  		  A more advanced example which show how to make a message
  		  appearing on the screen and then fading away and disappearing.
  		  This message could be something like "1000 points bonus"
  		  "Extra life" etc. This example is quite important since once
  		  you will understand it you will be able to create many more nice effects
  		  that have nothing to do with layers. 
  		  The following example is comprised of 3 functions that together
  		  create the mechanism.
  
  		  Call this function at the beginning of the program
  		DWORD create_message_layer(void)
  		{
  			DWORD my_bitmap=STATE_bitmap_load("ExtraLife", -1);
  			if(my_bitmap==NULL) return(NULL);
  
  			  Note that we have chosen LIGHT_SOURCE_GLASS below since
  			  this type of blending will do 'add' between the layer_message polygon and the
  			  rendered world below (new_pixel=src+dest). We need this adding for
  			  doing the fade away effect. We will make the message_layer_polygon
  			  darker and darker till it wont be seen (new_pixel= 0 + dest == dest)
  
  			DWORD message_layer_polygon=STATE_layer_create(20,15, 80,30, my_bitmap, LIGHT_SOURCE_GLASS);
  			if(message_layer_polygon==NULL) return(NULL);
  			  disable the polygon since we dont want it to be seen now
  			STATE_polygon_disable(message_layer_polygon);
  			m_is_message_visible=NO;   remember the status of the message in a global\class member variable. 
  			return(message_layer_polygon);
  		}
   
  		  Call this function when the message should be seen
  		void make_message_visible(DWORD message_polygon)
  		{
  			STATE_polygon_enable(message_polygon);
  			BYTE rgb[3]={255,255,255);
  			  Show the message in full visibility
  			STATE_polygon_set_light(message_polygon, rgb);   Set the rgb of all the points to 255,255,255
  			m_is_message_visible=YES;
  		}
  		
  
  		  Call this function before each render
  		void make_message_fade_away(DWORD message_polygon)
  		{
  			if(m_is_message_visible==NO) return;   If the message is not visible then there is nothing to do
  			  All the points have the same rgb so lets check the first one
  			DWORD point=STATE_polygon_get_first_point(message_polygon);
  			BYTE rgb[3];
  			STATE_point_get_rgb(point, rgb);
  			if(rgb[0]==0) {
  				STATE_polygon_disable(message_layer_polygon);
  				m_is_message_visible=NO;
  				return;
  			}
  			  Reducing the rgb will make the message darker and because we use LIGHT_SOURCE_GLASS 
  			  The result will be fading away
  			rgb[0]--;
  			rgb[1]--;
  			rgb[2]--;
  			STATE_polygon_set_light(message_layer_polygon, rgb);   Set the rgb of all the points of the polygon
  
  		}
  
  

 

 

Go to page 1      Select API

 

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