STATE_object_auto_add_shadows

 

 


  *** a very useful and powerful function
   This function uses Stencil shadow volumes techniques to automatically create shadows for the object.
   This is a similar technique to what is used in Doom3 (technique called Carmack's Reverse). There are many good articles 
   on the web describing different techniques for creating shadows. The good news is that you don't need to read any of them
   Currently only objects in Directx format (extension .x) can be used to create shadows.
  
   Parameters:
  		object_handle:
  			a handle to the object that cast a shadow
  
  		ON_or_OFF:
  			can be ON or OFF. If OFF is given no shadows will be created for the given object
  
  
  		number_of_light_sources:
  			A shadow can be created from one or more light sources.
  			The engine will automatically use the closest and strongest light sources.
  			Using two light sources doubles the rendering time. Using more than 4 light sources is very rarly done
  			Note that if we have 10 objects and each one of them is using 2 light sources then there will be between
  			2 to 20 light sources used for creating the shadows (depending whether the object are using the same light sources ....)
  			The only way to ensure there are no more than four light sources used is to make sure there are only 4 light sources defined in the world
  		
  
   Return value:
  		Returns OK or VR_ERROR. An error is returned if the object was not loaded from a directx file
  		for example STATE_object_create_from_file("monster.x"); currently only x files can be used to cast shadows
  		using this function.
  
   Remarks:
  		Note that even when the object is disable it will continue to produce shadows
  		This is because in many case a simplified disabled object is used to produce the shadow of high
  		detailed object. To disable a shadow call STATE_object_auto_add_shadows(my_object, OFF, 0);
  
  
   Tips:
  		1) Creating shadows is very time consuming. The more polygons in the object the more time it takes.
  		Therefor many times a more simplified object should be used for creating the shadows
  		The simplified object should never be rendered (always disabled STATE_object_disable()) 
  		but should always be in the same position and direction as the full detailed version.
  		
  
  		2) Note that the time it takes to render is linked directly to the number of light sources used.
  		It is advised for performance matters that when using this function for creating shadows, to use only 1 to 4 light sources in the world
  
  		3) Use STATE_light_set_distance_reach() to limit the effect of lights and thus minimize the number of source lights
  			used each render for calculating the shadows
  
  	The 3DSTATE Engine offers different techniques for creating shadows.
    For static shadows one can use the lightmaps function to create shadows
  	The function STATE_engine_create_shadow() and STATE_engine_create_dynamic_shadow()
  	use a different methos to create shadows. To know what is apropriate for your specific implimentation you
    should test both methods
    
   See also: STATE_engine_create_dynamic_shadow(), STATE_engine_create_shadow()
  
   Examples
  
  		  disabling shadow creation for an object
  		A) STATE_object_auto_add_shadows(my_object, OFF, 0);
  
  		  Setting on automated shadow generation for this object
  		  One light source will be used. The engine will select the closest/strongest light
  		  acording to the location of the object
  		B) STATE_object_auto_add_shadows(my_object, ON, 1);
  

 

 

Go to page 1      Select API

 

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