STATE_engine_create_terrain2

 

 



   This function is currently in its beta stages.
   Please use STATE_engine_create_terrain_from_bitmap()
   It has several important advantages over STATE_engine_create_terrain_from_bitmap()
  
   1) It automatically cuts large bitmaps into smaller parts
  	  The bitmap that is used to wrap over the terrain could be very big
  	  though the existing 3D cards are limited in handeling large bitmaps.
  	  Most of the 3D cards today can handle bitmaps not larget than 1024x1024
  
   2) This function is faster. The function doesnt try to minimize the number of polygons
  	  To reduce the number of polygons call STATE_group_create_reduced_copy() after creating the terrain
  
   3) The function can also accept a text file with the terrain mesh
  
  
  Parameters:
  
  	elevation_source: 
  		Currently there are two options:
  		1) A bitmap file (bmp)
  			The	brighter pixels present higher eltitude
  
  		2) an XYZ file (extension xyz)
  
  		   xyz file is a text file that contains a mesh of points x,y,z
  		   Example:
   
  			x1 y1 z01		x2 y1 z02		x3 y1 z03 .......
  			x1 y2 z11		x2 y2 z12       x3 y2 z13 .......
  				.
  				.
  				.
  				.
  			x1 Yn Zn1		x2 Yn zn2       x3 Yn zn3 .......Xn Yn Znn
  
  
  
  	terrain_bmp: 
  		The image that is put on top of the terrain.
  		This image could be very big.
  		In the resulted world this image will be split into
  		pieces according to terrain_bmp_part_width
  
  	world_dimension
  		world_dimension[0] is the length of the world along the world X axis
  				This axis is mapped to the length of the terrain bmp and to the -Y axis of
  				the XYZ file
  
  		world_dimension[1] is the length of the world along the world Y axis
  				This axis is mapped to the width of the terrain bmp and to the X axis of
  				the XYZ file
  
  		world_dimension[2] is the height of the world (max_Z-min_Z) 
  		
  		If any of the given dimensions is negative then the engine will use 
  		calculate the dimension according to the elevation_source ratio
  
  
  	add_polygons_to_create_flat_edges
  		Add polygons to the terrain edges in order to create flat edges of the terrain
  		This way the terrain is nicer to view (so that the terrain doesn't abruptly ends and the 
  		viewer walks on emty space).	It also makes the model a lot easier to integrate with other 
  		models (since the edges are all at the same height)
  		If the speed database is used then it is advised to add the surrounding polygons only
  		after running the getpoints utility.
  		possible values:
  			The number given is the width of the added border.
  			If 0 is given then no polygons are added for creating the flat square edge.
  			Common values are 1, 10, 1000000. Any positive number will be fine.
  		
  		Note that the given width is added to th given dimension. For example if the terrain dimensions given are 1000,1000,300
  		and add_polygons_to_create_flat_edges==700 then the result model will have the following dimesions 1700, 1700, 300
  
  	terrain_bmp_part_width
  		Since the terrain_bmp (the bitmap that is put on top of the terrain)
  		could be very big, there is a need to cut it into smaller pieces
  		Most of the 3D cards today can not handle bitmaps bigger than 1024x1024
  		The GeForce 4 Ti 4600 can not handle bitmaps larger than 4096x4096 
  		Anyhow, for performance sake it is best to divid the terrain bmp into
  		pieces in the size of 256x256 or 1024x1024
  		Common value for terrain_bmp_part_width are 256, 512, 1024
  		The given value must be in the power of two
  
  	max_num_of_polygons
  		Limits the created terrain to this given number. If max_num_of_polygons==0 then
  		the number of polygons will not be limited. This parameter is useful when we want to creat 
  		a terrain quicly (draft terrain ...). Some elevation sources could be highly detailed
  		In these cases creating the terrain and saving it might take a lot of time. Using this parameter
  		we can create a less detailed version first. In many cases we must put a limit to the number of polygons
  		since the terrain is used for realtime and must render quickly on all systems.
  		Note that the resulted terrain might actually have more polygons then the given max_num_of_polygons
  		For example you might set max_num_of_polygons to 50,000 and get a terrain with 51,000 polygons
  		This is normal and should happen frequently. The given limits acrually guarantee that the number of polygons
  		will close to the given limit 
  		
  	color_top_bitmap_flag
  		YES or NO.
  		Sometimes we only have a digital elevation map and no setallite image
  		In this case we use the DEM bmp also as the setallite map. In this case
  		we can ask the engine to color the gray map so it looks more like a physical map
  
    max_number_of_pixels_in_top_bmp
  		limit the size of the bitmap used. A value of 0 means no limitations.
  
  	temp_dir
  		During the function work it will write some temporary files to the disk.
  		Through this argument one can specify the temp directory to be used.
  		This parameter could be NULL (if one doesnt care where the temp files are written)
  		The function will automatically delete the temporary files once finished.
  
  	original_image_width, original_image_height
  		Through this arguments the function returns
  		the dimensions of the terrain_bmp im age
  
  	height_from_dem
  		The height of the terrain according to the diff between the max_z and the min_z
  		taken from the xyz or grd files. When a bmp is used as the source then -1 is returned
  
  	lowest_point, highest_point
  		only valid when height_from_dem!=-1
  		The X,Y,Z of the lowest and hieghest points
  
  	tfw_file
  		NULL or the tfw file
  
  
   Return Value:
  		On failure returns NULL
  		On success returns a handle to the created group
  
   See also STATE_engine_create_terrain_from_bitmap();
  
   Example: 
  		double dimensions[3]={10000,10000,500};
  		STATE_engine_create_terrain2("elevation_map.bmp", "Setellite_image.bmp",dimensions, 100000, 1024, NO, 10000, NO, NULL, "my_password");
  

 

 

Go to page 1      Select API

 

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