射击游戏

开发平台：

Visual C++

3DSTATE.H：源码内容

/*
3D
STATE3DS TATE3DSTATE3D STATE3DSTAT E3DSTATE3DSTATE3D STATE 3DSTATE3DSTATE3DS TATE3DSTATE3DST
ATE3DSTATE3 DSTATE3DSTATE3D STATE3DSTATE3 DSTATE3DSTATE3DST ATE3DST ATE3DSTATE3DSTATE 3DSTATE3DSTATE3
DSTAT E3DST ATE3D STATE3DS TATE3 DSTAT E3DSTA TE3DSTATE 3DSTATE 3DSTA
TE 3DST ATE3D STATE3 DSTAT E3DS TATE3 DSTATE3DS TATE3 DSTA
TE3DST ATE3D STATE 3DSTATE3D STATE 3DSTA TE3DS TATE3 DSTAT
E3DSTA TE3DS TATE 3DSTATE3DSTA TE3DS TATE3 DSTAT E3DST ATE3DSTATE3DSTA
TE3DSTAT E3DST ATE3D STATE3DSTATE 3DSTA TE3DS TATE3 DSTAT E3DSTATE3DSTATE
3DSTA TE3DS TATE3 DSTATE3DS TATE3 DSTATE3DSTATE3D STATE 3DSTA
TE3D STATE 3DSTA TE3D STATE 3DSTA TE3DSTATE3DSTATE 3DSTA TE3D
STATE 3DSTA TE3DS TATE3D STATE 3DSTA TE3DS TATE3DSTATE3DSTAT E3DST ATE3
DSTATE3DSTATE 3DSTATE3DSTATE3D STATE3DSTATE3DST ATE3D STATE 3DSTA TE3DS TATE3DSTATE3DSTA
TE3DSTATE3 DSTATE3DSTATE3 DSTATE3DSTATE 3DSTA TE3DS TATE3D STATE 3DSTATE3DSTATE3D
STATE3 DSTATE3DSTAT E3DSTATE3D DSTAT E3DS TATE3 DSTAT TE3DSTATE3DSTATE
3DSTATE.h
STATE 3D engine API
Version 5.7
NOTE: There are many functions in this API. You will probably need
only a few of them. You can write a great game using only about 20
functions from this API. We suggest that you first look at some
sample code and only when you feel comfortable, take a deeper
look at this API.
The main idea
-------------
With one command you load a three dimensional world model
into the engine. With one command you create a camera
for taking pictures from inside the world.
Now all you have to do is call this function
STATE_engine_render(HWND hwnd, DWORD camera)
and voila !!! you have the picture taken using the camera
pasted on the given window !!!!
now if you modify the camera location or direction
and call the rendering function again you get movement !!!
Naming convention.
1- All the functions of this API start with STATE_
example: STATE_camera_create(char *camera_name);
2- The second word is the name of the group of function.
examples:
STATE_camera_set_location(x,y,x);
STATE_engine_increase_atmospheric_effect();
There are several groups off API commands
1- the engine API
all function starting with STATE_engine_
controls things like picture quality, atmospheric effect etc ...
2- the camera API
all function starting with STATE_camera_
controls properties of the camera like
zoom location direction etc...
3- The object API
all function starting with STATE_object_
In your world you can define objects like an airplane,
a boy, a runner, a bird etc ...
this api allows you to control their behavior.
The Other APIs are:
The Polygon API, the Point API, the group API,
the Track API, the Bitmap API, the Math API, the Utilities API,
the Animation API, the profiler API, the background API.
You can find more information at the beginning of each API.
Speed and performances
-----------------------
Once you are more familiar with the STATE API you might want to
increase your application performances. Here are some tips:
1) Read the performance tip documentation (at www.3DSTATE.com - documentations)
2) Tips for software rendering:
Do some of the following calls
STATE_engine_set_perspective_correction_accuracy(0);
STATE_engine_use_zbuffer(NO);
STATE_engine_set_automatic_quality_control();
Each of the above functions has its advantages and disadvantages
but they will all make your application run faster, read their 'help'
for more details.
*/
#ifndef STATE_H
#define STATE_H
#include <windows.h>
#ifdef __cplusplus
extern "C" {
#endif
/*
#if defined(__BORLANDC__)
#define STATE_WINAPI WINAPI
#else
#define STATE_WINAPI
#endif
*/
#ifdef STATE_STATIC_LINK
#define STATE_WINAPI
#else
#define STATE_WINAPI WINAPI
#endif
#define OK 0
#define VR_ERROR -1
//Note that YES/NO ON/OFF and TRUE/FALSE are all the same.
#define YES 1
#define NO 0
#define ON 1
#define OFF 0
#define WORLD_SPACE 0
#define OBJECT_SPACE (WORLD_SPACE+1)
#ifndef CAMERA_SPACE
#define CAMERA_SPACE (WORLD_SPACE+2)
#endif
#define PLAYER_CONTROL 1
#define COMPUTER_CONTROL 2
// used for STATE_camera_save()
#define CAMERA_DESCRIPTOR_SIZE 53 //Number of DWORDs (212 bytes)
#define FORBID_DIRECTX
#define EDGE_NOT_SEEN 1
#define EDGE_FULLY_SEEN 2
#define EDGE_PARTIALLY_SEEN 3
// Automatic movement constants == "Chasing"
// --------------------------
// In the wld file we have the following lines that are relevant
// to the Automatic movement.
// TRACK: track_name track_offset //chase name could be NO_TRACK if ...
// SPEED: track_speed // track speed is also used in CHASE_PRECISE and CHASE_FLEXIBLE
// in those cases it is the distance behind the chased object
// CHASE: dynamic_object_to_chase chase_offset
// CHASE_TYPE: chase_type tracking_softness //tracking_softness is a number between 0 and 1.
// Below are the values that could appear in chase_type.
// relevant fields: none
// The NO_CHASE Const Must be 0.
#define NO_CHASE 0 // doesn't move at all. Control is through software
// relevant fields: dynamic_object_to_chase, chase_offset
#define CHASE_LOCATION 2 // trace only location. Only the line "CHASE: object_to_chase x y z " is relevant
// The three numbers are the offset from the object being chased
// relevant fields: dynamic_object_to_chase, chase_offset, chase_distance
#define CHASE_PRECISE 3 // trace location and cord system. The track is ignored
// relevant fields: dynamic_object_to_chase, chase_offset, chase_distance, tracking_softness
#define CHASE_FLEXIBLE 4 // trace location and direction with a delay
// not available yet
#define CHASE_ON_TRACK (5+CHASE_TRACK_FAMILY) // chase the object to be chased but doesn't go out of the track line
// not available yet
#define CHASE_INSIDE_TRACK_BOUNDING_BOX 6 // chase the object to be chased but doesn't go out from the track bounding box
// relevant fields: track_name, track_offset, speed, tracking_softness
#define CHASE_TRACK (7+CHASE_TRACK_FAMILY) // just advance on the track according to the speed with out chasing anyone
// relevant fields: track_name, track_offset, speed, tracking_softness
#define CHASE_TRACK_AIRPLANE (8+CHASE_TRACK_FAMILY) // like CHASE_TRACK just with an airplane movements
//Not a chase type but a chase family
//Makes it possible to do things like if(chase_type & CHASE_TRACK_FAMILY) ...
#define CHASE_TRACK_FAMILY 128
#define CHASE_PHYSICS 9 //Moves the object according to the physics params (that is
// speed,friction, elasticity, max_speed)
// Orientation values
#define ORIENTATION_UNKNOWN 0
#define ORIENTATION_TOP 1
#define ORIENTATION_BOTTOM 2
#define ORIENTATION_FRONT 4
#define ORIENTATION_BACK 8
#define NO_TRACK 0
#ifdef STATE_EXPORTS
#define STATE_IMPORT __declspec(dllexport)
#else
#define STATE_IMPORT __declspec(dllimport)
#endif
#ifdef STATE_STATIC_LINK
#define STATE_IMPORT
#endif
#ifdef STATE_STATIC_LINK
#define STATE_stdcall
#else
#define STATE_stdcall WINAPI
#endif
//--------------------------------------------------------//
//=========== T H E E N G I N E A P I ===============//
//--------------------------------------------------------//
// This API controls things like picture quality, atmospheric effect etc ...
// world_mode options (for function STATE_engine_load_world() )
#define USER_DEFINED_BEHAVIOR 0
#define AUTO_BEHAVIOR01 1 //JAPPLIC_ID
#define AUTO_BEHAVIOR02 2 //CORE_APPLIC // NOTE AUTO_BEHAVIOR02 is obsolete
#define EDITOR_MODE 4
#define DONT_USE_ZBUFFER 8 //This option doesn't works together with EDITOR_MODE. When zbuffer is off
// rendering will be faster but 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
// be accurate though slower. We suggest that you try both possibilities and choose what's best
// The default is zbuffer ON.
////The resample flags cause every bitmap that is loaded to be automatically resampled to a power of two dimensions
//Note that since version 3.0 all the bitmaps that are not in the power of two are automatically resampled (with RESAMPLE_CLOSEST).
#define RESAMPLE_UP 16 //The new width and height will always be bigger than or equal than the original dimension of the bitmap
#define RESAMPLE_CLOSEST 32 //The new dimensions will be the closest power of two numbers to the original dimensions
#define RESAMPLE_DOWN 64 //The new width and height will always be smaller than or equal than the original dimension of the bitmap
#define MIPMAP_DISABLE 0 //The default
#define MIPMAP_STABLE 128 //Bitmaps will look more stable (The pixels wont "swim")
//though the resolution will be a little bit lower
#define MIPMAP_RESOLUTION 512 //This option prefers better resolution upon stable bitmaps
#define MIPMAP_NORMAL 1024//An average between MIPMAP_STABLE and MIPMAP_RESOLUTION
#define ENABLE_BRIGHT_LIGHT 2048 //Relevant only when 3D card is used.
#define ENABLE_VERY_BRIGHT_LIGHT 4096
#define CREATE_BSP_FOR_DYNAMIC_OBJECTS 8192
#define NO_BSP_FOR_STATIC_WORLD 16384
#define DONT_CREATE_ADDITIONAL_BITMAPS 32768
#define DONT_LOAD_BITMAPS 65536
#define OUTPUT_RENDER_LOCATIONS 131072 //The location from where render is done (the location of the camera)
//Will be output to a file named visited_points.txt
//This file is used with STATE_engine_create_speed_database()
#define BUILD_BSP_FAST 262144//Usually builds the BSP faster. You should check the log file to
//if you get more polygons added or maybe less.
#define BUILD_BSP_WITH_LESS_POLYGONS 524288//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.
#define BUILD_BSP_WITH_MINIMUM_POLYGONS 786432//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
// For checking if a handle is legal (for example a camera handle) you can do one of the two:
// 1- call the function STATE_camera_is_camera(handle, "my_test");
// 2- Use the macro IS_CAMERA. The advantage of the macro is that you can
// replace it with an empty macro on your release program.
// See more details next to the declaration of function STATE_camera_is_camera()
#define IS_CAMERA(camera_handle,function_name) STATE_camera_is_camera(camera_handle,function_name)
#define IS_OBJECT(object_handle,function_name) STATE_object_is_object(object_handle,function_name)
#define IS_GROUP(group_handle,function_name) STATE_group_is_group(group_handle,function_name)
#define IS_TRACK(track_handle,function_name) STATE_track_is_track(track_handle,function_name)
#define IS_POLYGON(polygon_handle,function_name) STATE_polygon_is_polygon(polygon_handle,function_name)
#define IS_LIGHT(light_handle,function_name) STATE_light_is_light(light_handle,function_name)
#define IS_POINT(point_handle,function_name) STATE_point_is_point(point_handle,function_name)
#define IS_BITMAP(bitmap_handle,function_name) STATE_bitmap_is_bitmap(bitmap_handle,function_name)
#define IS_ANIMATION(animation_handle,function_name) STATE_animation_is_animation(animation_handle,function_name)
#define IS_BACKGROUND(background_handle,function_name) STATE_background_is_background(background_handle,function_name)
#define IS_3D_ANIMATION(animation3d_handle,function_name) STATE_3D_animation_is_3D_animation(animation3d_handle,function_name)
#define IS_3D_SEQUENCE(sequence3d_handle,function_name) STATE_3D_sequence_is_3D_sequence(sequence3d_handle,function_name)
// This function puts the image seen from the camera on the given window
// The rendering operation is not automatic after every API function
// This way we can save lots of CPU time by calling a group of API function
// followed by only one call to STATE_engine_render(). (This function takes lots of
// CPU time while all the other are very fast to execute)
STATE_IMPORT int STATE_WINAPI STATE_engine_render(HWND hwnd, DWORD camera);
//exactly like STATE_engine_render() only easier to use
// if you are working with MFC
//STATE_IMPORT void STATE_WINAPI STATE_engine_render_on_cwnd(void *pointer_to_CWnd_object, void *camera);
// 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);
STATE_IMPORT int STATE_WINAPI STATE_engine_load_world(char *world_file_name, char *world_directory_path, char *bitmaps_directory_path, int world_mode);
// The loaded world will be add to the existing world
// the given position indicates where the origin (note that the origin is 0,0,0 and not the center of the world)
// of the added world will be located
// returns a handle to the group that encapsulates the added world
// if an error occurred it will return NULL
// It is important to check the return value
// Note that usually you will call STATE_group_set_location(added_world_grp, center_position);
// after calling STATE_engine_add_world() to move the center of the added world
// to its place. Not calling STATE_group_set_location() will put the origin
// of the added world in the location as given by the position argument. Note that this is different from moving the center of the world to
// the given position
//
// The function is relevant only for EDITOR_MODE. For VIEWER_MODE (the default mode)
// use STATE_object_create_from_file() instead.
STATE_IMPORT DWORD STATE_WINAPI STATE_engine_add_world(char *world_file_name, char *world_directory_path, char *bitmaps_directory_path, double position[3]);
//The same as STATE_engine_add_world() the only difference
//is that using this command the engine will also load general settings as the fog color and intensity.
DWORD STATE_WINAPI STATE_engine_add_world_with_settings(char *world_file_name, char *world_directory_path, char *bitmaps_directory_path, double position[3]);
// returns YES if no world is loaded into the engine
// otherwise returns NO
STATE_IMPORT int STATE_WINAPI STATE_engine_is_engine_empty(void);
STATE_IMPORT int STATE_WINAPI STATE_engine_is_editor_mode(void);
// change the resolution of the screen.
// bits_per_pixel is 8 or 16 or 24
// returns OK or VR_ERROR
STATE_IMPORT int STATE_WINAPI STATE_engine_set_resolution(int width, int height, int bits_per_pixel);
// returns the resolution of the screen in the three arguments.
// returns OK or VR_ERROR
STATE_IMPORT int STATE_WINAPI STATE_engine_get_resolution(int *width, int *height, int *bits_per_pixel);
// Changes the screen graphics mode.
// The resolution is not modified (only the color depth).
//
// Important:
// The software rendering works much faster at 16bit color depth.
// If your end users might not have a 3D Card you should consider
// to call STATE_engine_set_color_depth() at the beginning of the program to set 16bit mode color depth.
// When the program exits the engine will switch back to what ever mode was before
//
// Parameters:
// bits_per_pixel is 8 or 16 or 24
//
// Return Value:
// Returns OK or VR_ERROR
STATE_IMPORT int STATE_WINAPI STATE_engine_set_color_depth(int bits_per_pixel);
//The log window is the small window with the progress bar that appears
//while the engine is loading. The reason it is called the Log Window (and not
//the progress window for example ...) is that in the first versions of the engine this window
//was a lot bigger and it included some of the engine log as now appear in the STATE.log file
//
// Hides the log window
STATE_IMPORT void STATE_WINAPI STATE_engine_hide_log_window(void);
//Makes the log window visible (The default)
STATE_IMPORT void STATE_WINAPI STATE_engine_set_log_window_visible(void);
//Returns YES or NO. YES if the log window is visible.
STATE_IMPORT int STATE_WINAPI STATE_engine_is_log_window_visible(void);
// On the log window there are two fields that has to do with the progress bar
// one field represent the current progress and the other the target number
// that the progress should reach.
STATE_IMPORT int STATE_WINAPI STATE_engine_get_log_window_progress(void);
STATE_IMPORT int STATE_WINAPI STATE_engine_get_log_window_target(void);
STATE_IMPORT void STATE_WINAPI STATE_engine_set_log_window_progress(int value);
STATE_IMPORT void STATE_WINAPI STATE_engine_set_log_window_target(int value);
STATE_IMPORT void STATE_WINAPI STATE_engine_log_window_minimize(void);
//Add text to the log window
STATE_IMPORT void STATE_WINAPI STATE_engine_log_window_output(char *text);
//Delete the old text and put the new text instead.
STATE_IMPORT void STATE_WINAPI STATE_engine_log_window_set_text(char *new_text);
//Set the title of the log window
STATE_IMPORT void STATE_WINAPI STATE_engine_log_window_set_title(char *new_caption);
//Obsolete
STATE_IMPORT HWND STATE_WINAPI STATE_engine_log_window_get_hwnd(void);
// Delete all the text in 3DSTATE log files
// There are two log files. 3dstate.log and error.log.
STATE_IMPORT void STATE_WINAPI STATE_engine_clear_STATE_log_files(void);
//Write the given text into the 3dstate.log file.
STATE_IMPORT void STATE_WINAPI STATE_engine_write_to_log_file(char *text);
// (x,y) is a point in the rendering window
// usually we get this point from the events like OnLButtonDown()
// returns OK if a polygon was marked
// returns VR_ERROR if there is no polygon in that spot
STATE_IMPORT int STATE_WINAPI STATE_engine_mark_polygon_at_point(int x, int y);
// Gets a two dimensional point (x,y) which is a point in the rendered window
// Usually we get this point from events like OnLButtonDown()
// The function returns the corresponding three dimensional point
// in the 3D world. Note that if the 2D point that is given is located where there is no
// polygon then the function will return VR_ERROR. This is because the point
// in 3D is in infinity ... in that case the 3d point retrieved (result[] )
// will hold a point in that direction that is one million units away
// from the camera.
//
// Arguments:
// x,y - A two dimensional point in the rendered window
// result - a point x,y,z in the 3D world which corresponds to the given 2D point.
// When calling the function to content of this argument is not relevant.
// The function calculate the 3D point and returns it through this argument.
//
// selected_object_handle - If the pixel X,Y (the 2D point) on the rendered window is taken from
// a dynamic object then this argument will hold the handle to this object.
//
//
// selected_polygon_handle - a handle to a polygon that corresponds with the given 2D point.
// Return Value: OK or VR_ERROR
//
// See also STATE_engine_2D_point_to_3D_point_on_plane()
//
//
// Remark:
// Note that this function doesn't take a camera handle as one of its parameters.
// Note also that the result of the operation is dependent on the current camera that is used.
// The engine will use the current camera (The camera that was used in the last render)
// In most of the cases this is the right thing to do. In the case when you want
// to use a different camera for the calculation then use STATE_camera_set_current()
// Before calling this function.
//
// Example:
// int x=10, y=20;
// double result[3];
// DWORD selected_object_handle;
// DWORD selected_polygon_handle;
// int return_code;
// return_code=STATE_engine_2D_point_to_3D(x,y,result, &selected_object_handle, &selected_polygon_handle);
STATE_IMPORT int STATE_WINAPI STATE_engine_2D_point_to_3D(int x, int y, double result[3], DWORD *selected_object_handle, DWORD *selected_polygon_handle);
// The function associates a 2D point on the rendered window and a plane in the 3D world.
// This function is useful for example when dragging an object with the mouse.
// Once we click on the object we can get the polygon that was clicked using STATE_engine_2D_point_to_3D()
// Now when dragging the object the mouse could move outside the object and then we wouldn't be able to use
// STATE_engine_2D_point_to_3D(). By using this function we tell the engine that the 2D point
// is related to a specific polygon even if the 2d coords are outside this polygon.
// Detailes:
// Gets a two dimensional point (x,y) which is a point in the rendered window
// Usually we get this point from events like OnLButtonDown()
// The function returns the corresponding three dimensional point
// in the 3D world that is on the given plane.
//
// Arguments:
// x,y - A two dimensional point in the rendered window
// p3D - a point x,y,z in the 3D world which corresponds to the given 2D point and is located on the given plane.
// When calling the function to content of this argument is not relevant.
// The function calculate the 3D point and returns it through this argument.
//
// polygons_plane - A plane in the 3D World (doesnt have to be a plane of any specific polygon)
// The result p3D point will always be on this plane.
//
// Return Value: OK or VR_ERROR
//
// See also STATE_engine_2D_point_to_3D_point(), STATE_polygon_get_plane()
//
// Example:
// int x=10, y=20;
// double result[3];
// the_plane[0]=10; //This is a random plane. Instead we could have used STATE_polygon_get_plane()
// the_plane[1]=11;
// the_plane[2]=12;
// the_plane[3]=14;
// int return_code;
// return_code=STATE_engine_2D_point_to_3D(x,y, the_plane ,result);
STATE_IMPORT int STATE_WINAPI STATE_engine_2D_point_to_3D_point_on_plane(int x, int y, double polygons_plane[4],double p3d[3]);
// Gets a point in the world and returns the
// matching point on the screen.
// Arguments:
// p2D
// On call p2D[2] has no meaning
// on exit it will contain the 2D point.
//
// p3D
// on call p3D[3] should be the 3D point in the world.
//
// Return value:
// returns -1 if an error occurred. p2D contains 0,0
// returns 0 if every thing is OK. p2D contains a valid result
// returns 1 if the point is out of the window. p2D contains a valid result.
// returns 2 if the point is behind the camera. p2D contains a valid result though not accurate
// returns 3 if both: behind the camera and out of the window. p2D contains a valid result though not accurate
//
// Remark:
// Note that this function doesn't take a camera handle as one of its parameters.
// Note also that the result of the operation is dependent on the current camera that is used.
// The engine will use the current camera (The camera that was used in the last render)
// In most of the cases this is the right thing to do. In the case when you want
// to use a different camera for the calculation then use STATE_camera_set_current()
// Before calling this function.
//
STATE_IMPORT int STATE_WINAPI STATE_engine_3D_point_to_2D(double p3D[3], int p2D[2]);
// Note that picture quality that is set by the following
// functions is related to the current camera only (the camera that was
// last used by STATE_engine_render().
STATE_IMPORT void STATE_WINAPI STATE_engine_set_picture_quality(int quality);
STATE_IMPORT int STATE_WINAPI STATE_engine_get_picture_quality(void);
STATE_IMPORT void STATE_WINAPI STATE_engine_increase_picture_quality(void);
STATE_IMPORT void STATE_WINAPI STATE_engine_decrease_picture_quality(void);
// This function deals with fine tuning the engine performances
// This function checks if it is possible to increase the quality without
// slowing down rendering time. The return value is YES or NO.
// Returns NO if couldn't increase quality without hurting performances.
// Returns YES if succeeded to do so.
// Usually this function will return NO. If it return YES
// then it is better if we dont change the graphics quality our selves by calling STATE_engine_set_picture_quality()
// Note that this function is very slow (about one third of a second !)
// Usually you would like to call it before the first render
// for calibration-optimization. Call this function with the same parameters you
// call STATE_engine_render();
// Arguments:
// hwnd: The window that is used when calling STATE_engine_render()
// NULL could be used if rendering is performed on the default rendering window
// camera: The camera that is used in STATE_engine_render().
STATE_IMPORT int STATE_WINAPI STATE_engine_set_automatic_quality_control(HWND hwnd, DWORD camera_handle);
//The engine will not use bitmaps. All the polygon will be drawn using color fill.
//This rendering mode does not have any effect when using hardware rendering.
//Using this function will make rendering a lot faster.
// On the whole this function is not very useful
//See also STATE_engine_set_color_fill_rendering_mode(), STATE_engine_set_normal_rendering_mode()
STATE_IMPORT void STATE_WINAPI STATE_engine_set_color_fill_rendering_mode(void);
//The engine will not use bitmaps. Only the wire frame of the polygons will be drawn.
//This rendering mode does not have any effect when using hardware rendering.
//Using this function will make rendering a lot faster.
// On the whole this function is not very useful
//See also STATE_engine_set_color_fill_rendering_mode(), STATE_engine_set_normal_rendering_mode()
STATE_IMPORT void STATE_WINAPI STATE_engine_set_wire_frame_rendering_mode(void);
//Reset the engine to its normal way of rendering (the default)
//See also STATE_engine_set_wire_frame_rendering_mode(), STATE_engine_set_color_fill_rendering_mode()
STATE_IMPORT void STATE_WINAPI STATE_engine_set_normal_rendering_mode(void);
//Obsolete
//STATE_IMPORT void STATE_WINAPI STATE_engine_toggle_rendering_mode(void);
//Obsolete
//STATE_IMPORT void STATE_WINAPI STATE_engine_toggle_wire_frame_flag(void);
//About the brightness functions
//--------------------------------
//
//We dont recommend using these functions any more since they work differently in software
//and hardware rendering.
//Use the brightness demo in the SDK to see how the change in brightness effect
//the rendered image. Note that the effect is different when using hardware
//rendering. We recommend to use these functions only if your application
//is not planed to run with hardware rendering.
//Obsolete
STATE_IMPORT void STATE_WINAPI STATE_engine_set_default_brightness(void);
//Obsolete
STATE_IMPORT void STATE_WINAPI STATE_engine_increase_brightness(void);
//Obsolete
STATE_IMPORT void STATE_WINAPI STATE_engine_decrease_brightness(void);
//Obsolete
// Zero means according to what is set in the input world file.
// a positive number means make brighter. a negative number means darker
// values should be in the range -64 till +64
STATE_IMPORT void STATE_WINAPI STATE_engine_set_brightness(int value);
//Obsolete
STATE_IMPORT int STATE_WINAPI STATE_engine_get_brightness(void);
//Increases the fog effect.
STATE_IMPORT void STATE_WINAPI STATE_engine_increase_atmospheric_effect_intensity(void);
//Decreases the fog effect.
STATE_IMPORT void STATE_WINAPI STATE_engine_decrease_atmospheric_effect_intensity(void);
//Set the fog intensity to the engine default.
STATE_IMPORT void STATE_WINAPI STATE_engine_set_default_atmospheric_effect_intensity(void);
//Returns the current fog intensity.
// 1 means according to what is set in the input world file.
// 2 means the atmospheric effect intensity is doubled.
// 0.5 means atmospheric effect intensity is half.
// 0 means that atmospheric effect is off.
STATE_IMPORT double STATE_WINAPI STATE_engine_get_atmospheric_effect_intensity(void);
// Set the fog intensity.
// Using fog is one of the easiest ways to increase your game speed.
// The more intensed fog, the higher FPS (frames per seconds) you should expect.
// Note however that if you do not use fog at all or use an unnoticeable intensity of fog
// then it is better to shut off fog entirely (by calling STATE_engine_set_atmospheric_effect_intensity(0) )
//
// Parameters:
//
// fog_intensity
// 1 means according to what is set in the input world file.
// 2 means the atmospheric effect intensity is doubled.
// 0.5 means atmospheric effect intensity is half.
// 0 means that atmospheric effect is off.
//
// Note that if you test this function and suddenly you don't anything in your world that
// usually means that you are using a too strong fog intensity. Try calling with a smaller value
// till you get the desired effect.
STATE_IMPORT void STATE_WINAPI STATE_engine_set_atmospheric_effect_intensity(double fog_intensity);
//Changes the color of the fog between some pre selected values.
STATE_IMPORT void STATE_WINAPI STATE_engine_toggle_atmospheric_effect(void);
// Set the color of the fog.
// Even if you don't use fog, you might want to use this function
// to reduce visible cracks seen between adjacent polygons. For that matter one should use a color that is as close as possible
// to the dominate world in the world
//
// This function also set automatically the background color to the fog color (see STATE_engine_set_background_color() )
//
// Here are some tips for getting natural results:
// 1) Choose a color that is very close to the dominant color in your world.
// for example if your world is a desert then your fog color (atmosphere color) should
// lean towards the color of sand.
//
// 2) Choose colors where the red==green==blue .Shades of gray look best
// even if you want to have a blue fog color then don't use 0,0,255
// this will be very unnatural ... Colors such as (180,200,220) where the blue is a little bit
// higher than the rest, will give a much better effect.
// Always try:
// Black - (0,0,0)
// Gray - (128,128,128) or any shade of gray
//
// See also STATE_engine_set_background_color()
STATE_IMPORT void STATE_WINAPI STATE_engine_set_atmospheric_effect(int red, int green, int blue);
//Returns the current fog color
STATE_IMPORT void STATE_WINAPI STATE_engine_get_atmospheric_effect(int *red, int *green, int *blue);
//Sets the color of the background. The background is the color of the window on which
//the rendering is done. If the rendered image does not cover the whole window then the
//background color will be seen in the area where there are no polygons.
STATE_IMPORT void STATE_WINAPI STATE_engine_set_background_color(int red, int green, int blue);
//Returns the current background color. For more information see STATE_engine_set_background_color()
STATE_IMPORT void STATE_WINAPI STATE_engine_get_background_color(int *red, int *green, int *blue);
//This function will not influance hardware rendering
// Toggles between automatic perspective correction and
// no perspective correction(fastest).
STATE_IMPORT void STATE_WINAPI STATE_engine_toggle_automatic_perspective_correction(void);
//This function will not effect hardware rendering
// Cancels automatic mode and toggle between several accuracy modes.
STATE_IMPORT void STATE_WINAPI STATE_engine_toggle_perspective_correction_accuracy(void);
//The following functions (color accuracy) are not extremely useful, they can be used to
//speed up software rendering and has little effect when doing hardware rendering.
//The engine has the capability to render far object using color fill instead of using
//the polygon bitmap. This can speed up software rendering. When using color fill instead
//of bitmap it will reduce the "color accuracy"
//
//Set the distance from the viewer that is needed so that the engine will use
//color fill instead of using the bitmap of the polygon to its default value.
STATE_IMPORT void STATE_WINAPI STATE_engine_set_default_far_objects_color_accuracy(void);
//Increase the distance from the viewer that is needed so that the engine will use
//color fill instead of using the bitmap of the polygon.
//See also STATE_engine_set_default_far_objects_color_accuracy()
STATE_IMPORT void STATE_WINAPI STATE_engine_increase_far_objects_color_accuracy(void);
//Decrease the distance from the viewer that is needed so that the engine will use
//color fill instead of using the bitmap of the polygon.
//See also STATE_engine_set_default_far_objects_color_accuracy()
STATE_IMPORT void STATE_WINAPI STATE_engine_decrease_far_objects_color_accuracy(void);
// Returns a number in the range [0, 31]
//See also STATE_engine_set_default_far_objects_color_accuracy()
STATE_IMPORT int STATE_WINAPI STATE_engine_get_far_objects_color_accuracy(void);
//The value should be in the range [0, 31].
//For more information please see STATE_engine_set_default_far_objects_color_accuracy()
STATE_IMPORT void STATE_WINAPI STATE_engine_set_far_objects_color_accuracy(int value);
//The engine can ignore polygons that are far away in order to speed up rendering.
//For example if our character in a game enters a building we could use
//this function to tell the engine that it doesnt have to work on far polygons
//that are outside the building ...
//When using fog the engine automatically ignores polygon that are totaly inside the
//fog.
STATE_IMPORT void STATE_WINAPI STATE_engine_set_default_culling_depth(void);
//Increases the distance from the viewer in which the engine ignores polygons.
STATE_IMPORT void STATE_WINAPI STATE_engine_increase_culling_depth(void);
//Decreases the distance from the viewer in which the engine ignores polygons.
STATE_IMPORT void STATE_WINAPI STATE_engine_decrease_culling_depth(void);
//Returns a number that represent the distance from the viwer in which
//the engine starts to ignore polygons.
//The given value is in the range 0-31
STATE_IMPORT int STATE_WINAPI STATE_engine_get_culling_depth(void);
// The given value should be in the range [0 - Infinity ]
// Tipical values are 15, 20 ,30
STATE_IMPORT void STATE_WINAPI STATE_engine_set_culling_depth(int value);
//This function is very important. It checks whether it is possible to move
// between one point to another in the 3D world without intersecting any polygon.
// If the movement is possible it returns YES else returns NO
// If movement is not possible it returns the blocking polygon
// and the intersection point.
// Note that the normal of the blocking surface is N=( plane[0], plane[1], plane[2])
// If the return value is NO and blocking_object==NULL
// it means that what blocks us is the static part of the world
// Note that the function will be faster if the distance between the start_location and the end_location is smaller
// Important NOTE:
// Polygons have only one side.
// So there is a question what to do when we want to
// go through a polygon that is not visible to the camera
// (the camera sees only its back )
// The solution that we chose is that: (can be changed using STATE_engine_ignore_back_faced_polygons_for_collision_detection() )
// In Viewer (STATE_load_world() without EDITOR_MODE) mode we dont care if you see the polygon or not
// you can never go through it !
// In Editor mode we apply the following.
// If the current camera sees the polygon then it is like
// a solid wall (nothing can go through the wall and nothing can come from the wall)
// If the current camera doesn't see the polygon then it is as if
// the polygon doesn't exist at all.
// If you didnt get it, we will try again.
// say A is a point in space in the front of a polygon and B is a point on the back side
// of that polygon (The front is the side of the normal where you see the vertex in counterclockwise order)
// then if the location of the camera is in the side of A then
// one cant move not from A to B nor form B to A.
// if the current camera is in the side of B
// then it is possible to move both from A to B and from
// B to A.
// Note that the result is insensitive to the direction
// of movement ( start_point to end_point or the other way around)
// IMPORTANT:
// If you want to move the camera from A to B. Lets say there is a one sided polygon
// on the way that doesn't allow the movement. Now watch this one, there is a big
// difference between the following options
// I- moving the camera to B and then asking STATE_engine_is_movement_possible()
// II- asking STATE_engine_is_movement_possible() while we are in A
// In the first case we would get YES (error)
// In the second case we would get the correct answer - NO
// The reason for that is that if the camera is at point B then from point
// B the polygon is not seen (we see only its back side which is invisible)
// and if the obstacle is not seen then the movement is allowed !
//
// Arguments:
//
// start_location:
// The x,y,z coordinate if the starting point
//
// end_location:
// The x,y,z coordinate if the end point
//
// intersected_polygon: If the line starting from start_point intersects a polygon in the world then
// the handle to this polygon will be returned through this argument
//
// intersection: The x,y,z coordinate of the intersection point.
//
// blocking_object: If the intersected_polygon belongs to a dynamic object (see the STATE_object API) then
// the handle to this object will be returned through this argument.
//
//
// Remark:
// Note that this function doesn't take a camera handle as one of its parameters.
// Note also that the result of the operation is dependent on the current camera that is used.
// The engine will use the current camera (The camera that was used in the last render)
// In most of the cases this is the right thing to do. In the case when you want
// to use a different camera for the calculation then use STATE_camera_set_current()
// Before calling this function.
//
//
//
// Example:
// double start_location[3]={10,0,0};
// double end_location[3]={10,0,1000};
// double intersection[3];
// DWORD intersected_polygon;
// DWORD blocking_object;
// int rc;
// rc=STATE_engine_is_movement_possible(start_location, end_location, &intersected_polygon, intersection, &blocking_object);
// if(rc==NO) .... //Collision
// else .... //no collision
//
// See also: STATE_engine_ignore_back_faced_polygons_for_collision_detection(),
// STATE_engine_ignore_dynamic_objects_for_collision_detection()
//
STATE_IMPORT int STATE_WINAPI STATE_engine_is_movement_possible(double start_location[3], double end_location[3], DWORD *intersected_polygon, double intersection[3], DWORD *blocking_object);
// This function is only relevant for the way collision detection functions work (mainly STATE_engine_is_movement_possible() ).
// By default STATE_engine_is_movement_possible() acts as follows:
// VIEWER_MODE (the default mode): does not ignore polygons that are back-facing the camera (if a polygon is back facing the camera it could still cause collision and become the blocking polygon when calling STATE_engine_is_movement_possible() )
// EDITOR_MODE : Polygons back facing the camera are ignored and do not participate in the collision detection.
// To change these defaults one can use this function.
//
// Among the collision detection functions that are influenced by STATE_engine_ignore_dynamic_objects_for_collision_detection() are:
// STATE_engineobject_is_movement_possible(), STATE_engine_2D_point_to_3D(), STATE_engine_get_object_at_point_2D().
// STATE_engine_get_polygon_at_point_2D(), STATE_object_drop_down() and other functions that is sensing the shape of the world
// and that its result is dependent on the shape of the world
//
// Example:
//
// //In editor mode this will change the default setting and will cause STATE_engine_is_movement_possible() to
// //consider all the polygons for collision purposes. This might be useful if you are writing a game in EDITOR_MODE
// STATE_engine_ignore_back_faced_polygons_for_collision_detection(NO);
//
// See also: STATE_engine_ignore_dynamic_objects_for_collision_detection()
STATE_IMPORT void STATE_WINAPI STATE_engine_ignore_back_faced_polygons_for_collision_detection(int YES_or_NO);
// This function is only relevant for the way collision detection functions work.
// The function is used for making collision detection checks that exclude all dynamic objects
// For example, we might use STATE_engine_is_movement_possible() to measure the altitude of an aeroplane to the ground
// (We take the plane location and the same point just with a very low Z value to be used as a point below the plane
// then we call STATE_engine_is_movement_possible() and check collision between those two points)
// For the matter of this check we do not care for the dynamic objects in the world and above all we don't want
// to get wrong altitude measurment if there is any dynamic object between the our plane and the ground)
// Calling STATE_engineobject_is_movement_possible() after calling STATE_engine_ignore_dynamic_objects_for_collision_detection(YES)
// Will have the same effect as the following commands
//
// disable_all_objects_that_are_not_currently_disabled()
// STATE_engine_is_movement_possible()
// enable_objects_that_were_disabled() //restore the enabled objects
//
// The default is NO, which means that all the non-disabled objects are included in collision detection tests
//
// Among the collision detection functions that are influenced by STATE_engine_ignore_dynamic_objects_for_collision_detection() are:
// STATE_engineobject_is_movement_possible(), STATE_engine_2D_point_to_3D(), STATE_engine_get_object_at_point_2D().
// STATE_engine_get_polygon_at_point_2D(), STATE_object_drop_down() and other functions that is sensing the shape of the world
// and that its result is dependent on the shape of the world
//
//
// Example:
//
// STATE_engine_ignore_dynamic_objects_for_collision_detection(YES);
//
STATE_IMPORT void STATE_WINAPI STATE_engine_ignore_dynamic_objects_for_collision_detection(int YES_or_NO);
// if movement possible returns YES else returns NO
// If movement is not possible it returns the plane equation Ax+By+Cz+D=0
// and the intersection point.
// Note that the normal of the blocking surface is N=( plane[0], plane[1], plane[2])
// If the return value is NO and blocking_object==NULL
// it means that what blocks us is the static part of the world
// see also remarks on STATE_engine_is_movement_possible()
//
// Remark:
// Note that this function doesn't take a camera handle as one of its parameters.
// Note also that the result of the operation is dependent on the current camera that is used.
// The engine will use the current camera (The camera that was used in the last render)
// In most of the cases this is the right thing to do. In the case when you want
// to use a different camera for the calculation then use STATE_camera_set_current()
// Before calling this function.
//
//
STATE_IMPORT int STATE_WINAPI STATE_engine_is_movement_possible_camera_space(double start_location[3], double end_location[3], DWORD *intersected_polygon, double intersection[3], DWORD *blocking_object);
//Counts how many polygons we will cross going from point1 to point2
//in addition it calculates the average normal of all the polygons between the two points
//
// Parameters:
//
// point1,point2: A line (actually a segment) starting at point1 and ending at point2
//
// combined_normal: The combined normal of all the intersected polygons.
// if for example we try to move through the corner of a room.
// The corner point is created from three intersectiong planes
// The combined normal will be the avareage of the three normals.
//
// Return value: The number of polygons that are intersected when going from point1 to point2
//
// Example:
// double point1[3]={10,0,0};
// double point2[3]={100,200,300};
// double combined_normal[3];
// int num_of_collisions;
// num_of_collisions=STATE_engine_get_number_of_collisions(point1, point2, combined_normal);
STATE_IMPORT int STATE_WINAPI STATE_engine_get_number_of_collisions(double point1[3], double point2[3], double combined_normal[3]);
// Gets a two dimensional point (x,y) which is a point on the rendered window
// (Usually we get this point from events like OnLButtonDown() )
// If there is a dynamic object at this location (on the rendered image) then this function
// will return the object handle
// See also STATE_engine_2D_point_to_3D() and the STATE_object_ API.
STATE_IMPORT DWORD STATE_WINAPI STATE_engine_get_object_at_point_2D(int x,int y);
// Gets a two dimensional point (x,y) which is a point on the rendered window
// (Usually we get this point from events like OnLButtonDown() )
// If there is a polygon at this location (on the rendered image) then this function
// will return the polygon handle
// See also STATE_engine_2D_point_to_3D()
STATE_IMPORT DWORD STATE_WINAPI STATE_engine_get_polygon_at_point_2D(int x,int y);
//The default rendering window is the window on which the engine render
//when we call STATE_engine_render() with a NULL window
//(example: STATE_engine_render(NULL,camera))
//If the return value is NULL it means that the function failed
//One can use this handle with many of the win32 api function
//that deals with windows
STATE_IMPORT HWND STATE_WINAPI STATE_engine_get_default_rendering_window_hwnd(void);
//The default rendering window is the window on which the engine render
//when we call STATE_engine_render() with a NULL window
//(example: STATE_engine_render(NULL,camera))
STATE_IMPORT void STATE_WINAPI STATE_engine_maximize_default_rendering_window(void);
//The default rendering window is the window on which the engine render
//when we call STATE_engine_render() with a NULL window
//(example: STATE_engine_render(NULL,camera))
STATE_IMPORT void STATE_WINAPI STATE_engine_minimize_default_rendering_window(void);
//The default rendering window is the window on which the engine render
//when we call STATE_engine_render() with a NULL window
//(example: STATE_engine_render(NULL,camera))
STATE_IMPORT void STATE_WINAPI STATE_engine_set_default_rendering_window_title(char *text);
//The default rendering window is the window on which the engine renders
//when STATE_engine_render() is called with a NULL window
//(example: STATE_engine_render(NULL,camera))
//Arguments:
// left_x, top_y : the top left corner of the window
// width, height: the dimension of the window
STATE_IMPORT void STATE_WINAPI STATE_engine_set_default_rendering_window_size(int left_x, int top_y, int width, int height);
// Obsolete, use STATE_group_create_reduced_copy() instead
// accuracy is used when we try to check whether two polygons
// have the same plane (so we can unite them to one polygon).
// If this number for example is 0.1 and
// the X component if the normals are planeA[0]=1 and planeB[0]=0.9
// then the join operation will take place.
// can be done only in editor mode.
// returns the number of polygons that were reduced.
STATE_IMPORT int STATE_WINAPI STATE_engine_reduce_polygons_count(double accuracy);
// Add a polygon to the world. A polygon can be created and manipulated
// but it is not drawn until we call this function.
//
// This function also calls STATE_polygon_is_valid() to check the validity of the added polygon.
// If STATE_polygon_is_valid() returns NO (not valid) then it will try to
// fix the polygon. If the attempt to fix the polygon will fail the
// function will return VR_ERROR.
//
// This function works only in EDITOR_MODE.
// To add a polygon in Viewer Mode (The default mode) use the
// function STATE_object_add_polygon(). Even when using STATE_object_add_polygon()
// (in viewer mode) it is only possible to add polygons to the dynamic part of the world.
//
// Returns OK or VR_ERROR.
STATE_IMPORT int STATE_WINAPI STATE_engine_add_polygon(DWORD polygon_handle);
// 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
//
// Example:
// //Save the whole world including the bitmaps that will be saved in bmp format
// STATE_engine_save("World1.STATE", 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 projects including the bitmaps file
// The function will make a directory called bitmap bellow the given path, and there it will put all the bitmaps
// The idea here that the world becomes a "stand alone" it can be send through e-mail, put on a diskette etc ...
// Note that when you try to load the world
// after it was saved the engine would first look for jbm files
// then for bmp and then for jpg, so if a bitmap was changed and saved as bmp
// but the jbm file wasnt deleted then the engine will load the old bitmap in the jbm format.
// using one of the bitmaps flag 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. it will create all of them on the disk.
#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 // 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 (now 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 STATE 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 extra polygon)
// the release_save_flag can be set by STATE_polygon_set_release_save_flag() or
// by specifying NOYES 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 //This flag is only valid when saving in the binary format (to save in binary format give a file name that has a "3dstate" "morfit" name extension instead of "wld")
//In many application in 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 "3dstate" "morfit" 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 //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.
STATE_IMPORT int STATE_WINAPI STATE_engine_save(char *file_name, DWORD group_to_save, int save_flags);
//Use STATE_engine_save() with a .x extension ...
//STATE_IMPORT int STATE_WINAPI STATE_engine_save_in_directx_format(char *file_name);
// Redraw on the window the last rendered image
// Usually used together with STATE_engine_render_on_dc()
// Note that this function also releases the dc the was obtained
// when calling STATE_engine_render_on_dc() this means that
// all the function that use the returned dc (from dc=STATE_engine_render_on_dc() )
// must be called before calling STATE_engine_copy_image_from_dc_to_screen().
//
//See STATE_engine_render_on_dc() for more information.
STATE_IMPORT void STATE_WINAPI STATE_engine_copy_image_from_dc_to_screen(void);
//obsolete. Completely identical (Physically the same) to STATE_engine_copy_image_from_dc_to_screen()
STATE_IMPORT void STATE_WINAPI STATE_engine_bitblt(void);
//Like STATE_engine_render() only that it renders on a HBITMAP
//A HBITMAP is a WIN32 type (nothing to do with STATE) for more information
//about HBITMAP check your compiler help.
//The size of the created bitmap will match the size of the window that
//was last used for regular rendering.
//Note that there is no need to free the HBITMAP that is created. The engine will automatically
//delete the old HBITMAP when calling STATE_engine_render_on_bitmap() again.
// Return value: on failure returns NULL. On success returns an HBITMAP
//
//
//Example A: Taking a screenshot
//
// HBITMAP hbm=STATE_engine_render_on_bitmap(your_window_or_null, your_camera_or_null);
// STATE_utilities_save_bitmap(hbm, "d:\screenshots\shot.bmp");
//
// Example B: Using the rendered image as a regular bitmap that
// can be put on a polygon.
//
// HBITMAP hbm=STATE_engine_render_on_bitmap(NULL, NULL);
// STATE_utilities_save_bitmap(hbm, "d:\screenshots\shot.bmp");
// DWORD STATE_bmp=STATE_bitmap_load("d:\screenshots\shot.bmp", -1);
// DWORD test_poly=STATE_polygon_get_first_polygon();
// STATE_polygon_set_bitmap_fill(test_poly, STATE_bmp);
//
// Please note that Example B uses the harddisk to do the conversion between
// a HBITMAP and a bitmap that can be used with STATE_bitmap API.
// Currently there is no other way to do this. This is not as bad as it sounds
// Since the operating system will use its buffers so when we will do
// STATE_bitmap_load() it doesnt wait for the file to be written to the disk
// it takes the file immediately from the operation system buffers.
//
// See also STATE_utilities_save_bitmap(), STATE_engine_render_on_dc()
STATE_IMPORT HBITMAP STATE_WINAPI STATE_engine_render_on_bitmap(HWND hwnd, DWORD camera_handle);
//This function is very important. It allows painting and writing over the rendered image
//The function is exactly like STATE_engine_render() only that it doesnt write the
//rendered image into the screen, instead the image is left on the device context ( dc )
//If you dont know what is a Device Context then dont bother about it
//just think of it as a handle that many WIN32 graphic functions get.
//The beauty of this technique that one can use all the many Windows function
// (GDI functions). Please be aware that Windows graphics function are
// some time quite slow.
// After finishing painting on top of the rendered image
// use STATE_engine_copy_image_from_dc_to_screen() to draw the finished image on the
// window
//
//Here is a sample how to use STATE_engine_render_on_dc()
//
// HDC dc=STATE_engine_render_on_dc(NULL,camera);
//
// //paints a circle on the device context.
// //Note that ELlipse() is a Windows function (WIN32 API)
// //Look in you compiler help for information about that function.
// //There are many other function that you can use for writing text, changing
// //colors, changing the fill pattern etc ...
// Ellipse(dc, 100,100,200,200);
// //paint another circle
// Ellipse(dc, 220,220,320,320);
//
// //Get the picture on the screen. Without calling this function you
// //wont see anything.
// STATE_engine_copy_image_from_dc_to_screen();
//
// //Note that STATE_engine_copy_image_from_dc_to_screen()
// //releases dc (the device context) so
// //after calling it one cant use dc any more.
// //a new valid dc will be obtain when we repeat it in a loop
// // dc=STATE_engine_render_on_dc();
//
// For drawing a wire frame lines around polygons note the function STATE_engine_3D_edge_to_2D()
//
STATE_IMPORT HDC STATE_WINAPI STATE_engine_render_on_dc(HWND hwnd, DWORD camera_handle);
// This function is similar to STATE_engine_render_on_dc()
//
// The differences are only when doing hardware rendering:
// Here are the differences:
// 1) This function is slower.
// 2) This function doesnt lock the target surface (DirectX surface ...)
// This way you can do your own bitblt to the screen and not use
// STATE_engine_copy_image_from_dc_to_screen()
//
// In short, in almost any case it is better to use STATE_engine_render_on_dc()
STATE_IMPORT HDC STATE_WINAPI STATE_engine_render_on_memCDC(HWND hwnd, DWORD camera_handle);
//This function converts a given line in the 3D world to its projection on the rendered window.
//This could be very useful when drawing a wire frame to a polygon.
//
// Parameters:
// p1, p2 : A line (a segment) in the 3D world
// p1_2D, p2_2D : The equivalent line on the rendered window.
//
// Return value:
// returns one of the four:
// EDGE_NOT_SEEN if the edge is outside the rendering window
// in this case p1_2D and p2_2D are not valid
// EDGE_FULLY_SEEN if the edge is fully inside the rendering window
// in this case p1_2D and p2_2D are the desired result
// EDGE_PARTIALLY_SEEN if some of the edge is inside the window
// in this case p1_2D and p2_2D are the portion that inside the rendering area
// VR_ERROR an error occurred
// in this case p1_2D and p2_2D are not valid
//
// Example:
// double p1[3]={10,20,30};
// double p2[3]={100,200,300};
// double p1_2d[3], p2_2d[3];
// inr rc;
// rc=STATE_engine_3D_edge_to_2D(p1,p2, p1_2d, p2_2d);
//
STATE_IMPORT int STATE_WINAPI STATE_engine_3D_edge_to_2D(double p1[3], double p2[3], int p1_2D[2], int p2_2D[2]);
// returns one of the four
// EDGE_NOT_SEEN if the edge is outside the rendering window
// in this case p1,p2 == clipped_p1,clipped_p2
// EDGE_FULLY_SEEN if the edge is fully inside the rendering window
// in this case p1,p2 == clipped_p1,clipped_p2
// EDGE_PARTIALLY_SEEN if some of the edge is inside the window
// in this case clipped_p1,clipped_p2 is the seen part
// VR_ERROR an error occurred
// in this case clipped_p1,clipped_p2 are not valid
STATE_IMPORT int STATE_WINAPI STATE_engine_clip_edge(double p1[3], double p2[3], double clipped_p1[3], double clipped_p2[3]);
// Calling this function will eliminate the render to the given group
// Polygons that are not included in this group wont be rendered
// If a NULL is given then all the polygons will be rendered (the default)
// Arguments:
// grp_to_render_handle: The group to render
STATE_IMPORT void STATE_WINAPI STATE_engine_set_group_to_render(DWORD grp_to_render_handle);
// -- bitmaps stuff
//Returns the number of bitmaps that are currently loaded into the engine.
STATE_IMPORT int STATE_WINAPI STATE_engine_get_number_of_loaded_bitmaps(void);
//Calling this function will free all the bitmaps that are not used at this moment.
//Not used means that there is no polygon or animation that uses them.
// Returns the number of bitmaps that were unloaded
STATE_IMPORT int STATE_WINAPI STATE_engine_unload_unused_bitmaps(void);
//This function is not very useful
//Unload all the bitmaps from the engine.
STATE_IMPORT void STATE_WINAPI STATE_engine_unload_all_bitmaps(void);
//Obsolete. Please use STATE_engine_translate_movement_on_screen_to_world()
STATE_IMPORT int STATE_WINAPI STATE_engine_translate_movement_on_screen_to_movement_in_world(double p3D[3], double result_p3D[3], int delta_x, int delta_y);
// This function is used to solve the following problem:
// An object inside our world is dragged with the mouse delta_x,delta_y pixels.
// Where should we put the object now so that it will reflect the correct move.
// Arguments:
// p3D -
// p3D is a point in the world.
//
// delta_x,delta_y
// delta_x, delta_y is the desired change in the location on
// the screen of the projection of p3D.
//
// result_p3D
// result_p3D is a location that if p3D will move to this location
// its projection on the render image will move delta_x pixels right
// and delta_y pixels down (negative gives an opposite direction)
//
// returns OK or VR_ERROR and the reslut x,y,z point in result_p3D.
STATE_IMPORT int STATE_WINAPI STATE_engine_translate_movement_on_screen_to_world(double p3D[3], double result_p3D[3], int delta_x, int delta_y);
// The function returns the color depth (of the graphic mode) that was before
// STATE.dll was loaded.
//When the dll is being loaded it changes the color depth of the desktop to 16 bit (if not 16 bit already).
// Possible return values are:
// 0 When DirectX is not installed it will always return 0
// this means that the color depth wasnt changed by the STATE dll.
// 4 (for 16 color mode)
// 8 (for 256 color mode)
// 16 (16bit color mode == 65536 colors)
// 24 ( RGB 8-8-8 mode )
// 32 (32bit color mode )
//
// Note also that the dll will change the color to 16bit rgb automatically only if DirectX was installed on the computer
// or if the OS is Windows98 or above
STATE_IMPORT int STATE_WINAPI STATE_engine_get_original_color_depth(void);
// gets YES or NO. YES will move the objects automatically each
// time we do STATE_engine_render(). The movement is according
// to the instructions in the wld file (CHASE ... ) or as was set in real-time.
// The default is YES.
// See also STATE_camera_advance_all()
// and STATE_object_advance_all()
// Note works only in viewer mode (viewer mode is the default mode)
STATE_IMPORT void STATE_WINAPI STATE_engine_advance_objects_automatically(int yes_no_flag);
// gets YES or NO. YES will move the cameras automatically each
// time we do STATE_engine_render(). The movement is according
// to the instructions in the wld file (CHASE ... ) or as was set in real-time.
// The default is YES.
// See also STATE_camera_advance_all()
// and STATE_object_advance_all()
STATE_IMPORT void STATE_WINAPI STATE_engine_advance_cameras_automatically(int yes_no_flag);
//This function doesn't work in editor mode. When zbuffer is off
// get YES or NO. zbuffer is the name of the algorithm that is often used to solve
// the hidden surface removal problem. If NO is given the engine will use
// BSP algorithms (binary space partitions) the BSP algorithms are faster
// and more accurate most of the time. There are some cases where BSP algorithms will
// be less accurate. Try testing both methods and see which is better for your world.
// Note that using this function is equivalent to calling STATE_engine_load_world()
// with (or without) the DONT_USE_ZBUFFER flag. Using this function makes it possible to change
// methods at run-time.
//The return value is OK or VR_ERROR (error if we try to do it in editor_mode)
// The default is zbuffer ON.
// example: STATE_engine_use_zbuffer(YES);
STATE_IMPORT int STATE_WINAPI STATE_engine_use_zbuffer(int yes_no_flag);
// returns YES or NO. YES if the zbuffer algorithm is used.
// see STATE_engine_use_zbuffer() for more details.
STATE_IMPORT int STATE_WINAPI STATE_engine_is_zbuffer(void);
// Returns an array of all the extensions supported by the engine.
// returns also in number_of_supported_formats the number of extensions supported.
// these are the extensions that can be used with STATE_engine_load_world()
// and with STATE_engine_save()
// Example of usage:
// int num;
// table=STATE_engine_get_supported_extensions_array(&num);
// for(int i=0; i<num; i++) MessageBox(table[i]);
//
// The strings that we will get are "3dstate"=="STATE" "wld", "morfit","mft", "raw", "x" and more depending on the
// version of STATE dll.
STATE_IMPORT char ** STATE_WINAPI STATE_engine_get_supported_formats_extensions_array(int *number_of_supported_formats);
// Usage is exactly like STATE_engine_get_supported_formats_extensions_array()
// The string that we will get is similar to "STATE's 3D worlds file format" for example.
STATE_IMPORT char ** STATE_WINAPI STATE_engine_get_supported_formats_names_array(int *number_of_supported_formats);
// a value of 0 will make rendering as fast as possible but
// perspective correction will be at its lowest level (try it out and see if the lake of accuracy influence your world)
// a value of one is the default. values less than one will make rendering faster (but less accurate)
// values bigger than one will make rendering slower but more accurate.
// normally you wouldnt find values bigger than 3 useful.
// the value 1000 has a special meaning it will make perspective correction
// 100% correct. This of course will make rendering very very slow,
// use this value for pause mode or for screen capturing or when ever speed
// is not important at all.
STATE_IMPORT void STATE_WINAPI STATE_engine_set_perspective_correction_accuracy(double value);
// see STATE_engine_set_perspective_correction_accuracy() for more details
STATE_IMPORT double STATE_WINAPI STATE_engine_get_perspective_correction_accuracy(void);
// === Performances Querying ====== //
// Measure the time between two consecutive calls to render.
// returns the time in milliseconds.
// STATE_engine_render() must be called at least twice before this
// function can be used (if not it will return 0)
// The function calculate the average time starting with the first render to the last render
// See also STATE_engine_get_computer_speed_factor() which returns the average of the last 50 program cycles
STATE_IMPORT DWORD STATE_WINAPI STATE_engine_get_average_program_cycle_time(void);
// Measure the time between two consecutive calls to render.
// returns the time in milliseconds.
// STATE_engine_render() must be called at least twice before this
// function can be use (if not it will return 0)
// See also STATE_engine_get_computer_speed_factor() which returns the average of the last 50 program cycles
STATE_IMPORT DWORD STATE_WINAPI STATE_engine_get_last_program_cycle_time(void);
// Returns the execution time (in milliseconds) of the last call to STATE_engine_render().
// Through this number one can calculate the current fps (frames per second)
// t=STATE_engine_get_last_render_execution_time()
// if (t==0) return(0); //STATE_engine_render() wasnt called even once. protect against division by zero
// fps=1000/t;
// see also STATE_engine_get_average_render_execution_time()
STATE_IMPORT DWORD STATE_WINAPI STATE_engine_get_last_render_execution_time(void);
// Returns the average execution time (in milliseconds) of STATE_engine_render().
// Through this number one can calculate the average fps (frames per second)
// t=STATE_engine_get_average_render_execution_time()
// if (t==0) return(0); //STATE_engine_render() wasnt called even once. protect against division by zero
// fps=1000/t;
STATE_IMPORT DWORD STATE_WINAPI STATE_engine_get_average_render_execution_time(void);
// Obsolete. Use the 3D_card API instead (STATE_3D_card....)
// return YES or NO
STATE_IMPORT int STATE_WINAPI STATE_engine_check_3d_hardware_support(void);
// Obsolete. Use the 3D_card API instead (STATE_3D_card....)
// Get YES or NO. Returns OK or VR_ERROR
// If gets YES, the function will look for a 3D card installed on the computer
// if it wont find, the function will return VR_ERROR.
// It is a good practice to call STATE_engine_use_3D_accelerator_card(NO);
//before you exit your application.
// The default is NO.
STATE_IMPORT int STATE_WINAPI STATE_engine_use_3D_accelerator_card(int YES_or_NO);
// Obsolete. Use the 3D_card API instead (STATE_3D_card....)
//Returns the current setting for the 3D accelerator card.
//example:
// int res_x, res_y;
// STATE_engine_get_3D_accelerator_resolution(&res_x,&res_y);
// output_message("The current resolution setting for 3D hardware is %d X %d n",res_x,res_y);
STATE_IMPORT void STATE_WINAPI STATE_engine_get_3D_accelerator_resolution(int *width, int *height);
// Obsolete. Use the 3D_card API instead (STATE_3D_card....)
//Returns YES if a 3D accelerator card is in use.
//Returns NO if software rendering is used.
STATE_IMPORT int STATE_WINAPI STATE_engine_is_3D_accelerator_card_used(void);
// 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);
//
STATE_IMPORT DWORD STATE_WINAPI STATE_engine_create_terrain_from_bitmap(char *bitmap_file_name, double level_of_optimization, int max_number_of_polygons, DWORD bitmap_to_wrap_over_handle, int tile_x, int tile_y, BYTE legend [][3], int number_of_colors_in_legend,double dimensions[3], int *number_of_polygons_in_group);
//If one of STATE's functions fails, then one can use this
//function to retrieve a string describing the error
//This is the same string that appears in the STATE.log file
STATE_IMPORT char *STATE_WINAPI STATE_engine_get_last_error(void);
// This function is intended to help in writing a program that:
// 1- Keep the same speed all the time even if the frames per second rate changes. This means that when the player in your program game
// move from one room to another he will continue to have the same speed even if one room
// has many more polygons than the other. In other words: it helps to keep the same speed
// even if the frames per second rate changes.
//
// 2- Make your program run equally on all computers.
//
// Usage:
// ------
//
// Example: Lets say we want to move an object by 100 units each second
// In this case we should write something similar to the following:
//
// factor=STATE_engine_get_computer_speed_factor();
// corrected_number= 100*factor;
// move_my_object(corrected_number);
//
// Important notes:
//
// 1- Since the program cycle duration is the time from the beginning of one render to the next render,
// one has to do two renders before getting a non-zero returned value.
// This should not a problem. Here is Why: Consider the usage example above. A returned value of 0 will
// cause a call to move_my_object(0) which results that nothing will move before the third render which means
// that at the first tenth of a second of your gameapplication (approximately one tenth) there wont be any movement.
//
//
// 2- The return value of this function is constantly changing to reflect
// changes in the CPU load. This means you have to call the function each
// time before you use it (dont call it once and then use the same value over and over ...).
//
// 3- This function is extremely fast. Like most of STATE functions it only retrieves an internal value
// This means that there is no penalty in frequent calling.
//
// Return Value:
// The factor returned is actually the average duration of the last 50 rendering cycles (from the beginning of one render to the beginning of the next render)
// The time is given in tenth of a second (for example if the returned value is 3.2 it means that the last render cycle took 0.32 seconds)
// The return value will be 0 till there are at least two renders done.
//
//
//
//
// Remarks:
//
// Here is how to calculate the FPS (Frames Per Second) achived by your program using the STATE_engine_get_computer_speed_factor()
//
// double average_program_cycle_duration_is_seconds=STATE_engine_get_computer_speed_factor()/10; //The average durection of the last 50 cycles
// if(average_program_cycle_duration_is_seconds==0) return; //protect against division by zero ...
// double FPS=1/average_program_cycle_duration_is_seconds;
// output_text("The current frames per second rate is %lf", FPS);
//
//
STATE_IMPORT double STATE_WINAPI STATE_engine_get_computer_speed_factor(void);
//When the engine detects an error it makes a beep using the PC loudspeaker
//and writes some words about it to the STATE.log file (also to error.log)
//Usually you should take care of all the errors and the warnings if
//you didnt, you can use this function to shut down the noise from the speaker.
//Note that the error messages will still be outputted to the STATE.log and error.lof files
//The default value is YES
//Example: STATE_engine_set_speaker_mode(NO);
STATE_IMPORT void STATE_WINAPI STATE_engine_set_speaker_mode(int yes_no_flag);
// This function is everything you'll need to create lighs and shadows
// The function creates and adds new polygons which are the shadow of "entity_creating_shadow"
// on "entity_receiving_shadow" according to the given light source location.
// Those new added polygons are called patches.
// entity_receiving_shadow and entity_creating_shadow could be handles to any one of the following
// types POLYGON, OBJECT or GROUP. If a NULL is given the function would treat it as a handle to group
// a(note that a NULL group means the whole world)
// Note that the new added polygons get the same properties
// of the "entity_creating_shadow" (i.e. the same bitmap, the same translucent etc ...)
// Usually you would like to change those properties. For example:
//
// double light[3]={0,0,200}
// STATE_engine_create_shadow(room_group, chair_group, light, 255);
// //setting the color of the shadows. Note that by changing the color
// //you can simulate changes in light intensity
// STATE_group_set_patches_color(room_group, 70,70,70, ALL_PATCHES);
//
// If we dont call STATE_group_set_patches_color() we wont get a dark shadow on the room floor
// instead we will get the shape of the shadow but with the colors and bitmaps of the chair.
// Note that the last argument in the call to STATE_engine_create_shadow() is called serial_number
// serial_number is a number in the range [10 - 255]
// The number is relevant only if we will call
// STATE_group_set_patches_color(..., serial_number)
// and the function STATE_group_set_patches_bitmap(..., serial_number)
// This will allow us to have a room with several shadows and to change only one of them.
//
// Use STATE_polygon_delete_patches() to remove the shadow
// For example: STATE_polygon_delete_patches(room_handle, ALL_PATCHES) will
// delete all the shadows in the room while STATE_polygon_delete_patches(room_handle, 255) will
// delete just the shadows that were created with serial number 255.
//
// Performance note:
// If you create the shadow in real time and you want it to be fast
// then call this function with polygon handles. for example
// STATE_engine_create_shadow(polygon_to_get_shadow, polygon_obscaring_light, light, 255);
//
// Note that function like STATE_polygon_add_patch_easy() are also creating patches though for
// different purposes.
//
// Examples:
// A)
// double light[3]={100,200,300}
// STATE_engine_create_shadow(wall_polygon, blocking_polygon, light, 255);
//
//
// Example B:
// while(user did not press ESC) {
// STATE_polygon_delete_patches(wall_polygon, ALL_PATCHES);
// light[0]+=10; //move the light source
// STATE_engine_create_shadow(wall_polygon, blocking_polygon, light, 255);
// STATE_polygon_set_bitmap_fill(shadow_polygon_handle, flare_bitmap);
// STATE_polygon_set_translucent(shadow_polygon_handle, NORMAL_GLASS);
// }
//
// See also: STATE_engine_set_patches_offset(),
// STATE_engine_create_dynamic_shadow(),
// STATE_polygon_delete_patches(),
// STATE_polygon_delete_patches(),
// STATE_group_delete_patches(), STATE_group_set_patches_translucent(),
// STATE_group_set_color(), STATE_group_set_patches_bitmap()
// STATE_polygon_add_patch_easy().
STATE_IMPORT void STATE_WINAPI STATE_engine_create_shadow(DWORD entity_receiving_shadow, DWORD entity_creating_shadow, double light_src[3], BYTE serial_number);
// Exactly like STATE_engine_create_shadow() only that it is faster
// The disadvantage is that dynamic shadows can only be deleted with
// STATE_engine_delete_dynamic_shadows() which delete all the existing dynamic shadow.
// (STATE_group_delete_patches() wont work here)
// We suggest that you use this function to create shadows that can be changed from
// one render to another. For example in our world we might have several source
// of lights some of them will be moving and some are fixed. We could also have some moving objects
// in our world (so their shadow is moving too). The shadow that is created
// from the fixed light sources and by the fixed object can be created only once at the beginning of
// the program. To create the fixed shadows use STATE_engine_create_shadow()
// The shadows that are created by the moving light sources or from the moving objects will have to be
// deleted and recreated for each render cycle. Use STATE_engine_create_dynamic_shadow()
// to create them. To delete them use STATE_engine_delete_dynamic_shadows().
// Here is an example:
//
// //creating the static shadow. Create the shadow that the trees project on the ground
// double sun[3]={10000, 10000, 30000};
// STATE_engine_create_shadow(ground, trees, sun, 255);
// while(Escape key is not pressed) {
// STATE_engine_delete_dynamic_shadows();
// move_our_ball(ball);
// STATE_engine_create_dynamic_shadow(ground, ball, light_source);
// STATE_engine_render(NULL, camera);
// }
//
// See also STATE_engine_set_patches_offset()
STATE_IMPORT void STATE_WINAPI STATE_engine_create_dynamic_shadow(DWORD entity_receiving_shadow, DWORD entity_creating_shadow, double light_src[3], BYTE serial_number);
// Deletes all the existing dynamic shadow. Dynamic shadow is created using
// the function STATE_engine_create_dynamic_shadow()
STATE_IMPORT void STATE_WINAPI STATE_engine_delete_dynamic_shadows(void);
//When rendering takes more than the specified time then the rendering function will exit automatically
//This is very useful when rendering indoor worlds. The engine renders front to back
// so it is usually enough to stop rendering after finishing with the current room.
// Try playing with different values and see the result.
//The default is 1000000 (which is about 17 minutes which is similar to "take all the time in the world to finish every rendering")
//Typical values would be 200,100,50
// Note that this function is only relevant in Viewer Mode (Viewer Mode is the the default mode)
//Example: STATE_engine_set_maximum_rendering_time(100); //Set minimum frames per seconds to 10
STATE_IMPORT void STATE_WINAPI STATE_engine_set_maximum_rendering_time(int max_duration_in_mili_seconds);
STATE_IMPORT int STATE_WINAPI STATE_engine_get_maximum_rendering_time(void);
//Sets a minimum time for each render. If STATE_engine_render() take less time
//than the specified time then the engine will wait (Doing Sleep() ) till it reaches the given
// duration.
// Why should you use this function ? Sometimes when you get to the end of your world
// The engine has only few polygons to render in this case it can get to 1000 frames per seconds and more !!!
// If you are moving a car by X units every render then your car is going to become
// a rocket when you reach the end of the world ...
// The default is 2. This permits a maximum of 500 frames per seconds
// Note also the function STATE_engine_get_computer_speed_factor()
//Example: STATE_engine_set_minimum_rendering_time(0);
STATE_IMPORT void STATE_WINAPI STATE_engine_set_minimum_rendering_time(int min_duration_in_mili_seconds);
STATE_IMPORT int STATE_WINAPI STATE_engine_get_minimum_rendering_time(void);
//Controls the amount of CPU time that the rendering process gets.
//Usually you would like to have the fastest graphics possible
//though sometime when a few application are working in conjunction
//there is need to release some CPU time for the benefit of the others.
// parameters:
// thread_priority: (For more details please see the win32 function SetThreadPriority() )
//
// THREAD_PRIORITY_ABOVE_NORMAL
// Indicates 1 point above normal priority for the priority class.
// THREAD_PRIORITY_BELOW_NORMAL Indicates
// 1 point below normal priority for the priority class.
// THREAD_PRIORITY_HIGHEST
// Indicates 2 points above normal priority for the priority class.
// THREAD_PRIORITY_IDLE
// Indicates a base priority level of 1 for IDLE_PRIORITY_CLASS, NORMAL_PRIORITY_CLASS, or HIGH_PRIORITY_CLASS processes, and a base priority level of 16 for REALTIME_PRIORITY_CLASS processes.
// THREAD_PRIORITY_LOWEST
// Indicates 2 points below normal priority for the priority class.
// THREAD_PRIORITY_NORMAL
// Indicates normal priority for the priority class.
// THREAD_PRIORITY_TIME_CRITICAL
// Indicates a base priority level of 15 for IDLE_PRIORITY_CLASS, NORMAL_PRIORITY_CLASS, or HIGH_PRIORITY_CLASS processes, and a base priority level of 31 for REALTIME_PRIORITY_CLASS processes.
//
// Class priorities: ( For more details please see the win32 function SetPriorityClass() )
//
// HIGH_PRIORITY_CLASS
// Specify this class for a process that performs time-critical tasks that must be executed immediately. The threads of the process preempt the threads of normal or idle priority class processes. An example is the Task List, which must respond quickly when called by the user, regardless of the load on the operating system. Use extreme care when using the high-priority class, because a high-priority class application can use nearly all available CPU time.
// IDLE_PRIORITY_CLASS
// Specify this class for a process whose threads run only when the system is idle. The threads of the process are preempted by the threads of any process running in a higher priority class. An example is a screen saver. The idle-priority class is inherited by child processes.
// NORMAL_PRIORITY_CLASS
// Specify this class for a process with no special scheduling needs.
// REALTIME_PRIORITY_CLASS
// Specify this class for a process that has the highest possible priority. The threads of the process preempt the threads of all other processes, including operating system processes performing important tasks. For example, a real-time process that executes for more than a very brief interval can cause disk caches not to flush or cause the mouse to be unresponsive.
//Examples:
// A)
// Setting High priority (The default)
// STATE_engine_set_thread_priority(THREAD_PRIORITY_HIGHEST, HIGH_PRIORITY_CLASS);
//
// B)
// Setting the fastest rendering possible
// STATE_engine_set_thread_priority(THREAD_PRIORITY_TIME_CRITICAL, REALTIME_PRIORITY_CLASS);
//
// For more details please see the win32 functions SetPriorityClass() and SetThreadPriority()
STATE_IMPORT void STATE_WINAPI STATE_engine_set_thread_priority(int thread_priority, DWORD class_priority);
//This function must be called before your program exits.
//Not calling this function at the end of your program might
//cause your program not to exit cleanly (Crashing at the end)
//This function should not be called from inside a destructor
//No STATE function can be called after calling STATE_engine_close()
STATE_IMPORT void STATE_WINAPI STATE_engine_close(void);
//Returns STATE's logo
STATE_IMPORT HBITMAP STATE_WINAPI STATE_engine_get_logo(void);
//Show the frames per second rate at the top left of the rendered window.
//by default it is activated.
//Example:
//STATE_engine_show_frames_per_second_rate(NO);
STATE_IMPORT void STATE_WINAPI STATE_engine_show_frames_per_second_rate(int YES_or_NO);
//The default is NO, which means that each render will
//clear the result of the previous rendering before painting the new picture.
//There are two cases in which one should consider calling this function
//with the argument YES
// 1) When our world is an indoor world. In this case clearing the screen is simply not needed.
// (by not clearing the previous screen we could improve a bit the speed of each render)
// 2) When we want to create special effects.
//
// To understand the effect of this function simply call it and see what you get.
// Example: STATE_engine_render_on_top_of_previous_rendering(YES);
STATE_IMPORT void STATE_WINAPI STATE_engine_render_on_top_of_previous_rendering(int YES_or_NO);
// Use this function only with the commercial version of STATE 3D Engine.
// This function should be the first STATE function that is called .
// If this function is not called then a popup message will appear.
// Note: It is better to call this function after you have created the main window
// of your application, otherwise when launching your application your main window
// might be behind the engine windows (there is nothing wrong with that, it is simply not as nice as)
// Arguments:
// Enter the argument exactly as they appear on the license that you got from STATE.
// Failing to do so will prompt a popup window with a warning.
//
// Return value:
// Returns OK if the registration was successful.
// Returns VR_ERROR if one of the arguments was wrong.
// If you receive VR_ERROR then please check that you type everything
// exactly as they appear on the license that you got from STATE.
//
//
// Example:
// STATE_register_license("XXXXXX", "John Smith", "johnsmith124@ibm.com", "IBM", "OS2 Wrap",1234567890.987654321);
int STATE_register_license(char *decleration_text, char *your_full_name, char *password ,char *company, char *product_name ,double registration_number);
//This function could be very important for performance if you find in STATE.log that
// a significant number of polygons were added to your world while loading it.
// Background:
// When the world is loaded in Viewer Mode (the default) the engine needs to build a BSP data structure (Never mind if you
// dont have any idea what BSP is. Keep reading) it then looks to see if such file exist in the same folder of the world.
// (in binary format this file is sometime inside the world file so there is no sparate file) If such a file does not exists
// then the engine start building its own file (a very lengthy process. When the world is big it could even take 30 minutes !)
// During this process many polygons are cut into smaller pieces. For example if a tree is stuck into the ground in a way
// that the ground intersect one of the polygons of the tree then this polygon or the polygon of the ground will be cut into two pieces,
// adding to the number of total polygons in the world. To avoid that it is recommended that polygons in your world should not
// intersect with each other. Nevertheless even if no polygon intersects others the engine might need to split some of the polygons.
// (If you really want to know why, you can search the Internet for articles about BSP trees == Binary Space Partition Trees)
//
// This function controls the numbers of polygons that the engine will add in the process of forming
// the bsp tree. The bigger this number is the less polygons will be added. The default is 1.
// Possible numbers are anything bigger then 0.
// Examples: 0.01, 0.1, 1, 10, 50, 100, 1e20
//
// Calling this function with a bigger number helps in reducing the number of added polygons but reduces the accuracy of the BSP
// structure. This could cause the world to appear incorrectly. Surfaces that should be in front
// of other surfaces will be behind. We suggest that you keep this number as low as possible as long as it doesnt increase significantly.
// the number of polygons in your world. Note that in the log file (STATE.log) you can find how many polygons were added
// during the process of creating the BSP data structure.
//
// STATE_engine_set_bsp_precision() should be called before loading the world.
// Each time that the precision variable is changed a new bsp tree will be created.
STATE_IMPORT void STATE_WINAPI STATE_engine_set_bsp_precision(double precision);
STATE_IMPORT double STATE_WINAPI STATE_engine_get_bsp_precision(void);
//This is a very important function.
//The Speed database is used to speed up rendering.
//One of the most time consuming test for the engine is to determine in real-time which
//of the polygons in the world are seen and which are totally hidden by other polygons.
//The information in the Speed database will reduce the amount of calculations that are needed in real-time
//in order to determine from each location in the world the polygons that are seen and those that are hidden.
//The Speed database contains information for every possible area in the world. The information tells the engine which
//polygons in the world are seen from this area. In order to keep the size of the Speed database reasonable it is needed to supply
//to the engine a list of points that we would like to speed the rendering in the vicinity of the given points.
//In order to create the Speed database it is first needed STATE_engine_load_world() with the flag OUTPUT_RENDER_LOCATIONS
//Here is a summary of how to speed up the rendering
// 1) Call STATE_engine_load_world() with the OUTPUT_RENDER_LOCATIONS flag and walk trough your world. This will create the visited_points.txt
// Try to visit every possible area inside your world. The direction in which a certain location is approached does not matter
// All that mater is the visited location themselves. Areas that wont be visited wont benefit from the Speed database
// 2) Call STATE_engine_create_speed_database() Sit back and relax while the engine will create the Speed database.
// Use the visited_points.txt you have created in step "1". The speed.pvs file that is created is the Speed database that will
// speed rendering in real-time.
// 3) Run your application. Make sure that the speed.pvs file is located in your application working directory (the folder where you have your exe file).
// If you encounter areas in the world that do not enjoy any speed up, it is usually because those areas were not
// visited in step "1". In order to fix this there is no need to redo the whole process. Here are two ways you can edit the speed.pvs database.
// A) Do step "1" again but visit only the locations where the speed optimization didn't take place.
// Do step "2" but now call STATE_engine_create_speed_database() with reset_database set to NO.
// The new information will be added to the original speed.pvs file.
//
// OR
//
// B) Add locations manually to the visited_points.txt file and then repeat step "2"
//
//
//Please note the following facts:
//1) The bigger your world is the more impact you will gain by using the Speed database.
// On very small worlds you might not even notice the effect.
//2) To increase the speed up by this process build your world in a way that a minimum number of polygon is visible
// from every location in the world. The most perfect world for this kind of optimization is
// an indoor world where one cant see from one room to another because the door leads to a corridor.
// Here is an example of such structure:
//