STATE_engine_save

 

 



   Save the 3D world as a file.
  
   Arguments:
  	file_name:
  			The file name should have the extension .wld (for text format) 
  			or .STATE (for binary format) or should be without 
  			an extension at all (.wld will be added automatically)
  			if a relative path is provided it will be relative to
  			the directory of the executable.
  
    group_to_save: The group to save. Give NULL if you would like to save the whole world.
  				   If a group handle that is not NULL is used then only the given group will be saved.
  
  	save_flags: See below.
  
   returns OK or VR_ERROR
  
   Note: 
  		1)
  		When saving the world the engine automatically calculates the vertices normal. If you set the points normal
  		yourself and you don't want the engine to overwrite it then call
  		STATE_light_calcualte_vertices_normals_automatically() before calling STATE_engine_save()
  
  		2)If the saved world is a terrain, sphere or any round surface then we suggest calling
  		  STATE_light_calcualte_vertices_normals_automatically(SET_VERTEX_NORMAL_EQUAL_TO_AVERAGE_OF_ADJACENT_POLYGONS);
  		  before doing save. This is only relvant if light will be applied on the saved world.
  		
  
   Example: 
  		  set a normal mode calculation that is good for terrain and round surfaces. This is only relvant if light
  		  will be applied on the saved world. If you do use light then we suggest you test  STATE_light_calcualte_vertices_normals_automatically()
  		  with different modes.
  		STATE_light_calcualte_vertices_normals_automatically(SET_VERTEX_NORMAL_EQUAL_TO_AVERAGE_OF_ADJACENT_POLYGONS);
  		  Save the whole world including the bitmaps that will be saved in bmp format
  		STATE_engine_save("World1.3dstate", NULL, SAVE_FLAT_BITMAP_PATH | SAVE_BITMAP_AS_BMP);
  
   possible flags: (note that we can do an OR operation between them)
#define SAVE_DEFAULT			0
#define SAVE_ONLY_WHATS_NEEDED	1   does NOT save extra resources that are not needed to the saved group. it will save only animations that are needed for the polygons in the models. Cameras backgrounds and tracks will NOT be saved
									   see also SAVE_MODELS_ONLY
#define SAVE_FLAT_BITMAP_PATH	2   Recomended. STATE World Builder always uses this flag. For every polygon the name of its bitmap wont include the path just the name. the same for animations. this is very convenient if we want to keep all the bitmap in one directory.
								   If we also save bitmaps then the save will be done with flat bitmap path no matter the value of this flag.
   The following options will save the world as a complete project including the bitmap files
   The function will make a directory called Bitmaps bellow the given path, and there it will put all the bitmaps
   The idea here is that the world becomes a "stand alone" it can be send through e-mail, put on a diskette etc ...
   using one of the bitmap flags will cause the save to be done with flat bitmap path no matter the value of this flag.
   using different kind of bitmaps type is allowed. 
#define SAVE_BITMAP_AS_JPG		4    The bitmaps are saved in a JPG format. This should be done when optimizing for space. The down side is that it would take more time to load the world. and
									   the quality of some bitmaps might suffer. If transparent bitmap have spots or that some parts are missing one can modify by hand
									   The *.flt file for that bitmap.
								      for more information about the flt files see at the bottom of this file
								       in the help appendixes

#define SAVE_BITMAP_AS_BMP		8    The bitmaps are saved in a BMP format. This should be done when we want the ability to modify the bitmaps
									   using bitmaps editors like PhtoPaint, Photoshop, Paintbrush etc ... Remember to delete the jbm file each time you modify the bitmap.
#define SAVE_BITMAP_AS_JBM		16   The bitmaps are saved in a JBM format. This is the engine internal format. This should be done when we want the loading time of the world to be as short as possible.

  see also the flag SAVE_BITMAP_OPTIMIZE below

