射击游戏

开发平台：

Visual C++

3DSTATE.H：源码内容

// --------
// | Room |
// | A |
// | |
// | ------
// ------ |
// |Room |
// |B |
// |------|
//
// Note that from Room A it is not possible to see room B and the other way around
// Many games (like Quake ...) use this technique extensively.
// Parameters:
//
// visited_points_file_name: A file that holds a list of x,y,z points. This file is created automatically
// when calling STATE_engine_load_world() with the OUTPUT_RENDER_LOCATIONS.
//
// reset_database: should be YES or NO. If NO then the function will use the previously created speed.pvs file and will
// add to it new information derived from the given visited_points_file_name
//
//
// make_compact_database: YES or NO. If YES the database will be significantly smaller. In some worlds the compact database
// will give a much smaller rendering speed up. In other worlds it will give better results then the
// detailed database (none compact). One has to check both methods on the final world.
// The best performance will be achieved when make_compact_database==NO and the points
// in the visited_points_file_name are selected cafully so that there are not too many but
// there are enough to represent all the location that deffer by the polygon visible from these locations.
// for example, if there are two ajacent points that when the camera is located in each one of them
// there are xxx visible polygons. So if from both location there are the same polygons visible
// so one of these points might be ommited.
STATE_IMPORT int STATE_WINAPI STATE_engine_create_speed_database(char *visited_points_file_name, int reset_database, int make_compact_database);
//Determines the distance that the engine will set for all created patches from the polygon
//the patches are put on. (To learn about patches and what they are used for please see
//STATE_polygon_add_patch_easy() or STATE_engine_create_shadow() )
//
// Q: Why do we need this function ?
//
// A: When putting a patch over a polygon we get two polygons one on top of the other
// Some 3D cards can not handle this situation cleanly because of small floating point
// glitches when zbuffer is done. The artifact is stripes on the patch (coming from the polygon behind)
// This function can be used to solve this problem so that patches look better.
//
//The default distance is 2. This function was introduced with version 5.4 of the engine.
//previous versions of the engine made patches with 0 distance.
//
// Parameters:
// offset_size: The distance is explained above.
// Use the smallest number that makes the patches look good
// example of possible values: 0, 0.4, 1, 10, 40
// A too big number would make shadows created with STATE_engine_create_shadow()
// to be inaccurate
//
// See also:
// STATE_engine_get_patches_offset(), STATE_polygon_add_patch_easy()
// STATE_polygon_add_patch(), STATE_polygon_add_shadow_patch(), STATE_engine_create_shadow()
STATE_IMPORT void STATE_WINAPI STATE_engine_set_patches_offset(double offset_size);
//For more details please see STATE_engine_set_patches_offset()
//Returns the distance that is used by the engine when creating patches
// (The distance from the created patch and the polygon that the patch is put on)
STATE_IMPORT double STATE_WINAPI STATE_engine_get_patches_offset(void);
// Why do we need this function
//------------------------------
//This function is used to group together many small bitmaps into several bigger bitmaps.
//This is very useful in improving rendering frames per second and shortening loading
//time of the world. One of the techniques used in today's leading games is to create
//small lightmaps (second bitmaps) to every polygon in the world (This can be done using STATE 3D WebmakerWorldBuilder)
//This technique can drastically improve the graphics quality of the world though they create a huge number of small bitmaps
//For example in one of Half-Life worlds there are about 4000 lightmaps each one at the average size of 5*9 pixels.
//Loading 4000 bitmaps can take quite sometime. Using STATE_engine_reduce_number_of_bitmaps()
//one can group those small bitmaps into bigger ones. For example 4000 5x9 bitmaps can be grouped to only 3 bitmaps of 256x256 !!!
//
// Please note that bitmap that are transparent or that are used by a STATE 2D animation or that are tiled will not be grouped together.
//
// How to use this function
// -------------------------
// Load your world in editor mode (Give the EDITOR_MODE flag when calling STATE_engine_load_world() )
// Call STATE_engine_reduce_number_of_bitmaps()
// Call STATE_engine_save()
//
// This will save a new copy of your world with the small bitmaps grouped in big bitmaps.
// Note that not always we would like to group all the small bitmaps in big bitmaps
// For example if we have a bitmap that we use as a shooting mark (to put on walls after shooting at them)
// then we would like this bitmap to stay separate in its own file so that we could easily
// call STATE_polygon_set_bitmap_fill()
// the include_filter and exclude_filter parameters are used in order to give
// the programmer the freedom to group together only the bitmaps that he wants to
//
// Example:
// ---------
// //The following example will group together all the bitmaps that are equal or smaller than 32x32 bitmap into bitmaps in the size of 256x256
// STATE_engine_reduce_number_of_bitmaps(32, 256, "..\bitmaps", NULL, NULL, YES);
//
// Return Value
// -------------
// Returns the number of bitmaps that were replaced and group together in bigger bitmaps
//
//
// Parameters:
// replace_below_equal_this_width:
// Only bitmaps equal or smaller than this size will be replaced
// Here are some common values to use 32, 20 and so on.
// a value of 32 means that only bitmaps that are smaller then a 32x32 bitmap will be included
// a bitmap of 33x2 is not consider smaller since it does not fit in inside the 32x32 square.
//
// big_bitmaps_width
// The size of the bitmaps that will be created and will be filled with the small bitmaps
// Values must be in the power of to (i.e 256, 512, 1024, 2048, 4096 etc.)
// For example giving 256 means that the engine will use 256x256 bitmaps.
// This bitmap is always square.
// By giving a big value (such as 1024 or 2048) you can group all the bitmaps in your world into
// one big bitmap !
// So what is the right value to use ? We recommend using 256 since
// there are some 3D card that can not display bitmaps larger than 256x256
// One can test different values and check how it effect the rendering speed.
//
// bitmaps_folder
// The directory where the bitmaps can be found. Bitmaps that are not in this folder are not going to be grouped
// inside big bitmaps.
//
// include_filter
// Only bitmaps with name that contains the "include filter" string will be groupedreplaced
// If this parameter is NULL then all the bitmaps in the given folder will be included
// Example: If the include_filter is "xx" then the following bitmaps will be included xx.bmp xx12345.bmp 123xx.bmp but not x123x.bmp
//
// exclude_filter
// Bitmaps with name that contains the "Exclude filter" string will NOT be groupedreplaced
//
//
// create_8bit_bitmaps
// Whether the group bitmaps are in 8 bit or 24 bit format.
// Could be YES or NO. YES is recommended for faster loading time.
// In some cases NO could give better graphics quality.
//
STATE_IMPORT int STATE_WINAPI STATE_engine_reduce_number_of_bitmaps(int replace_below_equal_this_width, int big_bitmaps_width, char *bitmaps_folder, char *include_filter, char *exclude_filter, int create_8bit_bitmaps);
#define STEREOSCOPIC_OFF 0
#define STEREOSCOPIC_CYAN_RED 1 //The left lenseye is cyan. The right lenseye is red.
#define STEREOSCOPIC_RED_CYAN 2 //The right lenseye is cyan. The left lenseye is red.
#define STEREOSCOPIC_BLUE_RED 3 //The right lenseye is red. The left lenseye is blue
#define STEREOSCOPIC_RED_BLUE 4 //The left lenseye is red. The right lenseye is blue
#define STEREOSCOPIC_GREEN_RED 5 //The right lenseye is red. The left lenseye is green
#define STEREOSCOPIC_RED_GREEN 6 //The left lenseye is red. The right lenseye is green
#define STEREOSCOPIC_NUMBER_OF_MODES 7
// If you have a pair of 3D paper glasses (Anaglyphic glasses)
// then this function can do amazing things for you.
// Once this function is called, the engine will render
// your scene in a way that will match your 3D glasses.
// The result is a real 3D rendering with a real sense of depth.
// If you don't have 3D paper glasses then you should quickly get a pair.
// 3D paper glasses should not cost more than 1 dollar.
// There are some Web Sites which even give them for free.
// Note that Cyan is the color that one gets
// when adding green to blue (CYAN RGB= 0,255,255).
// www.rainbowsymphonystore.com is a good place to buy 3D Glasses.
// 3D glasses are very cheap ( $0.4 for a pair)
// Check out http://www.rainbowsymphonystore.com/3dglasses.html
// www.d3.com is another option.
// Any other place is probably just as good.
// We recommend the glasses sold by www.d3.com though
// any other suitable product from other companies can do the work.
//
// If your company is using a type of 3D glasses or any type of 3D virtual reality head set that
// is not supported by the engine then you can write to us and we will
// try to add support for this equipment.
//
// Parameters:
// stereoscopic_mode:
// set the mode of work
//
// distance_between_eyes:
// Any number starting from 0.
// A bigger number will increase the 3D effect
// 0 will result in no 3D effect.
// The 3D effect is created using a combination of two images
// taken from adjacent locations. This mimics the way it is done
// in nature. In nature our brain receives two images, one from each eye.
//
// Note that getting an anaglyphic image is not without a price.
// In this mode the rendering operation will be about 40 percent slower.
//
// Examples:
// 1)
// //Initializing anaglyphic mode. You can call this function anytime
// //after the world is loaded.
// //Try different numbers for distance_between_eyes till you get the best effect
// STATE_engine_set_stereoscopic_mode(STEREOSCOPIC_RED_CYAN, 100);
//
// 2)
// //Canceling the anaglyphic mode.
// STATE_engine_set_stereoscopic_mode(STEREOSCOPIC_OFF, 100);
STATE_IMPORT void STATE_WINAPI STATE_engine_set_stereoscopic_mode(int stereoscopic_mode, double distance_between_eyes);
STATE_IMPORT char *STATE_WINAPI STATE_engine_get_stereoscopic_mode_name(void);
//Switch between the different stereoscopic modes.
//See also STATE_engine_get_stereoscopic_mode_name()
//returns the new mode number
STATE_IMPORT int STATE_WINAPI STATE_engine_switch_stereoscopic_mode(void);
//Returns the current stereoscopic mode
//For more information see STATE_engine_set_stereoscopic_mode()
STATE_IMPORT int STATE_WINAPI STATE_engine_get_stereoscopic_mode(void);
// A very useful and easy to use function.
// Layers are polygons that appear on top of the rendered world.
// Think of layers as the 2D mechanism of the engine.
// One can use layers for displaying information such as the
// player health, a cross hair, simulate looking through binocular etc.
// The function returns a handle to a polygon which is the created layer.
// While doing software rendering the function has no effect.
// Using this function is a lot faster and powerful than using Windows GDI
// functions. ( In other words using layer is better than calling STATE_engine_render_on_dc() for
// obtaining the Device Context handle and then to use Windows functions for drawing on the DC. See STATE_engine_render_on_dc()
// for more information)
//
// Using STATE_engine_add_layer() one can easily create a square polygon
// with a bitmap on it. The first four parameters define the layer size and position.
// No matter what is the size of the window which you render on the
// top left corner is always 0,0 and the bottom right corner is 100,100
// For example if the four numbers 0,0,50,100 are given as the first 4 parameters
// then the layer will occupied the half left of the rendered screen
// If there are two or more polygon layers that overlap then the one which was
// first created will be on top.
//
// Return value
// The function returns a handle to a polygon which is used for the layer.
// One can use all the polygon functions in order to modify the created layer
// A few of the functions you might probably want to use are:
// STATE_polygon_disable(), STATE_polygon_enable(), STATE_polygon_set_bitmap_fill()
// STATE_polygon_set_light(), STATE_polygon_set_translucent(). STATE_polygon_move()
// STATE_polygon_shift_bitmap()
//
//
// Parameters:
// left_x, top_y:
// The top left corner of the created layer.
// Any number in range [0-100]. (0,0) is the top left corner
// while (100,100) is the bottom right corner
//
// right_x, bottom_y:
// The bottom right corner of the created layer.
// Any number in range [0-100]. (0,0) is the top left corner
// while (100,100) is the bottom right corner
//
//
// Note that after the a layer is created it is possible
// to changemove the points using the Polygon and Point APIs
//
//
// bitmap_handle: A handle to a bitmap that will be used.
// Give NULL if your layer will use color fill.
// Note that after the layer is created, one can use STATE_polygon_set_bitmap_fill()
// to change the bitmap.
//
// glass_type:
// Using this parameter one can determine if the layer will be
// opaque or translucent. Use any of the values possible with
// the STATE_polygon_set_translucent() function.
// To precisely control the level of translucency
// call STATE_polygon_set_light(layer_handle, translucent_level_rgb);
//
//
// Remarks:
// --------
//
// A very convenient way to work with layer polygons is
// to create them all at the beginning of the program and then to disable those
// which should not be visible right away.
// Then during the program run to enable layer polygons according to the need.
// There is no time penalty for having many layer polygons which are disabled
// Only those which are drawn consume time. Layers are very fast to draw since
// they exploit the 3D card hardware. The time it takes to draw a layer
// depends on its size. If the layer covers the whole rendering windowfullscreen
// then the slowdown in FPS might be measurable.
//
// Examples:
//
// Example 1:
// //Creating a layer on the whole window
// DWORD my_bitmap=STATE_bitmap_load("binocular", -1);
// if(my_bitmap==NULL) return(VR_ERROR);
// DWORD layer_polygon=STATE_engine_add_layer(0,0, 100, 100, my_bitmap, FILTER_GLASS);
// //After the next render the layer will be shown on the screen
//
// Example 2:
// //A more advanced example which show how to make a message
// //appearing on the screen and then fading away and disappearing.
// //This message could be something like "1000 points bonus"
// //"Extra life" etc. This example is quite important since once
// //you will understand it you will be able to create many more nice effects
// //that have nothing to do with layers.
// //The following example is comprised of 3 functions that together
// //create the mechanism.
//
// //Call this function at the beginning of the program
// DWORD create_message_layer(void)
// {
// DWORD my_bitmap=STATE_bitmap_load("ExtraLife", -1);
// if(my_bitmap==NULL) return(NULL);
//
// //Note that we have chosen LIGHT_SOURCE_GLASS below since
// //this type of blending will do 'add' between the layer_message polygon and the
// //rendered world below (new_pixel=src+dest). We need this adding for
// //doing the fade away effect. We will make the message_layer_polygon
// //darker and darker till it wont be seen (new_pixel= 0 + dest == dest)
//
// DWORD message_layer_polygon=STATE_engine_add_layer(20,15, 80,30, my_bitmap, LIGHT_SOURCE_GLASS);
// if(message_layer_polygon==NULL) return(NULL);
// //disable the polygon since we dont want it to be seen now
// STATE_polygon_disable(message_layer_polygon);
// m_is_message_visible=NO; //remember the status of the message in a globalclass member variable.
// return(message_layer_polygon);
// }
//
// //Call this function when the message should be seen
// void make_message_visible(DWORD message_polygon)
// {
// STATE_polygon_enable(message_polygon);
// BYTE rgb[3]={255,255,255);
// //Show the message in full visibility
// STATE_polygon_set_light(message_polygon, rgb); //Set the rgb of all the points to 255,255,255
// m_is_message_visible=YES;
// }
//
//
// //Call this function before each render
// void make_message_fade_away(DWORD message_polygon)
// {
// if(m_is_message_visible==NO) return; //If the message is not visible then there is nothing to do
// //All the points have the same rgb so lets check the first one
// DWORD point=STATE_polygon_get_first_point(message_polygon);
// BYTE rgb[3];
// STATE_point_get_rgb(point, rgb);
// if(rgb[0]==0) {
// STATE_polygon_disable(message_layer_polygon);
// m_is_message_visible=NO;
// return;
// }
// //Reducing the rgb will make the message darker and because we use LIGHT_SOURCE_GLASS
// //The result will be fading away
// rgb[0]--;
// rgb[1]--;
// rgb[2]--;
// STATE_polygon_set_light(message_layer_polygon, rgb); //Set the rgb of all the points of the polygon
//
// }
//
//
STATE_IMPORT DWORD STATE_WINAPI STATE_engine_add_layer(double left_x, double top_y, double right_x, double bottom_y, DWORD bitmap_handle, BYTE glass_type);
// Return a handle to the layer (a polygon handle) which the given 2D point is inside
// The 2D point is a point inside the rendering window client area.
// For example 0,0 is the top left point of the window.
// The functions ignore disabled layers. If the given point is not inside any of the
// enabled layers, the function will return NULL.
//
STATE_IMPORT DWORD STATE_WINAPI STATE_engine_get_layer_at_2D_point(int x, int y);
// Who needs this function ?
// -----------------------------
// This function is not very important. 99% of all users will never have to use it.
// Users who import code from other engines might need this function.
// This function is also useful if your code is built to support only triangles.
// Using this function one can limit the engine to use only triangles.
// What does it do ?
// -------------------
// Limits the number of points that are permitted per polygon.
// This function can be called at any time, before or after loading the world.
// This function will split polygons that have more points than what is permitted into smaller polygons.
// The engine is smart enough to isolate the internally created polygon fractions from
// the software API. For example if we limit the number of permitted points per polygon to 3
// in this case polygons with 10 points will be split to 8 triangles.
// When we use functions such as STATE_polygon_set_bitmap_fill() on one of the
// newly created fractions (triangles) the engine will be smart enough to set the given
// bitmap to all the fractions as if it is still one polygon.
//
// Remarks:
// -----------
//
// IMPORTANT: Please note that polygons that have more than the permitted number of points will
// deleted ! This means that one should consider all polygon handles as not legal
// after calling this function.
// Example:
// DWORD floor_handle=STATE_polygon_get_handle_using_name("floor");
// STATE_engine_set_max_num_of_points_per_polygon(4);
// // If the polygon "floor" had more than 4 point, it was deleted. In this case we cannot use its handle any more
// //Repeat the call to be sure that we get a valid handle
// DWORD floor_handle=STATE_polygon_get_handle_using_name("floor");
// //We now have a valid fraction of the floor (or the whole floor if it was not deleted)
// API functions that are executed on the floor fraction will be carried out on all the fractions
// that make the floor.
//
//
// Example:
// STATE_engine_set_max_num_of_points_per_polygon(3);
//
// See also STATE_engine_get_max_num_of_points_per_polygon()
STATE_IMPORT void STATE_WINAPI STATE_engine_set_max_num_of_points_per_polygon(int max_number);
// Returns the maximum permited number of points per polygon
// for more details please see STATE_engine_set_max_num_of_points_per_polygon().
STATE_IMPORT int STATE_WINAPI STATE_engine_get_max_num_of_points_per_polygon(void);
STATE_IMPORT void STATE_WINAPI STATE_engine_set_turbo_mode(int ON_or_OFF);
//--------------------------------------------------------//
//=========== T H E C A M E R A A P I ===============//
//--------------------------------------------------------//
// This API controls properties of the camera like
// zoom location direction etc...
// returns a handle to a camera.
// Used in conjunction with STATE_camera_get_next_camera()
// to traverse all the existing cameras
// example:
// for(handle=STATE_camera_get_first_camera() ; handle!=NULL ; handle=STATE_camera_get_next_camera(handle) )
// {
// ...
//
// }
STATE_IMPORT DWORD STATE_WINAPI STATE_camera_get_first_camera(void);
STATE_IMPORT DWORD STATE_WINAPI STATE_camera_get_next_camera(DWORD camera_handle);
//Checks whether the given camera handle is legal and represents a handle to a camera.
//If the handle is not a legal camera handle then a popup window will pop out (only if popup_title!=NULL).
//This function is used mainly for debugging (similar to the C++ function assert() )
//Return value: YES or NO.
//Arguments:
// camera_handle: The handle of the camera to be examined.
// popup_title: The title of the popup that will pop-out in case the given handle does not represent
// a legal camera handle. If popup_title==NULL then there wont be any popup
// The best is to give the function name so if you get the error you know
// what function should be fixed.
STATE_IMPORT int STATE_WINAPI STATE_camera_is_camera(DWORD camera_handle, char *function_name);
// insensitive to upper / lower case (it doesn't make a difference if it is a or A)
STATE_IMPORT DWORD STATE_WINAPI STATE_camera_get_using_name(char *camera_name);
// Returns a pointer to camera name which is stored internally inside the 3D Engine.
// Visual Basic users should use STATE_entity_get_name() instead.
// See also STATE_entity_get_namel(), STATE_camera_set_name();
STATE_IMPORT char *STATE_WINAPI STATE_camera_get_name(DWORD camera_handle);
STATE_IMPORT void STATE_WINAPI STATE_camera_set_name(DWORD camera_handle, char *name);
// Function level of importance = High.
//
// The human eye can not see clearly objects that are too near the eye.
// Try reading a newspaper when your eye is one centimeter a way from the page ...
// The camera object (see the STATE_camera_ API ) which is the computer eye for rendering, act
// similarly to the human eye. This function determines the closest distance in which the camera
// is able to see objects. The parts of objects that are closer than this number will not be seen.
// Calling this function with a number too small has its price.
// The bigger this number is the more accurate the rendering of the objects will be
// On the other hand a number too big will hide objects that are near
// the camera. Typical values are 1, 4, 10, 20 100.
// Try to make this number as big as you can. Stop increasing this number
// when near objects are not drawn.
//
// Important :
// In some cases increasing the number can improve the rendering speed dramatically.
//
// return OK or VR_ERROR
STATE_IMPORT void STATE_WINAPI STATE_camera_set_distance_from_eye(DWORD camera_handle, double distance);
//See STATE_camera_set_distance_from_eye()
STATE_IMPORT double STATE_WINAPI STATE_camera_get_distance_from_eye(DWORD camera_handle);
// Creates a camera and returns a handle to that camera
// Note that the values for the camera setting (location, direction , field view etc ...)
// are given default values. In probably all cases you
// would like to set those values yourself before you
// You use the camera specially the location and the direction
// given parameters
//-----------------
// camera_name: a string that identifies the camera. Usually this
// string wont be in use since it is more efficient to
// retrieve a camera using the handle (the return value of this
// function).
// see also STATE_camera_recreate() STATE_camera_save()
STATE_IMPORT DWORD STATE_WINAPI STATE_camera_create(char *camera_name);
// returns the last camera that was used with STATE_engine_render();
STATE_IMPORT DWORD STATE_WINAPI STATE_camera_get_current(void);
// The current camera is the camera that was used in the last render.
// Many functions such as STATE_engine_3D_point_to_2D(), STATE_engine_2D_point_to_3D, is_movement_possible() and more, dont take
// a camera_handle as one of their parameters instead they do
// STATE_camera_get_current() ( note that the result of functions such as STATE_engine_2D_point_to_3D() depends on the camera that is used)
// This assumption is usually correct though in some occasions you might want to call STATE_engine_2D_point_to_3D() (or similar functions )for a camera
// other then the one that was used in the last render. For these occasions you will need
// to call STATE_camera_set_current().
// If you are rendering on more than one window then you are most likely to use STATE_camera_set_current()
// (for example, if you render on 3 different windows with three different camera and then you do STATE_engine_3D_point_to_2D()
// How will the engine know with which windowcamera you want this calculation to be done).
// STATE_camera_set_current() takes little time to execute so if you are in doubt, there is no harm in calling this function.
//
// If your program doesn't call STATE_engine_render() at all then you will need to call STATE_camera_set_current()
// in order that the engine will know what camera to use for calculations done in functions such as STATE_engine_2D_point_to_3D()
//
// hwnd is the window that we are using the camera with
// ( If you are using MFC you can do CWnd->m_hWnd )
STATE_IMPORT int STATE_WINAPI STATE_camera_set_current(DWORD camera_handle, HWND hwnd);
//STATE_IMPORT int STATE_WINAPI STATE_camera_set_current(DWORD camera_handle);
// Returns a handle to the first camera that was created.
STATE_IMPORT DWORD STATE_WINAPI STATE_camera_get_default_camera(void);
//save the current status of the given camera to the given buffer
// later a camera with the same status (location, direction, field_of_view etc ...)
// can be created using the given buffer.
STATE_IMPORT void STATE_WINAPI STATE_camera_save(DWORD camera_handle, DWORD save_buffer[CAMERA_DESCRIPTOR_SIZE]);
// creates a new camera and returns the handle to that camera
// The new camera status (location, direction, field_of_view etc ...) is
// set according to the data in restore_buffer.
// this buffer should be filled before calling this function
// using STATE_camera_save(). This mechanism could be used to
// duplicate cameras. Another usage could be to send the buffer across
// the internet so that the same camera could be created on
// the far computer. see also STATE_camera_create()
STATE_IMPORT DWORD STATE_WINAPI STATE_camera_recreate(char *camera_name, DWORD restore_buffer[CAMERA_DESCRIPTOR_SIZE]);
// The new camera status (location, direction, field_of_view etc ...) is
// set according to the data in "values_data" buffer.
// this buffer should be filled before calling this function
// using STATE_camera_save().
STATE_IMPORT void STATE_WINAPI STATE_camera_set_values(DWORD camera_handle, DWORD values_data[CAMERA_DESCRIPTOR_SIZE]);
// return the width of the core image created on the camera film
// this value multiplied by the value return from STATE_camera_get_height()
// indicates the quality of the picture that will be created
// you can modify the picture quality by using the following functions
// 1- STATE_engine_set_picture_quality(int quality);
// 2- STATE_engine_increase_picture_quality(void);
// 3- STATE_engine_decrease_picture_quality(void);
STATE_IMPORT int STATE_WINAPI STATE_camera_get_width(DWORD camera_handle);
STATE_IMPORT int STATE_WINAPI STATE_camera_get_height(DWORD camera_handle);
// Set the direction towards which the camera will point .
//
// Example:
//
// DWORD camera=STATE_camera_get_default_camera();
// //Make the camera points towards the positive Y axis (pointing right)
// STATE_camera_set_direction(camera, 0,1,0);
//
// Remarks:
// Note that STATE_camera_set_direction(camera, 10,20,30);
// has exactly the same result as STATE_camera_set_direction(camera, 1,2,3);
//
// For more information about coordination systems and setting directions see the book (download the book free from www.3dstate.com )
//
// See also: STATE_camera_set_direction1()
//
STATE_IMPORT void STATE_WINAPI STATE_camera_set_direction(DWORD camera_handle, double x, double y, double z);
// Set the direction towards which the camera will point. Exactly the same as the function STATE_camera_set_direction()
// only that here we use just 1 parameter.
//
// Example:
//
// double xyz[3]={10,20,30}; //Note that setting 10,20,30 is the same as 1,2,3 (the engine normalizes the vector (make it a unit vector) )
// DWORD camera=STATE_camera_get_default_camera();
// STATE_camera_set_direction1(camera, xyz);
//
// Remarks:
//
// For more information about coordination systems and setting directions see the book (download the book free from www.3dstate.com )
//
// See also STATE_camera_set_direction()
//
STATE_IMPORT void STATE_WINAPI STATE_camera_set_direction1(DWORD camera_handle, double xyz[3]);
// Returns the direction towards which the camera points.
//
//
// Example A:
//
// double x,y,z;
// DWORD camera=STATE_camera_get_default_camera();
// STATE_camera_get_direction(camera, &x, &y, &z);
//
// Example B:
//
// //Note that instead of doing it as shown below, it is easier to use the function STATE_camera_get_direction1() instead
// double xyz[3];
// DWORD camera=STATE_camera_get_default_camera();
// STATE_camera_get_direction(camera, &xyz[0], &xyz[1], &xyz[2]);
//
//
//
// See also STATE_camera_get_direction1()
//
//
// Remarks:
//
// The returned direction is normalized (meaning it is a unit vector)
// For more information about coordination systems and setting directions see the book (download the book free from www.3dstate.com )
//
STATE_IMPORT void STATE_WINAPI STATE_camera_get_direction(DWORD camera_handle, double *x, double *y, double *z);
// Returns the direction towards which the camera points. Exactly the same as the function STATE_camera_get_direction()
// only that here we use just 1 parameter.
//
// Example:
//
// double xyz[3];
// DWORD camera=STATE_camera_get_default_camera();
// STATE_camera_get_direction1(camera, xyz);
//
//
//
// See also STATE_camera_get_direction()
//
//
// Remarks:
//
// The returned direction is normalized (meaning it is a unit vector)
// For more information about coordination systems and setting directions see the book (download the book free from www.3dstate.com )
//
STATE_IMPORT void STATE_WINAPI STATE_camera_get_direction1(DWORD camera_handle, double xyz[3]);
//Gets a pointlocation in the world and make the camera point at this location
// See also STATE_camera_point_at_2D(), STATE_engine_2D_point_to_3D()
STATE_IMPORT void STATE_WINAPI STATE_camera_point_at(DWORD camera_handle, double x, double y, double z);
// Gets a two dimensional point=> (x,y) is a point in the rendered window
// Usually we get this point from events like OnLButtonDown()
// The function calculates the corresponding three dimensional point
// in the world and sets the camera to point towards this point.
// If there is no corresponding 3D point then it returns VR_ERROR
// (happens when we point to an empty place in the rendered image.
// see also STATE_camera_point_at() and STATE_engine_2D_point_to_3D();
STATE_IMPORT int STATE_WINAPI STATE_camera_point_at_2D(DWORD camera_handle, int x, int y);
// Set the location of the camera
//
// Example A:
//
// DWORD camera=STATE_camera_get_default_camera();
// STATE_camera_set_location(camera, 10, 20, 30);
//
// Example B:
//
// double x=10,y=20,z=30;
// DWORD camera=STATE_camera_get_default_camera();
// STATE_camera_set_location(camera, x, y, z);
//
// Example C:
//
// //Note that instead of doing it as shown below, it is easier to use the function STATE_camera_set_location1() instead
// double xyz[3]={10,20,30};
// DWORD camera=STATE_camera_get_default_camera();
// STATE_camera_set_location(camera, xyz[0], xyz[1], xyz[2]);
//
// See also STATE_camera_set_location1()
//
STATE_IMPORT void STATE_WINAPI STATE_camera_set_location(DWORD camera_handle, double x, double y, double z);
// Set the location of the camera. Exactly the same as the function STATE_camera_set_location()
// only that here we use just 1 parameter.
//
// Example:
//
// double xyz[3]={10,20,30};
// DWORD camera=STATE_camera_get_default_camera();
// STATE_camera_set_location1(camera, xyz);
//
// See also STATE_camera_set_location()
//
STATE_IMPORT void STATE_WINAPI STATE_camera_set_location1(DWORD camera_handle, double xyz[3]);
//Returns the location of the camera.
//
// Example A:
//
// double x,y,z;
// DWORD camera=STATE_camera_get_default_camera();
// STATE_camera_get_location(camera, &x, &y, &z);
//
// Example B:
//
// //Note that instead of doing it as shown below, it is easier to use the function STATE_camera_get_location1() instead
// double xyz[3];
// DWORD camera=STATE_camera_get_default_camera();
// STATE_camera_get_location(camera, &xyz[0], &xyz[1], &xyz[2]);
//
//
//
// See also STATE_camera_get_location1()
//
STATE_IMPORT void STATE_WINAPI STATE_camera_get_location(DWORD camera_handle, double *x, double *y, double *z);
// Returns the location of the camera. Exactly the same as the function STATE_camera_get_location()
// only that here we use just 1 parameter.
//
// Example:
//
// double xyz[3];
// DWORD camera=STATE_camera_get_default_camera();
// STATE_camera_get_location(camera, xyz);
//
// See also STATE_camera_get_location()
//
STATE_IMPORT void STATE_WINAPI STATE_camera_get_location1(DWORD camera_handle, double xyz[3]);
//Sets the axis system of the camera explicitly.
// X,Y,Z are three unit vectors that defines the view space. -X is the direction
// of viewing.
// One of the useful usage of this function together with STATE_camera_get_axis_system() and getset location
// is to save the camera exact position.
//The function works exactly like STATE_object_set_axis_system()
//See STATE_object_set_axis_system() for more information.
// Returns OK or VR_ERROR
STATE_IMPORT int STATE_WINAPI STATE_camera_set_axis_system(DWORD camera_handle, double X[3], double Y[3], double Z[3]);
//Gets the axis system of the camera..
// X,Y,Z are three unit vectors that defines the view space. -X is the direction
// of viewing.
// One of the useful usage of this function together with STATE_camera_set_axis_system() and getset location
// is to save the camera exact position.
// See also STATE_camera_set_axis_system()
STATE_IMPORT void STATE_WINAPI STATE_camera_get_axis_system(DWORD camera_handle, double X[3], double Y[3], double Z[3]);
// Returns the new tilt angle
// examples:
// tilt 0 mean looking straight.
// tilt 90 looking up
// tilt -90 means looking down
STATE_IMPORT double STATE_WINAPI STATE_camera_set_tilt(DWORD camera_handle, double angle);
// Returns the new tilt angle
// examples:
// tilt 0 mean looking straight.
// tilt 90 looking up
// tilt -90 means looking down
STATE_IMPORT double STATE_WINAPI STATE_camera_get_tilt(DWORD camera_handle);
// Returns the new tilt angle
// examples:
// 90 means rotate camera 90 degrees up
// -90 means rotate camera 90 degrees down
// The rotation is done in world cords (rather then in object cords)
STATE_IMPORT double STATE_WINAPI STATE_camera_modify_tilt(DWORD camera_handle, double change);
//Changes the location of the camera by the given X,Y,Z offset
// New_location=old_location + (X,Y,Z)
// space_flag could be WORLD_SPACE or CAMERA_SPACE
// space_flag determines if the step is according to the camera's
// coordinate system or the world coordinate system.
// For example if space_flag==CAMERA_SPACE and step==(-1,0,0)
// This means that the camera will advance forward.
// Try both options and see what happens.
STATE_IMPORT void STATE_WINAPI STATE_camera_move(DWORD camera_handle, int space_flag, double x, double y, double z);
//This is an important function. It helps in moving the camera nicely
//so it doesn't go through polygons.
//The function tries to move the camera to the given wanted location.
//If it is impossible because of collision, it tries to move as close as it can
//In every respected game, when the player moves towards a wall, his movement won't be stopped
//when he hits the wall. Instead the player will move smoothly along the wall.
//Using this function one can achieve this effect automatically.
//
// Parameters:
//
// DWORD camera,
// The camera that we want to move
//
// double wanted_location[3],
// The location in world space coordinates where we want to move the camera
//
// double camera_physical_width
// The physical camera is actually a point though in order to
// simulate real life the engine apply real dimensions to the camera
// The size of the camera is calculated as a square with the dimension
// camera_physical_width x camera_physical_width
// The smaller this number is the more we will be able to get nearer to the walls in the world.
//
//Return value
// Returns YES or NO. YES is returned if the camera was moved. NO is returned
// if the function could not move the camera at all
//
STATE_IMPORT int STATE_WINAPI STATE_camera_move_with_collision_detection(DWORD camera, double wanted_location[3], double camera_physical_width);
//Move the camera up or down so its height above the ground
//is according to the given parameters.
//This function is quite useful, usually one calls it before moving the camera.
//Imagine for example that we have stairs to climb. If calling this function
// and then moving the camera forward the result will be a very natural stairs climbing.
// Note that this function is very simple inside. Some people might not use this function and
// would rather write their own code.
//
// Return Value.
// Returns a handle to the polygon bellow.
// If there is nothing below it will return NULL
// Parameters:
// camera_handle: the camera to be dropped.
//
// double height_above_ground : set this argument to the desire height above the ground.
//
// gravity : The maximum fall that the camera is allowed to make for each call of the function.
// For example if the camera falls down from a building. The bigger this number is
// the fewer calls (to this function) it will take till the camera reaches the ground.
// In other words if the camera height above the ground is 100 and the camera is moving forward
// on the top of a building, once it falls from the building the camera height from the floor will suddenly be
// quite a big number, lets say 10000. If the gravity is 50 then after calling this function the camera will be set
// at a height of 10000-50 above the ground.
// If you didn't get all of this it doesn't matter, try different values till you reach the desired effect.
//
//
// point_on_the_ground : The function returns through this parameter a point on the ground that is exactly
// bellow the camera. If there is no polygon bellow the camera then this parameter will hold (0,0,0)
//
//
// Example
// double point_on_the_ground[3];
// DWORD floor_polygon=STATE_camera_set_height_above_ground(my_camera, 100, 40,point_on_the_ground);
// if(floor_polygon==NULL)
// error_message("We are walking on air !!!);
//
//
STATE_IMPORT DWORD STATE_WINAPI STATE_camera_set_height_above_ground(DWORD camera_handle, double height_above_ground, double gravity ,double point_on_the_ground[3]);
//The function is not in use
// Returns the new focus distance
STATE_IMPORT double STATE_WINAPI STATE_camera_set_focus(DWORD camera_handle, double focus_distance);
//The function is not in use
// Returns the new focus distance
STATE_IMPORT double STATE_WINAPI STATE_camera_modify_focus(DWORD camera_handle, double change_in_focus_distance);
// Returns the new field of view angle
// the field of view could be anything between 1 to 179 degrees
// field of view == 1 means a very strong zoom in
// field of view == 179 means a very strong zoom out
STATE_IMPORT double STATE_WINAPI STATE_camera_set_zoom(DWORD camera_handle, double field_of_view_angle);
STATE_IMPORT double STATE_WINAPI STATE_camera_get_zoom(DWORD camera_handle);
//Changes the current field of view
// New_vield_of_view = old_field_of_view + field_of_view_change
// field_of_view_change could be positive or negative.
// Returns the new field of view angle
STATE_IMPORT double STATE_WINAPI STATE_camera_modify_zoom(DWORD camera_handle, double field_of_view_change);
// Sets the new head angle (also the return value)
// examples:
// 0 means look forward into the screen
// 90 means look left
// -90 or 270 means look right
// 180 means camera looking from the screen out
// if we add or subtract 360*n to the angle it
// will be the same
STATE_IMPORT double STATE_WINAPI STATE_camera_set_head_angle(DWORD camera_handle, double head_angle);
// Returns the new head angle
// Could be use the determine absolute direction (North, Soth , West, East ...)
// examples:
// 0 means look forward into the screen (in the opposite direction of the world X axis)
// 90 means look left (in the opposite direction of the world Y axis)
// -90 or 270 means look right (in the direction of the world Y axis)
// 180 means camera looking from the screen out (in the direction of the world X axis)
// Adding or subtracting 360*n to the angle has no influence on the result
STATE_IMPORT double STATE_WINAPI STATE_camera_get_head_angle(DWORD camera_handle);
// Returns the new head angle
// examples:
// 0 do nothing (can be use as get_current_head_angle() ...)
// 90 means turn 90 degrees counterclockwise
// 90 means turn 90 degrees clockwise.
// 180 means camera turns half a circle
STATE_IMPORT double STATE_WINAPI STATE_camera_modify_head_angle(DWORD camera_handle, double head_angle);
// Returns the new bank angle
// the angle is given in degrees from the horizon
// examples:
// 0 means looking straight.
// 90 means turned 90 degrees clockwise
// -90 means turned 90 degrees clockwise
// giving alpha +360*k (k= ... -5,-4 , .... 0, 1 ,2 ...)
// is the same as giving alpha
STATE_IMPORT double STATE_WINAPI STATE_camera_set_bank(DWORD camera_handle, double angle);
// Returns the new bank angle
// the angle is given in degrees from the horizon
// examples:
// 0 means looking straight.
// 90 means turned 90 degrees clockwise
// -90 means turned 90 degrees clockwise
// The return value is in the range -90 - 270
STATE_IMPORT double STATE_WINAPI STATE_camera_get_bank(DWORD camera_handle);
// Returns the new bank angle
// the angle is given in degrees from the horizon
// examples:
// 0 means looking straight.
// 90 means turned 90 degrees clockwise
// -90 means turned 90 degrees clockwise
STATE_IMPORT double STATE_WINAPI STATE_camera_modify_bank(DWORD camera_handle, double change);
// Rotates the camera in the given angle.
// space_flag can be OBJECT_SPACE or WORLD_SPACE
// space_flag determines if the step is according to the camera's
// coordinate system or the world coordinate system.
// For example if space_flag==CAMERA_SPACE and step==(-1,0,0)
// This means that the camera will advance forward.
// Try both options and see what happens.
STATE_IMPORT void STATE_WINAPI STATE_camera_rotate_x(DWORD camera_handle, double degrees, int space_flag);
STATE_IMPORT void STATE_WINAPI STATE_camera_rotate_y(DWORD camera_handle, double degrees, int space_flag);
STATE_IMPORT void STATE_WINAPI STATE_camera_rotate_z(DWORD camera_handle, double degrees, int space_flag);
// The same just with radians.
// space flag can be OBJECT_SPACE or WORLD_SPACE
STATE_IMPORT void STATE_WINAPI STATE_camera_rotate_x_radians(DWORD camera_handle, double radians, int space_flag);
STATE_IMPORT void STATE_WINAPI STATE_camera_rotate_y_radians(DWORD camera_handle, double radians, int space_flag);
STATE_IMPORT void STATE_WINAPI STATE_camera_rotate_z_radians(DWORD camera_handle, double radians, int space_flag);
//Converts a point in camera space to a point in world space.
// Returns OK or VR_ERROR if failed
//Here are some examples:
// The location of the camera (world space) will always translate to (0,0,0) in camera space
// (-1,0,0) in camera space is one unit in front of the camera this is equal to
// the camera location plus the camera direction (a unit vector) in camera space.
// (1,0,0) in camera space is one unit in the back of the camera
// (0,1,0) in camera space is always one unit to the right of the camera.
// (0,-1,0) in camera space is always one unit to the left of the camera.
// (0,0,1) in camera space is always one unit up above the camera.
//See also STATE_camera_convert_point_to_camera_space()
STATE_IMPORT int STATE_WINAPI STATE_camera_convert_point_to_world_space(DWORD camera_handle, double camera_space_point[3], double result[3]);
//Converts a point in world space to a point in camera space.
// Returns OK or VR_ERROR if failed
//Here are some examples:
// The point (0,0,0) in camera space will always translate to the location of the camera in world space
// (-1,0,0) in camera space is one unit in front of the camera this is equal to
// the camera location plus the camera direction (a unit vector) in camera space.
// (1,0,0) in camera space is one unit in the back of the camera
// (0,1,0) in camera space is always one unit to the right of the camera.
// (0,-1,0) in camera space is always one unit to the left of the camera.
// (0,0,1) in camera space is always one unit up above the camera.
//See also STATE_camera_convert_point_to_world_space()
STATE_IMPORT int STATE_WINAPI STATE_camera_convert_point_to_camera_space(DWORD camera_handle, double world_space_point[3], double result[3]);
// deletes a camera.
// remember not to use any handle after the instance was deleted
// doing:
// STATE_camera_delete(my_camera);
// my_camera=NULL;
// is good practice.
// returns OK or VR_ERROR
// VR_ERROR could be receive if there is no more camera with this handle
// (if we already deleted the camera before)
STATE_IMPORT int STATE_WINAPI STATE_camera_delete(DWORD camera_handle);
STATE_IMPORT void STATE_WINAPI STATE_camera_delete_all(void);
// *************************
//Returns the name of the track that the camera is associated with.
//See also STATE_camera_set_track()
STATE_IMPORT char * STATE_WINAPI STATE_camera_get_track_name(DWORD camera_handle);
STATE_IMPORT DWORD STATE_WINAPI STATE_camera_get_track_handle(DWORD camera_handle);
// Returns VR_ERROR, OK
// if track_handle ==NULL it doesn't cancel the chase type so
// for canceling chasing use STATE_camera_set_chase_type(NO_CHASE);
// Automatically set the closest point on the track (closest to the object)
// as the next point to go towards (to override this setting use STATE_camera_set_next_point_on_track() )
STATE_IMPORT int STATE_WINAPI STATE_camera_set_track(DWORD camera_handle, DWORD track_handle);
// return OK or VR_ERROR
// the offset is return through argument "offset"
STATE_IMPORT int STATE_WINAPI STATE_camera_get_track_offset(DWORD camera_handle, double offset[3]);
// return OK or VR_ERROR
STATE_IMPORT int STATE_WINAPI STATE_camera_set_track_offset(DWORD camera_handle, double offset[3]);
// Returns an index to a point on the track. This point is the point that the camera is moving towards
// The exact cords of the point can be retrieved through STATE_track_get_point()
// 0 is the first point and number_of_points-1 is the last index (use STATE_track_get_number_of_points() to get this number
STATE_IMPORT int STATE_WINAPI STATE_camera_get_next_point_on_track(DWORD camera_handle);
// returns the point on the track that the camera is moving towards
// 0 is the first point and number_of_points-1 is the last index (use STATE_track_get_number_of_points() to get this number
// if point_index<0 then it set it to 0
// if point_index is bigger than the maximum index then it is set to the maximum allowed. In those cases it returns VR_ERROR
// to notify the change from the given value.
// If there is no track associated with the camera it returns VR_ERROR without setting the value
STATE_IMPORT int STATE_WINAPI STATE_camera_set_next_point_on_track(DWORD camera_handle, int point_index);
// Set the object to chase after
// the given arguments should NOT be NULL
// Note that if the camera was previously chasing a camera or a group
// , those chasing operation are canceled. (The camera can chase only one thing at a time).
STATE_IMPORT void STATE_WINAPI STATE_camera_set_object_to_chase(DWORD camera_handle, DWORD object_to_chase_handle);
// If the return value is NULL it means no object is being chased
STATE_IMPORT DWORD STATE_WINAPI STATE_camera_get_chased_object(DWORD camera_handle);
// Set the camera to chase after
// the given argument should NOT be NULL
// Note that if the camera was previously chasing an object or a group
// , those chasing operation are canceled. (The camera can chase only one thing at a time).
STATE_IMPORT void STATE_WINAPI STATE_camera_set_camera_to_chase(DWORD camera_handle, DWORD camera_to_chase_handle);
// If the return value is NULL it means no camera is being chased
STATE_IMPORT DWORD STATE_WINAPI STATE_camera_get_chased_camera(DWORD camera_handle);
// Set the group to chase after
// the given argument should NOT be NULL
// Note that if the camera was previously chasing a camera or an object
// , those chasing operation are canceled. (The camera can chase only one thing at a time).
STATE_IMPORT void STATE_WINAPI STATE_camera_set_group_to_chase(DWORD camera_handle, DWORD group_to_chase_handle);
// If the return value is NULL it means no group is being chased
STATE_IMPORT DWORD STATE_WINAPI STATE_camera_get_chased_group(DWORD camera_handle);
// return OK or VR_ERROR
// the offset is return through argument "offset"
STATE_IMPORT int STATE_WINAPI STATE_camera_get_chase_offset(DWORD camera_handle, double offset[3]);
// return OK or VR_ERROR
STATE_IMPORT int STATE_WINAPI STATE_camera_set_chase_offset(DWORD camera_handle, double offset[3]);
// The returned number is between 0 and one.
// A number close to 0 means that the tracking is weak
// 1 means that the tracking is very sharp.
STATE_IMPORT double STATE_WINAPI STATE_camera_get_chase_softness(DWORD camera_handle);
// The returned number is between 0 and one
// a number close to 0 means that the tracking is weak
// 1 means that the tracking is very sharp.
// it the given number is bigger than one it is set as one
// if it is smaller than 0 than it set as 0
STATE_IMPORT void STATE_WINAPI STATE_camera_set_chase_softness(DWORD camera_handle, double softness);
// look in the header file for possible values and their meanings
// (look for NO_CHASE, CHASE_LOCATION and others ...)
STATE_IMPORT int STATE_WINAPI STATE_camera_get_chase_type(DWORD camera_handle);
// look in the header file for possible values and their meanings
// (look for NO_CHASE, CHASE_LOCATION and others ...)
STATE_IMPORT void STATE_WINAPI STATE_camera_set_chase_type(DWORD camera_handle, int chase_type);
STATE_IMPORT void STATE_WINAPI STATE_camera_set_chase_distance(DWORD camera_handle, double chase_distance);
STATE_IMPORT double STATE_WINAPI STATE_camera_get_chase_distance(DWORD camera_handle);
// ************************
// Advance the object on the track according to its
// track, track_speed, track_offset, chase_offset, target_point_on_track and chasing softness
// Use STATE_camera_advance() instead (set the right chase type before calling ...)
// XXXX STATE_IMPORT void STATE_WINAPI STATE_camera_advance_on_track(DWORD camera_handle);
// Advance the camera according to its chase_type
STATE_IMPORT void STATE_WINAPI STATE_camera_advance(DWORD camera_handle);
//Relevant only when CHASE_PHYSICS is used.
//Set the speed of the camera.
// Example
// //Give the camera speed of 10 in the positive direction of the Y axis
// STATE_camera_set_speed(camera, 0,10,0);
//
// See also STATE_object_set_speed_units()
//
STATE_IMPORT void STATE_WINAPI STATE_camera_set_speed(DWORD camera_handle, double speed[3]);
STATE_IMPORT void STATE_WINAPI STATE_camera_get_speed(DWORD camera_handle, double speed[3]);
//Returns the size of the speed.
//Using this function we can only retrieve the magnitude of the speed but not its direction.
//For example if the function returns 10, it means that the speed of the camera is 10.
//Q: "speed of ten" to which direction ?
//A: To know the direction of the speed call STATE_camera_get_speed()
//
STATE_IMPORT double STATE_WINAPI STATE_camera_get_absolute_speed(DWORD camera_handle);
//Relevant only when CHASE_PHYSICS or CHASE_TRACK is used.
//Set the size of the speed.
//
// Read the example below to learn how it all works.
//
// Example:
// STATE_camera_set_speed(camera, 0,10,0);
// speed_size=STATE_camera_get_absolute_speed(camera);
// //speed_size is now 10
//
// STATE_camera_set_absolute_speed(camera, 100);
//
// double speed[3];
// STATE_camera_get_speed(camera, speed);
// //speed is now { 0, 100, 0}
//
//
// Advanced:
// In physics speed is a vector it has a size and a direction
// Q: If the speed vector is 6,8,0 ( STATE_camera_set_speed(camera, 6,8,0) );
// what is the size of the speed (what will STATE_camera_get_absolute_speed(camera) return ?)
//
//
// A: Let calculate the vector size according to Pythagoras Theorem
// speed size= Square root of ( A*A+ B*B+ C*C ) = square root of ( 6*6 + 8*8 + 0*0) = Square root of (100) == 10
//
//
STATE_IMPORT void STATE_WINAPI STATE_camera_set_absolute_speed(DWORD camera_handle, double speed);
// Set the force that will work on the camera. For example to simulate gravity force
// do like that:
// double force[3];
// force[0]=0;
// force[1]=0;
// force[2]= -10; //simulate gravity 10 in the direction of the -Z axis.
// STATE_camera_set_force(my_camera,force);
//
// Note that this will only relevant when CHASE_PHYSICS is applyed
STATE_IMPORT void STATE_WINAPI STATE_camera_get_force(DWORD camera_handle, double force[3]);
STATE_IMPORT void STATE_WINAPI STATE_camera_set_force(DWORD camera_handle, double force[3]);
//Limits the maximum possible speed of a camera
//If there is no limit then by applying force on the camera
//The speed could reach infinity (unless some friction is given too)
//Note that this will only relevant when CHASE_PHYSICS is applyed
STATE_IMPORT void STATE_WINAPI STATE_camera_set_max_speed(DWORD camera_handle, double value);
STATE_IMPORT double STATE_WINAPI STATE_camera_get_max_speed(DWORD camera_handle);
//Friction is a value smaller or equal to 1
// if friction==0 it means no friction
// if friction==1 it means infinite friction nothing can move
// if friction is smaller than 0, it acts like pressing on the gas
// The exact calculation.
// Each render the absolute_speed is multiply with (1-friction).
//
// Note, a negative number can used for increasing the speed.
// a friction of -1 will double the speed.
// -2 will multiply the speed by three each rendering.
// so choose number carefully.
// typical numbers can be 0.03 or -0.03 etc ...
STATE_IMPORT void STATE_WINAPI STATE_camera_set_friction(DWORD camera_handle, double value);
STATE_IMPORT double STATE_WINAPI STATE_camera_get_friction(DWORD camera_handle);
//This number is used when the camera hits a polygon.
//A value of one will make the new speed (after collision)
//equal to the old speed (effects only the absolute speed value and not the direction)
//a value of 0.5 will cut speed by half.
//We can also give values greater than one.
//For example a value of 2 will make the new speed twice as big
//as before the collision.
STATE_IMPORT void STATE_WINAPI STATE_camera_set_elasticity(DWORD camera_handle, double value);
STATE_IMPORT double STATE_WINAPI STATE_camera_get_elasticity(DWORD camera_handle);
// (left_x, top_y) and (right_x ,bottom_y) are points on the window that
// was used to render an image using the given camera.
// The function returns through new_location a location that if we would
// do STATE_camera_set_location() the rectangle area will fill our screen
// returns OK or VR_ERROR
STATE_IMPORT int STATE_WINAPI STATE_camera_get_location_to_fit_rectangle(DWORD camera_handle, int left_x, int top_y, int right_x, int bottom_y, double new_location[3]);
// x,y are points on the window
// usually we get this point from events like OnLButtonDown()
// The function moves the camera towards the point (or far from the point depending
// on the given value, factor).
// Note that the direction of the camera doesn't change. (Use STATE_camera_point_at() to make the target point at the center)
// returns OK, VR_ERRORR.
// factor can be any number. Here are some examples:
// factor== -2 , the camera will triple its distance from the given point
// factor== -1 , the camera will double its distance from the given point
// factor==0 means, the camera wont move
// factor==0.5 the camera will move half way to the point
// factor==1 the camera will move to the given point x,y
// factor==2 the camera will pass the point (will be in the same distance but on the other side of the line that connects the point and the line).
STATE_IMPORT int STATE_WINAPI STATE_camera_move_toward_point_2D(DWORD camera_handle, int x, int y, double factor);
// advance all the cameras. If STATE_engine_advance_cameras_automatically(YES) is called
// then this function will be called automatically each time we do render
STATE_IMPORT void STATE_WINAPI STATE_camera_advance_all();
STATE_IMPORT void STATE_WINAPI STATE_camera_set_name_to_chase(DWORD camera_handle, char *name_to_chase);
STATE_IMPORT char * STATE_WINAPI STATE_camera_get_name_to_chase(DWORD camera_handle);
// sending YES will write the given camera to file after call to STATE_engine_save() with SAVE_ONLY_WHATS_NEEDED
// Note that it if STATE_engine_save() is called without SAVE_ONLY_WHATS_NEEDED, all the cameras will be saved
// sending NO will cause STATE_engine_save() not to save this camera (only if SAVE_ONLY_WHATS_NEEDED is used)
// The default value is NO
// see also STATE_animation_set_save_flag()
STATE_IMPORT void STATE_WINAPI STATE_camera_set_save_flag(DWORD camera_handle, int yes_no_flag);
// returns YES or NO
// The default value is NO
// see STATE_camera_set_save_flag() for more details
STATE_IMPORT int STATE_WINAPI STATE_camera_get_save_flag(DWORD camera_handle);
// Some words about parallel and perspective projection:
// Though we have a 3D world eventually when we create an image
// of that world it is a 2D image. In order to get this image the engine
// projects the 3D world onto a projection plane. There are two main methods to do this projection
// They are called parallel projection and perspective projection.
// Perspective projection (the default ) is similar to the way the human
// eye sees things. Far away objects look smaller while closer objects look bigger.
// Parallel projection is the same as orthographic projection.
// The depth dimension is not shown on the result image.
// If you never heard of projection method simply try both method
// and see what happens. For the vast majority of applications
// you will use only perspective projection (the default)
// Parallel projection should interest you only if your application is in fields such as
// Architecture design, 3D modeling etc ...
// Parallel projection has little use in games if at all.
STATE_IMPORT void STATE_WINAPI STATE_camera_set_perspective_projection(DWORD camera_handle);
STATE_IMPORT void STATE_WINAPI STATE_camera_set_parallel_projection(DWORD camera_handle, int width, int heigh);
STATE_IMPORT int STATE_WINAPI STATE_camera_is_perspective_projection(DWORD camera_handle);
STATE_IMPORT int STATE_WINAPI STATE_camera_get_parallel_projection_width(DWORD camera_handle);
STATE_IMPORT int STATE_WINAPI STATE_camera_get_parallel_projection_height(DWORD camera_handle);
//Drops the camera down.
//In other words: Move the camera down till it is height_above_ground above the polygon below the camera
//If there is nothing below the camera then the location of the camera will not be changed.
//In many times the function STATE_engine_ignore_dynamic_objects_for_collision_detection(YES);
// will be called before dropping down the camera. This will make the camera fall through dynamic objects
//
// Return value:
// returns a handle to the polygon below the camera
//
// parameters:
// object_handle: the camera to be dropped
//
// height_above_ground: the height above the polygon below the camera in which the camera should be positioned.
//
//
// Examples:
// A) //drop the camera down
// STATE_camera_drop_down(my_camera, 100); //put the camera 100 units above the ground
//
// B) //drop the camera through objects
// STATE_engine_ignore_dynamic_objects_for_collision_detection(YES);
// STATE_camera_drop_down(my_camera, 100); //put the camera 100 units above the ground
// STATE_engine_ignore_dynamic_objects_for_collision_detection(NO); //restore regular collision detection
STATE_IMPORT DWORD STATE_WINAPI STATE_camera_drop_down(DWORD camera_handle, double height_above_ground);
// Who needs this function ?
// --------------------------
// Users that are porting code from other 3D engines might want to use this function.
// All the rest can skip this function
//
// General background
// ------------------
// Please note that when moving or rotating the camera all that the engine does is change
// the camera's matrix which is a quick and fast to do.
//
//
// What is this matrix ?
// ---------------------
// To learn more about transformation matrixes you should read a computer graphics math book.
// This is just if you are interested in the subject. One of the great things about the STATE engine
// is that it makes it completely unnecessary to learn these subjects.
// Anyhow, since you are still reading it means that you want to know more, so here it is:
// the first top 9 cells of the matrix are the rotation matrix
// The bottom row is the translation values.
// The diagnal is the scale values
//
// S R R 0
// R S R 0
// R R S 0
// T T T 1
//
// Above is the matrix. T stands for translation. S for scale. R for rotation.
// If you don't know what we are talking about then you should read a book in the subject
//
// By taking a point in camera space and multiplying it by the inverse_matrix we get the point in World Space.
// for example the point (0,0,0) in camera space is the location of the camera.
// when multiplying (0,0,0) by the inverse_matrix we get (T T T) which means that
// (T,T,T) is the camera location
// The code below shows how to multiply a point (vec) by the matrix (mat).
// The result is saved in dst.
//
// void mul_vec_mat(vector dst, vector vec, matrix mat) //does dst=vec*mat
// {
// double res[4];
// double one_over_res3;
//
//
// res[0]=vec[0]*mat[0][0] + vec[1]*mat[1][0] + vec[2]*mat[2][0] + mat[3][0];
// res[1]=vec[0]*mat[0][1] + vec[1]*mat[1][1] + vec[2]*mat[2][1] + mat[3][1];
// res[2]=vec[0]*mat[0][2] + vec[1]*mat[1][2] + vec[2]*mat[2][2] + mat[3][2];
// res[3]=vec[0]*mat[0][3] + vec[1]*mat[1][3] + vec[2]*mat[2][3] + mat[3][3];
//
// if(res[3]<1e-20 && res[3]>-1e-20) { //protect agains floating point errors.
// ERROR_MSG(SCREEN,"mul_vec_mat: devision by zeron");
//
// dst[0]=res[0];
// dst[1]=res[1];
// dst[2]=res[2];
// return;
// }
//
// one_over_res3=1/res[3];
//
// dst[0]=res[0]*one_over_res3;
// dst[1]=res[1]*one_over_res3;
// dst[2]=res[2]*one_over_res3;
//
// }
//
//
// Parametar:
// ----------
//
// camera_handle: the camera handle
//
// camera_matrix: The camera matrix. Note that multiplying a point in world space by this matrix will result
// a point in camera space.
//
// inverse_matrix: The inverse of camera_matrix. Multiplying a point in camera space by this matrix will
// result a point in world space.
//
//
// Example:
//
// double matrix[4][4], int_matrix[4][4];
// STATE_camera_get_transformation_matrix(my_camera, matrix);
//
STATE_IMPORT void STATE_WINAPI STATE_camera_get_transformation_matrix(DWORD camera_handle, double camera_matrix[4][4], double inverse_matrix[4][4]);
//-----------------------------------------------------//
//======== T H E O B J E C T A P I ==============//
//-----------------------------------------------------//
// This API is used in viewer_mode to manipulate moving objects (also referredcalled dynamic objects)
//
// See also the GROUP API for manipulating things in EDITOR mode.
// Note that some of group API are also working in viewer mode
// (those that do not move polygons or change them) but not the other way around.
// Returns YES or NO.
// YES , if the given handle is an object handle. NO if not.
// If it is not an object handle , a message box will appear,
// the title of this message box will be the parameter "function_asking"
// if function_asking==NULL than no popup will be created.
// See also IS_OBJECT()
STATE_IMPORT int STATE_WINAPI STATE_object_is_object(DWORD object_handle, char *function_asking);
// Checks whether a given object can move from one point to another inside the world
// Return value: YES or NO.
// If movement is possible the function will return 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])
// on return blocking_object is the object that make movement impossible
// if the return value is NO and blocking_object==NULL it means
// that what blocks us is the static part of the world.
// the difference between this function end STATE_engine_is_movement_possible()
// is that here we also give the handle to the dynamic object that wants to move.
// This handle is needed so that the function can eliminate the object itself
// from being the obstacle that makes the movement impossible.
// see also remarks on STATE_engine_is_movement_possible()
//
// Arguments:
// object_handle: The object that we want to move. The engine will disable this object
// for doing the collision detection as explained in the remarks above.
//
// start_point, end_point: The function will check collision between the world and a line going from start_point to end_point
//
// intersected_polygon: If there is a collision going from the start point to the end point then the function will return
// the blocking polygon using this argument.
//
// intersection: an x,y,x point on the intersected_polygon where the line from start_point to end_point intersects
//
// blocking_object: If the intersection is caused because of another dynamic object that the blocking object will be returned
// using 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_point[3]={1,2,3};
// double end_point[3]={100,200,300};
// DWORD intersected_polygon;
// double intersection[3];
// DWORD blocking_object[3];
// STATE_object_is_movement_possible(my_object ,start_location, end_location, &intersected_polygon, intersection, &blocking_object);
//
STATE_IMPORT int STATE_WINAPI STATE_object_is_movement_possible(DWORD object_handle ,double start_location[3], double end_location[3], DWORD *intersected_polygon, double intersection[3], DWORD *blocking_object);
//Searches for an object with this name.
// If no object has this name then it
// returns a NULL
// If there are several objects with the same name then
// it returns the first one.
STATE_IMPORT DWORD STATE_WINAPI STATE_object_get_object_using_name(char *object_name);
// Returns the name of the given object
// The function returns a pointer to the name which is stored internally inside the 3D Engine
// Visual Basic users should use STATE_entity_get_name() instead.
// See also STATE_entity_get_namel()
STATE_IMPORT char *STATE_WINAPI STATE_object_get_name(DWORD object_handle);
STATE_IMPORT char *STATE_WINAPI STATE_object_get_type_name(DWORD object_handle);
// Returns OK if was successful else VR_ERROR;
// Arguments:
// new_name: the name to set for this object
//See also STATE_object_get_name(), STATE_object_get_object_using_name()
STATE_IMPORT int STATE_WINAPI STATE_object_set_name(DWORD object_handle, char *new_name);
// Returns OK if was successful else VR_ERROR;
STATE_IMPORT int STATE_WINAPI STATE_object_set_type_name(DWORD object_handle, char *new_name);
STATE_IMPORT int STATE_WINAPI STATE_object_get_object_type_number(DWORD object_handle);
STATE_IMPORT void STATE_WINAPI STATE_object_set_object_type_number(DWORD object_handle, int object_type_number);
STATE_IMPORT int STATE_WINAPI STATE_object_get_control_type_number(DWORD object_handle);
STATE_IMPORT void STATE_WINAPI STATE_object_set_control_type_number(DWORD object_handle, int control_type_number);
STATE_IMPORT char *STATE_WINAPI STATE_object_get_track_name(DWORD object_handle);
STATE_IMPORT DWORD STATE_WINAPI STATE_object_get_track_handle(DWORD object_handle);
// returns a handle to an object.
// Used in conjunction with STATE_object_get_next_object()
// to traverse all the existing objects
// example:
// for(handle=STATE_object_get_first_object() ; handle!=NULL ; handle=STATE_object_get_next_object(handle) )
// {
// ...
//
// }
STATE_IMPORT DWORD STATE_WINAPI STATE_object_get_first_object(void);
STATE_IMPORT DWORD STATE_WINAPI STATE_object_get_next_object(DWORD object_handle);
// Set the location of the object
//
// Example A:
//
// DWORD object=STATE_object_get_first_object();
// STATE_object_set_location(object, 10, 20, 30);
//
// Example B:
//
// double x=10,y=20,z=30;
// DWORD object=STATE_object_get_first_object();
// STATE_object_set_location(object, x, y, z);
//
// Example C:
//
// //Note that instead of doing it as shown below, it is easier to use the function STATE_object_set_location1() instead
// double xyz[3]={10,20,30};
// DWORD object=STATE_object_get_first_object();
// STATE_object_set_location(object, xyz[0], xyz[1], xyz[2]);
//
// See also STATE_object_set_location1()
//
STATE_IMPORT void STATE_WINAPI STATE_object_set_location(DWORD object_handle, double x, double y, double z);
// Set the location of the object. Exactly the same as the function STATE_object_set_location()
// only that here we use just 1 parameter.
//
// Example:
//
// double xyz[3]={10,20,30};
// DWORD object=STATE_object_get_first_object();
// STATE_object_set_location1(object, xyz);
//
// See also STATE_object_set_location()
//
STATE_IMPORT void STATE_WINAPI STATE_object_set_location1(DWORD object_handle, double xyz[3]);
//Returns the location of the object.
//
// Example A:
//
// double x,y,z;
// DWORD object=STATE_object_get_first_object();
// STATE_object_get_location(object, &x, &y, &z);
//
// Example B:
//
// //Note that instead of doing it as shown below, it is easier to use the function STATE_object_get_location1() instead
// double xyz[3];
// DWORD object=STATE_object_get_first_object();
// STATE_object_get_location(object, &xyz[0], &xyz[1], &xyz[2]);
//
//
//
// See also STATE_object_get_location1()
//
STATE_IMPORT void STATE_WINAPI STATE_object_get_location(DWORD object_handle, double *x, double *y, double *z);
// Returns the location of the object. Exactly the same as the function STATE_object_get_location()
// only that here we use just 1 parameter.
//
// Example:
//
// double xyz[3];
// DWORD object=STATE_object_get_first_object();
// STATE_object_get_location(object, xyz);
//
// See also STATE_object_get_location()
//
STATE_IMPORT void STATE_WINAPI STATE_object_get_location1(DWORD object_handle, double xyz[3]);
// Advance the object (move relative)
//
// Parameters:
// space_flag: could be WORLD_SPACE or OBJECT_SPACE or CAMERA_SPACE
// space_flag determines if the step is according to the objects
// coordinate system or the world coordinate system etc ...
// For example if space_flag==OBJECT_SPACE and step==(-1,0,0)
// This means that the object will advance forward (If it is a car than
// forward is the direction of the front window).
// Try both options and see what happens.
//
STATE_IMPORT void STATE_WINAPI STATE_object_move(DWORD object_handle, int space_flag, double x, double y, double z);
// Set the direction towards which the object will point .
//
// Example:
//
// DWORD object=STATE_object_get_first_object();
// //Make the object points towards the positive Y axis (pointing right)
// STATE_object_set_direction(object, 0,1,0);
//
// Remarks:
// Note that STATE_object_set_direction(object, 10,20,30);
// has exactly the same result as STATE_object_set_direction(object, 1,2,3);
//
// For more information about coordination systems and setting directions see the book (download the book free from www.3dstate.com )
//
// See also STATE_object_set_direction1()
//
STATE_IMPORT void STATE_WINAPI STATE_object_set_direction(DWORD object_handle, double x, double y, double z);
// Set the direction towards which the object will point. Exactly the same as the function STATE_object_set_direction()
// only that here we use just 1 parameter.
//
// Example:
//
// double xyz[3]={10,20,30}; //Note that setting 10,20,30 is the same as 1,2,3 (the engine normalizes the vector (make it a unit vector) )
// DWORD object=STATE_object_get_first_object();
// STATE_object_set_direction1(object, xyz);
//
// Remarks:
//
// For more information about coordination systems and setting directions see the book (download the book free from www.3dstate.com )
//
// See also STATE_object_set_direction()
//
STATE_IMPORT void STATE_WINAPI STATE_object_set_direction1(DWORD object_handle, double xyz[3]);
// Returns the direction towards which the object points.
//
//
// Example A:
//
// double x,y,z;
// DWORD object=STATE_object_get_first_object();
// STATE_object_get_direction(object, &x, &y, &z);
//
// Example B:
//
// //Note that instead of doing it as shown below, it is easier to use the function STATE_object_get_direction1() instead
// double xyz[3];
// DWORD object=STATE_object_get_first_object();
// STATE_object_get_direction(object, &xyz[0], &xyz[1], &xyz[2]);
//
//
//
// See also STATE_object_get_direction1()
//
//
// Remarks:
//
// The returned direction is normalized (meaning it is a unit vector)
// For more information about coordination systems and setting directions see the book (download the book free from www.3dstate.com )
//
STATE_IMPORT void STATE_WINAPI STATE_object_get_direction(DWORD object_handle, double *x, double *y, double *z);
// Returns the direction towards which the object points. Exactly the same as the function STATE_object_get_direction()
// only that here we use just 1 parameter.
//
// Example:
//
// double xyz[3];
// DWORD object=STATE_object_get_first_object();
// STATE_object_get_direction1(object, xyz);
//
//
//
// See also STATE_object_get_direction()
//
//
// Remarks:
//
// The returned direction is normalized (meaning it is a unit vector)
// For more information about coordination systems and setting directions see the book (download the book free from www.3dstate.com )
//
STATE_IMPORT void STATE_WINAPI STATE_object_get_direction1(DWORD object_handle, double xyz[3]);
// Rotates the object so that the orientation of the object matches the given directions
// returns OK or VR_ERROR
// One of the useful usage of this function together with STATE_object_get_axis_system() and getset location
// is to save the objact exact position.
// For more explaniton see inside the book "3D programming for windows using STATE"
// One of the given axises could be 0,0,0 in this case this axis is calculated automatically(derived from the other two axises).
// If the given axises are not orthogonal, the function
// handle it by building an orthogonal system that is close as possible
// to the given axis.
//
// Arguments:
//
// double x[3], double y[3], double z[3];
// The X Axis, the Y axis and the Z axis.
// The given axises do not have to be a unit vector. and one of the axises
// could be left for the function to calculate by giving(0,0,0)
//
//
// Here are some examples, note that
// all the examples give the same result.
// Example A:
// x_axis[0]=0; x_axis[1]=1; x_axis[2]=0;
// y_axis[0]=-1; y_axis[1]=0; y_axis[2]=0;
// z_axis[0]=0; z_axis[1]=0; z_axis[2]=1;
// STATE_object_set_axis_system(x_axis, y_axis, z_axis);
//
// Example B:
// //Example B would give exactly the same result as example A
// x_axis[0]=0; x_axis[1]=111; x_axis[2]=0;
// y_axis[0]=-17; y_axis[1]=0; y_axis[2]=0;
// z_axis[0]=0; z_axis[1]=0; z_axis[2]=12;
// STATE_object_set_axis_system(x_axis, y_axis, z_axis);
//
// Example C:
// //Note that z_axis=(0,0,0) and will be automatically
// // calculated by the function
// //Example C would give exactly the same result as example A and B
// x_axis[0]=0; x_axis[1]=111; x_axis[2]=0;
// y_axis[0]=-17; y_axis[1]=0; y_axis[2]=0;
// z_axis[0]=0; z_axis[1]=0; z_axis[2]=0;
// STATE_object_set_axis_system(x_axis, y_axis, z_axis);
//
// Example D:
// // Note that z_axis=(0,0,0) and that the x_axis and the y_axis are not orthogonal to each other.
// //Note that we will get again the same result
// x_axis[0]=0; x_axis[1]=1; x_axis[2]=0;
// y_axis[0]=-1; y_axis[1]=11; y_axis[2]=0;
// z_axis[0]=0; z_axis[1]=0; z_axis[2]=0;
// STATE_object_set_axis_system(x_axis, y_axis, z_axis);
//
// Example E:
// // Note that z_axis=(-1,0,0) which doesn't give a right hand system
// // in this case the z_axis will be ignored and calculated by doing cross between the x_axis and the y_axis
// //Note that we will get again the same result
// x_axis[0]=0; x_axis[1]=1; x_axis[2]=0;
// y_axis[0]=-1; y_axis[1]=0; y_axis[2]=0;
// z_axis[0]=0; z_axis[1]=0; z_axis[2]=-1;
// STATE_object_set_axis_system(x_axis, y_axis, z_axis);
STATE_IMPORT int STATE_WINAPI STATE_object_set_axis_system(DWORD object_handle, double x[3], double y[3], double z[3]);
// One of the useful usage of this function together with STATE_object_set_axis_system() and getset location
// is to save the objact exact position.
//Returns the axis system of the object. For more details please see STATE_object_set_axis_system()
STATE_IMPORT void STATE_WINAPI STATE_object_get_axis_system(DWORD object_handle, double x[3], double y[3], double z[3]);
//Retrieves the X axis of the object. Note the following: x_axis * -1 == the object direction
//For more details see STATE_object_set_axis_system
STATE_IMPORT void STATE_WINAPI STATE_object_get_x_axis(DWORD object_handle, double x_axis[3]);
//Retrieves the Y axis of the object.
//For more details see STATE_object_set_axis_system
STATE_IMPORT void STATE_WINAPI STATE_object_get_y_axis(DWORD object_handle, double y_axis[3]);
//Retrieves the Z axis of the object.
//For more details see STATE_object_set_axis_system
STATE_IMPORT void STATE_WINAPI STATE_object_get_z_axis(DWORD object_handle, double z_axis[3]);
#ifndef WORLD_SPACE
#define WORLD_SPACE 0
#endif
#define OBJECT_SPACE (WORLD_SPACE+1)
// space flag can be OBJECT_SPACE or WORLD_SPACE
STATE_IMPORT void STATE_WINAPI STATE_object_rotate_x(DWORD object_handle, double degrees, int space_flag);
STATE_IMPORT void STATE_WINAPI STATE_object_rotate_y(DWORD object_handle, double degrees, int space_flag);
STATE_IMPORT void STATE_WINAPI STATE_object_rotate_z(DWORD object_handle, double degrees, int space_flag);
// The same just with radians.
// space flag can be OBJECT_SPACE or WORLD_SPACE
STATE_IMPORT void STATE_WINAPI STATE_object_rotate_x_radians(DWORD object_handle, double radians, int space_flag);
STATE_IMPORT void STATE_WINAPI STATE_object_rotate_y_radians(DWORD object_handle, double radians, int space_flag);
STATE_IMPORT void STATE_WINAPI STATE_object_rotate_z_radians(DWORD object_handle, double radians, int space_flag);
// The return value is in [-1 - 1] according to the
// angle between the object direction and the world Z axis
// 1 means we are looking up . -1 means down.
// For example if we have an airplane we can use this function to test
// whether the plane is diving, going up or strait (strait would return 0)
STATE_IMPORT double STATE_WINAPI STATE_object_get_cos_pitch(DWORD object_handle);
// The return value is in [-1 - 1] according to the
// angle between the object Y axis and the world Z axis
// If our object is a plane then this function will return the
// cos() of the angle between the plane wing and the world Z axis
// 0 means the object is strait.
// 1 means one wing is pointing up to the sky and the other wing into the ground.
// -1 means that the other wing is pointing up to the sky and the first wing into the ground.
STATE_IMPORT double STATE_WINAPI STATE_object_get_cos_bank(DWORD object_handle);
// Used to check if the object is heading North
// south east west etc ...
STATE_IMPORT double STATE_WINAPI STATE_object_get_cos_head(DWORD object_handle);
//obsolete. Use STATE_object_get_transformation_matrix() instead.
STATE_IMPORT void STATE_WINAPI STATE_object_get_total_move_mat(DWORD object_handle, double object_matrix[4][4]);
// Who needs this function ?
// --------------------------
// Users that are porting code from other 3D engines might want to use this function.
// All the rest can skip this function
//
// General background
// ------------------
// Please note that the STATE engine never modify the X,Y,Z values of the points of the polygons of a dynamic object.
// When the object is rotated scaled or moved, the engine only modify the object matrix.
// Not modifing all the object points save a lot of time.
//
// What is this matrix ?
// ---------------------
// To learn more about transformation matrixes you should read a computer graphics math book.
// This is just if you are interested in the subject. One of the great things about the STATE engine
// is that it makes it completely unnecessary to learn these subjects.
// Anyhow, since you are still reading it means that you want to know more, so here it is:
// the first top 9 cells of the matrix are the rotation matrix
// The bottom row is the translation values.
// The diagnal is the scale values
//
// S R R 0
// R S R 0
// R R S 0
// T T T 1
//
// Above is the matrix. T stands for translation. S for scale. R for rotation.
// If you don't know what we are talking about then you should read a book in the subject
//
// By taking a point in object space and multiplying it by the matrix we get the point in World Space.
// for example the point (0,0,0) in object space is the center of the object.
// when multiplying (0,0,0) by the matrix we get (T T T) which means that
// (T,T,T) is the object location
// The code below shows how to multiply a point (vec) by the matrix (mat).
// The result is saved in dst.
//
// void mul_vec_mat(vector dst, vector vec, matrix mat) //does dst=vec*mat
// {
// double res[4];
// double one_over_res3;
//
//
// res[0]=vec[0]*mat[0][0] + vec[1]*mat[1][0] + vec[2]*mat[2][0] + mat[3][0];
// res[1]=vec[0]*mat[0][1] + vec[1]*mat[1][1] + vec[2]*mat[2][1] + mat[3][1];
// res[2]=vec[0]*mat[0][2] + vec[1]*mat[1][2] + vec[2]*mat[2][2] + mat[3][2];
// res[3]=vec[0]*mat[0][3] + vec[1]*mat[1][3] + vec[2]*mat[2][3] + mat[3][3];
//
// if(res[3]<1e-20 && res[3]>-1e-20) { //protect agains floating point errors.
// ERROR_MSG(SCREEN,"mul_vec_mat: devision by zeron");
//
// dst[0]=res[0];
// dst[1]=res[1];
// dst[2]=res[2];
// return;
// }
//
// one_over_res3=1/res[3];
//
// dst[0]=res[0]*one_over_res3;
// dst[1]=res[1]*one_over_res3;
// dst[2]=res[2]*one_over_res3;
//
// }
//
// Example:
//
// double matrix[4][4];
// STATE_object_get_transformation_matrix(my_object, matrix);
//
STATE_IMPORT void STATE_WINAPI STATE_object_get_transformation_matrix(DWORD object_handle, double object_matrix[4][4]);
// returns a handle to the an animation that belongs to the object
// If the object has no animations or it has more then one the function
// returns NULL
STATE_IMPORT DWORD STATE_WINAPI STATE_object_get_animation(DWORD object_handle);
// Returns OK or VR_ERROR
// The function search the given object for a polygon that has an animation with the name old_animation_name
// The function then replaces the animation for this specifc polygon.
// This polygon is set with an animation that has the name new_animation_name
// If the given object has more than one polygon with the animation old_animation_name
// then the function will return VR_ERROR
// See also STATE_object_replace_animation()
//
// Arguments:
// object_handle
// The object handle.
// old_animation_name
// The name of the animation to be replaced.
// new_animation_name
// The name of the animation to to be set instead of old_animation_name.
//
STATE_IMPORT int STATE_WINAPI STATE_object_replace_animation_using_names(DWORD object_handle, char *old_animation_name ,char *new_animation_name);
// Returns OK or VR_ERROR
// Exactly like STATE_object_replace_animation_using_names() only that instead of getting the names of the animation
// it receives the handles (faster)
// For more details see STATE_object_replace_animation_using_names()
// Arguments:
// object_handle
// The object handle.
// old_animation_handle
// The handle to the animation to be replaced.
// new_animation_handle
// The handle to the animation to to be set instead of old_animation_name.
//
//
STATE_IMPORT int STATE_WINAPI STATE_object_replace_animation(DWORD object_handle, DWORD old_animation_handle ,DWORD new_animation_handle);
//Converts a point in object space to a point in world space.
// Returns OK or VR_ERROR if failed
//Here are some examples:
// The location of the object (world space) will always translate to (0,0,0) in object space
// (-1,0,0) in object space is one unit in front of the object this is equal to
// the object location plus the object direction (a unit vector) in object space.
// (1,0,0) in object space is one unit in the back of the object
// (0,1,0) in object space is always one unit to the right of the object.
// (0,-1,0) in object space is always one unit to the left of the object.
// (0,0,1) in object space is always one unit up above the object.
//See also STATE_object_convert_point_to_object_space()
STATE_IMPORT int STATE_WINAPI STATE_object_convert_point_to_world_space(DWORD object_handle, double object_space_point[3], double result[3]);
//Converts a point in world space to a point in object space.
// Returns OK or VR_ERROR if failed
//Here are some examples:
// The point (0,0,0) in object space will always translate to the location of the object in world space
// (-1,0,0) in object space is one unit in front of the object this is equal to
// the object location plus the object direction (a unit vector) in object space.
// (1,0,0) in object space is one unit in the back of the object
// (0,1,0) in object space is always one unit to the right of the object.
// (0,-1,0) in object space is always one unit to the left of the object.
// (0,0,1) in object space is always one unit up above the object.
//See also STATE_object_convert_point_to_world_space()
STATE_IMPORT int STATE_WINAPI STATE_object_convert_point_to_object_space(DWORD object_handle, double world_space_point[3], double result[3]);
// **************************
// returns VR_ERROR, OK
// if track_handle ==NULL it doesn't cancel the chase type so
// for canceling chasing use STATE_object_set_chase_type(NO_CHASE);
// Automatically set the closest point on the track (closest to the object)
// as the next point to go towards
// (to override this setting use STATE_object_set_next_point_on_track() )
STATE_IMPORT int STATE_WINAPI STATE_object_set_track(DWORD object_handle, DWORD track_handle);
// return OK or VR_ERROR
// the offset is return through argument "offset"
STATE_IMPORT int STATE_WINAPI STATE_object_get_track_offset(DWORD object_handle, double offset[3]);
// return OK or VR_ERROR
STATE_IMPORT int STATE_WINAPI STATE_object_set_track_offset(DWORD object_handle, double offset[3]);
// returns an index to a point on the track. This point is the point that the object is moving towards
// The exact cords of the point can be retrieved through STATE_track_get_point()
// 0 is the first point and number_of_points-1 is the last index (use STATE_track_get_number_of_points() to get this number
STATE_IMPORT int STATE_WINAPI STATE_object_get_next_point_on_track(DWORD object_handle);
// returns the point on the track that the object is moving towards
// 0 is the first point and number_of_points-1 is the last index (use STATE_track_get_number_of_points() to get this number
// if point_index<0 then it set it to 0
// if point_index is bigger than the maximum index then it is set to the maximum allowed. In those cases it returns VR_ERROR
// to notify the change from the given value.
// If there is no track associated with the object it returns VR_ERROR without setting the value
STATE_IMPORT int STATE_WINAPI STATE_object_set_next_point_on_track(DWORD object_handle, int point_index);
// Set the object to chase after
// the given argument should NOT be NULL
// Note that if the object was previously chasing a camera or a group
// , those chasing operation are canceled. (The object can chase only one thing at a time).
STATE_IMPORT void STATE_WINAPI STATE_object_set_object_to_chase(DWORD object_handle, DWORD object_to_chase_handle);
// If the return value is NULL it means no object is being chased
STATE_IMPORT DWORD STATE_WINAPI STATE_object_get_chased_object(DWORD object_handle);
// Set the camera to chase after
// the given argument should NOT be NULL
// Note that if the object was previously chasing another object or a group
// , those chasing operation are canceled. (The object can chase only one thing at a time).
STATE_IMPORT void STATE_WINAPI STATE_object_set_camera_to_chase(DWORD object_handle, DWORD camera_to_chase_handle);
// If the return value is NULL it means no camera is being chased
STATE_IMPORT DWORD STATE_WINAPI STATE_object_get_chased_camera(DWORD object_handle);
// Set the group to chase after
// the given argument should NOT be NULL
// Note that if the object was previously chasing a camera or an object
// , those chasing operation are canceled. (The object can chase only one thing at a time).
STATE_IMPORT void STATE_WINAPI STATE_object_set_group_to_chase(DWORD object_handle, DWORD group_to_chase_handle);
// If the return value is NULL it means no group is being chased
STATE_IMPORT DWORD STATE_WINAPI STATE_object_get_chased_group(DWORD object_handle);
// return OK or VR_ERROR
// the offset is return through argument "offset"
STATE_IMPORT int STATE_WINAPI STATE_object_get_chase_offset(DWORD object_handle, double offset[3]);
// return OK or VR_ERROR
STATE_IMPORT int STATE_WINAPI STATE_object_set_chase_offset(DWORD object_handle, double offset[3]);
// The returned number is between 0 and one
// a number close to 0 means that the tracking is weak
// 1 means that the tracking is very sharp.
STATE_IMPORT double STATE_WINAPI STATE_object_get_chase_softness(DWORD object_handle);
// The returned number is between 0 and one
// a number close to 0 means that the tracking is weak
// 1 means that the tracking is very sharp.
// it the given number is bigger than one it is set as one
// if it is smaller than 0 than it set as 0
STATE_IMPORT void STATE_WINAPI STATE_object_set_chase_softness(DWORD object_handle, double softness);
// look in the header file for possible values and their meanings
// (look for NO_CHASE, CHASE_LOCATION and others ...)
STATE_IMPORT int STATE_WINAPI STATE_object_get_chase_type(DWORD object_handle);
// look at the top of the header file for possible values and their meanings
// (look for NO_CHASE, CHASE_LOCATION and others ...)
STATE_IMPORT void STATE_WINAPI STATE_object_set_chase_type(DWORD object_handle, int chase_type);
/*
Function for automatic falling from a track.
--------------------------------------------
Example of usage:
Say we have a track for a runner on a road, if the track is not 100 percent precise
meaning that some time the runner will be in the air and some times inside the ground.
With these functions we can solve that problem.
We give an offset for the track in the Z axis
so the track will be above the road. Now if "falling"
is ON, the object will fall down till it reaches the
the track.
Another example:
If we want to move the object on a terrain model
very close to the ground. It will be very difficult to
calculate the exact track. Now we can define a very simple
track like a basic square and "falling" will do the rest.