|
returns (OK / VR_ERROR)
It is important to check the return value
Arguments:
world_file_name: the name of the file to be loaded
examples: "my_world.wld" , "my_world.raw" , "C:\\worlds\\my_world.x"
world_directory_path: relevant only if INCLUDE_FILE is used
(INCLUDE_FILE is used in the world file if our world consist of several files)
using a different world_directory_path we can load the same
world with different models library
or we can use one models library for several worlds
examples: "", "C:\\models\\chaires\\plastic", "C:\\models\\chaires\\plastic"
bitmaps_directory_path:
using a different bitmaps_directory_path we can load the same
world with different bitmaps library
or we can use one bitmap library for several worlds
examples: "", "C:\\bitmaps1", "C:\\bitmaps2", "bitmaps"
world_mode options:
USER_DEFINED_BEHAVIOR
AUTO_BEHAVIOR01 Automatically moves the camera or an object according the arrows key
AUTO_BEHAVIOR02 Obsolete
EDITOR_MODE Dont move objects automatically. make it possible to use all the group API
DONT_USE_ZBUFFER
This option doesn't work together with EDITOR_MODE. When zbuffer is off, the
rendering will be faster but could be less accurate (things that are supposed to be hidden will sometime appear
depending on the structure of the used world). If zbuffer is on, the rendering will sometime
more accurate though slower. We suggest that you try both possibilities and choose what's best
The default is zbuffer ON. The changes in speed are not so relevant when using a 3D card (harware rendering)
The resample flags cause every bitmap that is loaded to be automatically resampled to a power of two dimensions
RESAMPLE_UP The new width and height will always be bigger than or equal than the original dimension of the bitmap
RESAMPLE_CLOSEST The new dimensions will be the closest power of two numbers to the original dimensions
RESAMPLE_DOWN The new width and height will always be smaller than or equal than the original dimension of the bitmap
ENABLE_BRIGHT_LIGHT Relevant only when 3D card is used. Makes it possible to create brighter lighting on textures
ENABLE_VERY_BRIGHT_LIGHT
DONT_CREATE_ADDITIONAL_BITMAPS When a bitmap is in jpg format the engine convert it into a bitmap and leave the bitmap on the disk so that the next
time that this world is loaded will be faster. This flag will tell the engine not to create additional bitmaps.
Instead of using this flag one can simply delete all the unneeded bitmaps before
releasing the application.
DONT_LOAD_BITMAPS If this flag is given then the world will be loaded without its bitmaps.
Bitmaps can be loaded later using STATE_bitmap_load(). To retrieve the names of the bitmaps use STATE_polygon_get_bitmap_name()
Constants for BSP data structure creation
----------------------------------------
Some background about BSP Trees
---------------------------------
The BSP (Binary Space Partition) is an internal data structure inside the engine
that is used in Viewer Mode (the default mode) in the process of rendering the world and for collision detection.
There is nothing that you need to know about this internal data structure. Its existence and operation are
hide inside the engine. Your only encounter with the BSP tree is when you wait for the engine to create it
while you load your world in the first time. When the world is loaded at the first time
the engine creates a file called world_name.bsp . When you release the world you should include
this file to save the engine from regenerating it. Feel free to omit this file from
your release version if the creation process is fast (less than 1 second)
New parameters to control the bsp construction speed and number of add polygons
------------------------------------------------------------------------------
In the past the construction of a bsp tree was a very long process
(it could even reach 12 hours and more !!!) though now it should be very fast
about one second. If however this process takes too long (you can see the duration in the log file)
or it creates too many polygons in the way then you could try and load the world with the constants
below. You should try all the three constants because sometimes the one that supposed to give fewer polygons
gives more and vice versa. PLEASE NOTE THAT YOU MUST DELETE THE BSP FILE (IF EXSITS) OTHERWISE THE BUILD_BSP CONSTANTS
WILL HAVE NO EFFECT (because if the bsp file exists the engine takes it instead of building a new one).
You can read in the log file how well the constants affected the construction of the bsp tree.
Tips on how to minimize the number of polygons that are added when the bsp tree is constructed
------------------------------------------------------------------------------------------------
1) When building your world (using World Builder or other programs)
Dont make polygons intersect one each other. For example, if you put a tree on the ground
and the bottom of the tree polygons intersect the ground then it will force the engine to split
the tree into two polygons. In order to avoid this, don't put the tree on the ground manually, instead
use World Builder tools for doing dropping an object on the ground.
2) If you have implemented tip "1" and tried to load your world with each one of the three parameters above
and still you too many polygons are added in the process then
you should try to call STATE_engine_set_bsp_precision() before loading the world.
BUILD_BSP_FAST Usually builds the BSP faster. You should check the log file to
if you get more polygons added or maybe less.
BUILD_BSP_WITH_LESS_POLYGONS Usually adds less polygons tyo the world in the buildup of the bsp tree
though this is not always the case. Usually it will also take more time to create.
BUILD_BSP_WITH_MINIMUM_POLYGONS Beware, using this parameter will increase the duration of the BSP Tree
construction significantly. If your world is big then it
might take several hours. So run your program with this parameter
and pray that by the time you get beack to work on the day after the computer
will finish loading the world
CREATE_BSP_FOR_DYNAMIC_OBJECTS This used to be the default. The default was changed since a BSP tree might add polygons to the world
NO_BSP_FOR_STATIC_WORLD The world might have less polygons but collision detection will be slower. Usually it is not recommended to use this flag.
Use the OR operation to combine several options ,for example STATE_engine_load_world("my_world.3dstate", NULL, "Bitmaps", USER_DEFINED_BEHAVIOR | EDITOR_MODE); this will load the world in editor mode
Example:
A)
int rc=STATE_engine_load_world("my_world.3dstate", NULL, "Bitmaps", USER_DEFINED_BEHAVIOR);
if(rc!=OK) {
MessageBox("Failed loading world");
lets exit the program
STATE_engine_close();
exit(-1);
}
B)
starting the engine with an empty world
STATE_engine_load_world(NULL, NULL, NULL, USER_DEFINED_BEHAVIOR);
|