|
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.
|