#define SAVE_IN_MULTIPLE_FILES	32     * Not very useful. Instead of putting all the models in one file, it saves each model
									   in a separate file. This way is easier to change the world
									   by hand. In this method it is also very easy to replace components (since each one is
									   separate file.

#define	SAVE_ONLY_MODELS 64   Save the model and its bitmaps and only the animations that are currently used by
							   the model. This is the same as to call with SAVE_ONLY_WHATS_NEEDED when all the save flags are set to NO
							   ( see STATE_camera_set_save_flag() , STATE_animation_set_save_flag(0 etc ...)

#define SAVE_RELEASE 128   1-	All the polygons will be put inside module main
						   		this makes a faster save and a faster load afterwards
						   		When we load a world that was save using SAVE_RELEASE we
						   		will lose all group affiliations.
						   2-	polygons that have their release_save flag set to NO wont be saved
						   		for example some models have polygons that are used only as a bottom
						   		(applications like 3DSTATE World Builder need a bottom polygon so when
						   		we drop an objects on a floor it will know how to put it, in some models
						   		a bottom polygon is part of the model and in others (like trees) it is just an auxiliary polygon)
						   		the release_save_flag can be set by STATE_polygon_set_release_save_flag() or
						   		by specifying NO\YES in the RELEASE_SAVE field in the world text file

#define SAVE_BITMAP_OPTIMIZED 512   This option overrides the following flags SAVE_BITMAP_AS_JPG, SAVE_BITMAP_AS_BMP, and SAVE_BITMAP_AS_JBM
								    with this option all the bitmaps will be saved in jpg format
								    except those that are being used with a transparency, those will be saved
								    in BMP format. This flag is used when we want to save in jpg format
								    but we dont want the jpg format to ruin the transparency bitmaps.
								    The problem is that jpg images are not identical to the original and
								    this makes a big problem with the transparent color because instead of one background color
								    for example 255,255,255 we get several like 254,255,255 and 255,254,254 etc ...
								    the engine will only eliminate one transparent color leaving all the other nuances
								    If you didnt understand, just try to save a world using the flag SAVE_BITMAP_AS_JPG
								    and then load the saved world and look at polygons that use a transparent bitmap.
								    another way to deal with this problem is using the flt file that is saved together with each jpg bitmap
								    for more information about the flt files see at the bottom of this file
								     in the help appendixes

#define SAVE_WITHOUT_GROUPS	 1024   * Not useful. This flag is only valid when saving in the binary format (to save in binary format give a file name that has a "3DSTATE" name extension instead of "wld")
								    In many applications that use viewer mode, the STATE_group_ API is not used at all
								    In this case you might want to use this flag in order to decrease the size of the saved file.

#define SAVE_WITH_BSP_TREE_INFORMATION 2048   The use of this flag is not recommended.
											  This flag is only valid when saving in the binary format (to save in binary format give a file name that has a "STATE" name extension instead of "wld")
											  The bsp information is needed only when the world is loaded in VIEWER_MODE (the drfault mode)
											  If a world will be loaded in viewer mode without the bsp information then the
											  engine will create this information on its own. Creating the bsp tree is a lengthy operation
											  so it is better if it is done at save time rather then in load time. To conclude you should use this flag in
											  the following situation:
											  The world is meant to be used in VIEWER_MODE and this is the release version.
											  Dont use this flag if you still have to do some editing to the world in World Builder.
											  Very Important ! In many cases a world that was saved with this flag will be unusable in editor mode
											  (because in the process of creating the bsp tree many polygons have to be cut into smaller fractions)
											  so because of that you should also save another version without using this flag in case you might want in the future to
											  edit this world.

#define SAVE_WITHOUT_CALCULATING_POINT_NORMALS 4096    * Very useful (shorten save time). When saving the world the engine calculates the normal of all the points
													  Use this flag if you have modify the points normal and you dont want the engine
													  to overwrite your point normal calculations. Another reason you might want to use this flag is to speed-up
													  the time it takes to save a world. Using this flag one can reduce some significant time
													  since the normal calculations are quite a time consuming process. We don't recommend
													  using this flag for speeding the saving function because if the points normal are not calculated
													  and the world is lit then the lighting result will be inaccurate.
													  See STATE_point_get_normal() for more information. 
							

 

 

Go to page 1      Select API

 

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