STATE_engine_create_terrain_from_bitmap

 

 



   Using this function one can build an application that
   scan a map from the atlas and build a 3D world from it
   the 3D world can be 100% accurate (but never more accurate than
   the map itself ...)
   The function takes a regular windows bitmap (in 256 color format or 24bit per pixel RGB format)
   painted with gray scales and convert it into a 3d model. The 3d model is built according
   to the colors of the bitmap the more white it is the higher it is.
   (the peaks of the mountains will be much brighter than the valleys in the bitmap)
  Input params:
   bitmap_file_name:
  		The name of the bitmap that according to its colors the model is built
  		The bitmap must be in 24 bit rgb format or 8 bit per pixel format (256 colors).
  		The colors of the bitmap should be in gray scale (not a must) since
  		the function calculates height according to their brightness (sqrt (red^2 + green^2 + blue^2)  Never mind if you dont understand the calculation)
  		The bitmap could be in any size.
  		examples: "my_bitmap.bmp" ; "c:\\gs_maps\\France.bmp" ; "..\\rgb24maps\\Jerusalem.map" etc ...
  
   level_of_optimization:
  		This number is responsible to the polygon reduction level.
  		A number in the range [0 - 3000]
  		The bigger the number is the stronger the optimization
  		0 means that there is no optimization so the number of polygon in the output file
  		will be as set by the argument max_number_of_polygons
  		3000 will make such a strong optimization that the model
  		will be simplified to one flat polygon no matter what source bitmap we had !
  		common numbers that you might try are
  		0.1 , 1, 10 ,100 ,200 ,400
  		Use a big numbers if it is important to reduce as many as possible polygons
  		Use small number if the terrain model must be very detailed.
  
    max_number_of_polygons:
  		A big number makes a very detailed object
  		a small number makes a model with less polygons
  		so it can be rendered fast in real-time
  		Try 2000 to begin with and if you need more details increase this number
  		if on the other hand you need more speed when rendering, use a smaller number
  
    bitmap_to_wrap_over_handle:
  		This is a handle to the bitmap that will be used to paint the created model
  		for example this bitmap could be a texture of rocks, sand snow , grass etc ...
  		If a NULL is given, then the model will be painted according to the given legend.
  		You get the handle for the bitmap using STATE_bitmap_load()
  		Note that if you want the bitmap to repeat more than once on the model (tile mode)
  		then the dimensions of the bitmap must be in the power of two (for example 32,64,128,256,512,1024,2048 etc ... 
  		all these numbers are powers of two).
  		see also STATE_group_wrap_a_bitmap()
  
    tile_x, tile_y:
  		The numbers of time that the tile of the bitmap is to repeat itself
  		These numbers are only relevant if bitmap_to_wrap_over_handle
  		is not NULL.
  		examples: 1,1 (no tile) ; 4,4 (bitmap will repeat 16 times) ; 7,3 ; 712,1095 etc ...
  
  	legend, number_of_colors_in_legend:
  		If bitmap_to_wrap_over_handle is NULL, then
  		The created model is painted according to the given legend.
  		legend is an array of RGB colors. If for example we give
  		three colors then the first color will be the color of the bottom
  		third of the model. The second color will be the middle color.
  		the last color will be the color of the top third.
  		If NULL is given (instead of the legend array) then the
  		model is colored according to the default legend.
  		number_of_colors_in_legend is of course the number of colors that
  		the given legend array contains.
  		example: 
  			BYTE my_legend[2][3]={0,255,0,  255,255,255};
  			Here we define two colors. 0,255,0 is green.
  			255,255,255 is white. This would cause the bottom half
  			to be painted with green colors and the top half with white hues
  
  	dimensions:
  		The created model is built so its center is in the origin ( point 0,0,0 )
  		and its width is dimension[0], its length is dimension[1] and its height is dimension[2]
  		Note that if for example dimension[2]==100 (the height of the model)
  		then the model will be built from -50 to +50 (remember that the center is in the origin ...)
  		Chose the number according to the source map.
  		If for example it was a map of Israel then you should give the following dimensions
  		dimension[0]=60 (The width of Israel is 60 Km) (quit small isn't it ?)
  		dimension[1]=300 (The length of Israel is 300 Km)
  		dimension[2]=2 (The difference between the tallest mountain to the lowest place is 2 Km)
  
  	number_of_polygons_in_group:
  		This value is set by the function so it doesn't have to be initialized.
  		When the function returns it contains the number of polygons in the created model
  		This parameter is updated during the time that the function runs and can be
  		accessed by a different process to get an idea on the the function progress
  		This parameter can be used to estimate how much time the function would take
  		If it is not one of your concerns just give NULL.
  		This function can take a lot of time (if we have a huge max_number_of_polygons for example 100000)
  		so you might like to run it in a different process ,while showing
  		a progress bar. Send a pointer to a global variable
  		so that you can read its value outside the process.
  		Though it is not known in advance how much time it takes, this number give some ideas
  		at first this number will be equal to max_number_of_polygons and it will go down by one when ever
  		a polygon is reduced. Till what number it gets to depends on level_of_optimization and
  		the source bitmap itself (If the map is flatter it will be possible to reduce more polygons and vice versa)
  
   Return Value:
  		On failure returns NULL
  		On success returns a handle to the created group
  
  	Example: 
  		double dimensions[3]={20000,20000,6000};
  		DWORD terrain_group=STATE_engine_create_terrain_from_bitmap("map.bmp", 100, 3200, NULL,1,1,NULL, 0,dimensions,NULL);
  		double step[3]={0,0,-3500};
  		STATE_group_move(terrain_group, step, WORLD_SPACE);
  		STATE_camera_set_location(STATE_camera_get_default_camera(),0,0,0);
  		STATE_camera_set_direction(STATE_camera_get_default_camera(),-1,0,0);
  

 

 

Go to page 1      Select API

 

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