射击游戏

开发平台：

Visual C++

3DSTATE.H：源码内容

//
// }
STATE_IMPORT DWORD STATE_WINAPI STATE_polygon_get_first_patch(DWORD polygon_handle);
//Returns the next patch. patch_polygon_handle could also be a regular polygon
//that is not a patch, in this case the function will return the first patch
//which is attached to this polygon or NULL if there aren't any patches attached.
//
//Example:
// //Here is how to go through all the patches of a given polygon
// for(DWORD poly=STATE_polygon_get_first_patch(polygon_handle); poly!=NULL; poly=STATE_polygon_get_next_patch(poly) )
// {
// //do some processing for each patch
// }
STATE_IMPORT DWORD STATE_WINAPI STATE_polygon_get_next_patch(DWORD patch_polygon_handle);
//Returns the polygon to which the given patch was added.
//if patch_polygon_handle is not a patch (a regular polygon) then the function returns NULL
STATE_IMPORT DWORD STATE_WINAPI STATE_polygon_get_patch_father(DWORD patch_polygon_handle);
// Function level of importance = Medium.
//
// The function turns OFF or ON the bilinear filtering for the given polygon
// The effect is visible only when the 3D card is on.
// Bilinear filtering is a technique for getting better looking textures. When bilinear
// filtering is ON, it removes the pixelization effect from close textures.
// By default the bilinear mode for all polygons is set according to the 3D card settings
// Using this function one can overide the default settings for specific polygons.
// Here are some reasons why one might consider turning off bilinear filtering for specific polygons
// - Some 3D card add a counter line around transparent textures when bilinera is used
// - Give the polygon a different look.
// - When bilinear filtering is turned off, rendering is slightly faster.
//
// To change the default bilinear setting for all the polygons use:
// STATE_3D_card_set_bilinear_filtering()
// parameters:
// bilinear_mode:
// ON - The default. Turns on bilinear filtering.
// OFF - Turns off bilinear filtering
// BILINEAR_FOR_PRIMARY_TEXTURE_ONLY - Turns bilinear only for the primary texture (each polygon could have two textures, the primary and the secondary)
// BILINEAR_FOR_PRIMARY_SECONDARY_ONLY - Turns bilinear only for the secondary texture (each polygon could have two textures, the primary and the secondary)
// BILINEAR_USE_3D_CARD_DEFAULTS - Use the setting as defined by STATE_3D_card_set_bilinear_filtering. This is the default option.
//Example:
// STATE_3D_card_set_bilinear_filtering(OFF);
//
// See also STATE_3D_card_set_bilinear_filtering()
STATE_IMPORT void STATE_WINAPI STATE_polygon_set_bilinear_filtering(DWORD polygon_handle, int bilinear_mode);
//----------------------------------------------------//
//=========== T H E P O I N T A P I =============//
//----------------------------------------------------//
// About this API:
// Every polygon is built from points. This API deals with those points.
// Returns YES or NO.
// YES , if the given handle is a point handle. NO if not.
// If it is not a point 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_POINT()
STATE_IMPORT int STATE_WINAPI STATE_point_is_point(DWORD point_handle, char *function_asking);
// Returns the next point
// use STATE_polygon_get_first_point() to get the first point
//
//Example:
//
// //Go over all the points of a polygon
// for(DWORD point=STATE_polygon_get_first_point(polygon_handle); point!=NULL ; point=STATE_point_get_next_point(point) )
// {
//
//
// }
//
STATE_IMPORT DWORD STATE_WINAPI STATE_point_get_next_point(DWORD point_handle);
// Gets the point (x,y,z) coordinate.
//Please note that if the point belongs to a dynamic object then the returned (x,y,z) will be in OBJECT_SPACE.
// To get the point in WORLD_SPACE you should write the following code:
//
// double xyz[3];
// STATE_point_get_xyz(my_point, xyz);
// double xyz_world_space[3]
// STATE_object_convert_point_to_world_space(my_object, xyz, xyz_world_space);
STATE_IMPORT void STATE_WINAPI STATE_point_get_xyz(DWORD point_handle, double xyz[3]);
// Sets the point (x,y,z) coordinate.
// After changing the points of a polygon dont forget to call STATE_polygon_is_valid()
// This call is needed for recalculating internal data of the polygon (such as the polygon's normal)
//
// Example:
//
// double xyz[3]={100,200,300};
// STATE_point_set_xyz(my_point, xyz);
// STATE_polygon_is_valid(); //Update the polygon data (call this function after you have finished manipulating the polygon's point
//
//
// Please note that if the point belongs to a dynamic object then the (x,y,z) should be in OBJECT_SPACE.
// To get a x,y,z coorinate in OBJECT_SPACE you should write the following code:
//
// double xyz[3];
// xyz[0]=100; xyz[1]=200; xyz[2]=300; //setting the coordinate (world space)
// double xyz_object_space[3]
// STATE_object_convert_point_to_object_space(my_object, xyz, xyz_object_space);
// STATE_point_set_xyz(my_point, xyz);
// STATE_polygon_is_valid(); //Update the polygon data (call this function after you have finished manipulating the polygon's point)
//
STATE_IMPORT void STATE_WINAPI STATE_point_set_xyz(DWORD point_handle, double xyz[3]);
#define FIND_COORDINATE_AUTOMATICALLY -1
//Set the bitmap coordinates of the given points.
//Examples:
// A) //Attach the polygon's bitmap top left corner to the given point.
// double xy[2]={0,0}
// STATE_point_set_bitmap_xy(pnt1,owner_polygon_handle, xy);
//
// B) //Attach the polygon's bitmap bottom right corner to the given point.
// double xy[2]={1,1}
// STATE_point_set_bitmap_xy(pnt1,owner_polygon_handle, xy);
//
// C) //This tells the engine to figure out on his own to witch part of the bitmap
// //this point should be attached. This is very useful since sometimes the right bitmap coord
// //could look like 0.5543222323 etc... For example if our polygon has a trapez shape or a pentagon shape
// //Please note that in order for the engine to figure out on his own it must previously give it
// //Three other coords. The actual calculation of all the missing coordinates is done when
// //We call STATE_engine_add_polygon()
// double xy[2]={FIND_COORDINATE_AUTOMATICALLY, FIND_COORDINATE_AUTOMATICALLY}
// STATE_point_set_bitmap_xy(pnt1,owner_polygon_handle, xy);
// D) // Like "C" only that one coordinate element we give and one we ask the engine to find.
// // In this example we ask to find the y bitmap coordinate. In order for the engine to find it on its own
// // We must give him befroehand three other y values.
// double xy[2]={0, FIND_COORDINATE_AUTOMATICALLY}
// STATE_point_set_bitmap_xy(pnt1,owner_polygon_handle, xy);
//
// E) How to tile a bitmap over a polygon. Lets say we have
// a square polygon and we want to tile a bitmap .In this example it will be tiled 5x5 .
//
// double xy[2]={0, 0}
// STATE_point_get_bitmap_xy(pnt1, xy); //The top left
// xy[0]=5;
// STATE_point_set_bitmap_xy(pnt2,owner_polygon_handle, xy); //The top right
// xy[1]=5;
// STATE_point_set_bitmap_xy(pnt3,owner_polygon_handle, xy); //The bottom right. xy==[5,5]
// xy[0]=FIND_COORDINATE_AUTOMATICALLY;
// xy[1]=FIND_COORDINATE_AUTOMATICALLY;
// STATE_point_set_bitmap_xy(pnt4,owner_polygon_handle, xy); //We have already three points so the engine
// //can figure out the rest on its own. In this case
// //If our polygon is a square it should calculate xy={0,5}
// //It is better to let the engine handle the forth point and above
// //to avoid mistakes.
STATE_IMPORT void STATE_WINAPI STATE_point_set_bitmap_xy(DWORD point_handle, DWORD owner_polygon_handle ,double xy[2]);
STATE_IMPORT void STATE_WINAPI STATE_point_get_bitmap_xy(DWORD point_handle, double xy[2]);
//The same as STATE_point_set_bitmap_xy() just for the second bitmap.
//See also STATE_polygon_set_second_bitmap()
STATE_IMPORT void STATE_WINAPI STATE_point_set_second_bitmap_xy(DWORD point_handle, DWORD owner_polygon_handle ,double xy[2]);
STATE_IMPORT void STATE_WINAPI STATE_point_get_second_bitmap_xy(DWORD point_handle, double xy[2]);
// This function will return the rgb values of the point
// Red will be returned in rgb[0]
// Green will be returned in rgb[1]
// Blue will be returned in rgb[2]
// Note that these values are only relevant with hardware rendering.
// The default is (255,255,255).
// By changing the rgb value we can create light and atmospheric effects.
//
// How the rgb values are combined with the texture color and the polygon color
// to form the final color of each pixel:
// ----------------------------------------------------------------------------
// The final color of a pixel in a polygon is
// an outcome of the rgb values of the vertexes and the polygon texture or color
// The rgb of the vertexes is interpolated for every pixel of the polygon
// The interpolated value is multiplied by the texture color of every pixel.
// (If there is no texture then it is multiplied by the color of the polygon)
// Before multiplying the rgb is converted to a 0 till 1 scale.
// Example: Lets say we have a red polygon with its color set to (240,10,10)
// Lets assume that this is a triangle and that the rgb value of the vertexes is
// (255,0,0 ) , (0,255,0) , (0,0,255). If we take a point in the center of the polygon
// then the interpolated value from the three vertexes will be something like (83,83,83)
// when 83 is converted from 0-255 scale to 0-1 scale we get that the interpolated value
// is (0.33, 0.33, 0.33). Now let multiply this value with the color of the polygon
// we get: (0.33, 0.33, 0.33) * (240, 10, 10) == (80, 3, 3)
// The result pixel will be (80,3,3)
//
// Special cases.
// --------------
// 1) If the RGB value of all the vertexes is (255,255,255)
// Then it wont have any effect since in scale of [0-1]
// it will become (1,1,1) and then the multiplication wont change
// the value of the pixel
// 2) If the polygon has no bitmap and its color is white (255,255,255)
// In this case the rgb values of the vertexes determine alone the color
// of the final pixel. This is also known as Gouraud shading
//
STATE_IMPORT void STATE_WINAPI STATE_point_get_rgb(DWORD point_handle, BYTE rgb[3]);
// This function will set the rgb values of the point
// Red should be given in rgb[0]
// Green should be given in rgb[1]
// Blue should be given in rgb[2]
// Note that these values are only relevant with hardware rendering.
// By changing the rgb value we can create light and atmospheric effects.
// The light API is based on this function. Usually one would
// use the light API function though sometimes it nice to have the direct control
// for creating special effects.
//
// How the rgb values are combined with the texture color and the polygon color
// to form the final color of each pixel:
// ----------------------------------------------------------------------------
// The final color of a pixel in a polygon is
// an outcome of the rgb values of the vertexes and the polygon texture or color
// The rgb of the vertexes is interpolated for every pixel of the polygon
// The interpolated value is multiplied by the texture color of every pixel.
// (If there is no texture then it is multiplied by the color of the polygon)
// Before multiplying the rgb is converted to a 0 till 1 scale.
// Example: Lets say we have a red polygon with its color set to (240,10,10)
// Lets assume that this is a triangle and that the rgb value of the vertexes is
// (255,0,0 ) , (0,255,0) , (0,0,255). If we take a point in the center of the polygon
// then the interpolated value from the three vertexes will be something like (83,83,83)
// when 83 is converted from 0-255 scale to 0-1 scale we get that the interpolated value
// is (0.33, 0.33, 0.33). Now let multiply this value with the color of the polygon
// we get: (0.33, 0.33, 0.33) * (240, 10, 10) == (80, 3, 3)
// The result pixel will be (80,3,3)
//
// Special cases.
// --------------
// 1) If the RGB value of all the vertexes is (255,255,255)
// Then it wont have any effect since in scale of [0-1]
// it will become (1,1,1) and then the multiplication wont change
// the value of the pixel
// 2) If the polygon has a bitmap and its color is white (255,255,255)
// In this case the rgb values of the vertexes determine alone the color
// of the final pixel. This is also known as Gouraud shading
//
// See also STATE_polygon_set_light()
STATE_IMPORT void STATE_WINAPI STATE_point_set_rgb(DWORD point_handle, DWORD father_polygon, BYTE rgb[3]);
// relevant only for bitmap fill
// 100 means the same brightness as the original bitmap
// 200 means twice as bright as the original bitmap
// 50 is half bright as the original
// see also:
// STATE_polygon_get_brightness()
// STATE_polygon_set_brightness()
// STATE_polygon_is_uniform_brightness()
// STATE_point_get_brightness()
STATE_IMPORT double STATE_WINAPI STATE_point_get_brightness(DWORD point_handle);
// note that if not all the points have the same brightness value
// the rendering of this polygon will be slower.
// relevant only for bitmap fill
// 100 means the same brightness as the original bitmap
// 200 means twice as bright as the original bitmap
// 50 is half bright as the original
// see also:
// STATE_polygon_get_brightness()
// STATE_polygon_set_brightness()
// STATE_polygon_is_uniform_brightness()
// STATE_point_get_brightness()
STATE_IMPORT void STATE_WINAPI STATE_point_set_brightness(DWORD point_handle, double value);
//The point's normal is relevant only when using light (through the STATE_light_ API)
//The following are three cases where you might want to modify the points normal
// 1) If it is needed to sharpen the contact lines of polygons (see example below)
// in order to get better illumination of objects such as rooms boxes etc.
// 2) If one is writing his own lighting module
// 3) If one is writing a file format converter (from or to STATE).
//
//The normal of a point is set internally to the average of the normals of the adjacent surfaces.
//For example, if we have model of a room (a cube) the normal of a point on the floor
//will point to the center of the cube this is because the coordinates of a point on the floor
//exists in three polygons. The floor polygon and two adjacent walls.
//The average of the normals of these three polygons is a normal that points to the center of the cube.
//Please note that inside the engine a cube is built from 6 polygons each contains
//4 points, so a cube is built from 24 points (and NOT 8).
//Because of the fact that the normal of each point is the average of the adjacent
//it results that points that have the same coordinates will have the same adjacent polygons
//and therefore the same point normal. In other words point that have the same X,Y,Z coordinates
//will also have the same normal.
//
//Why do we need points to have a normal ? What is it good for.
//-------------------------------------------------------------
//The point normal helps a lot in making polygonal shapes to look more rounded
//while lighting the model polygons. Since points with the same X,Y,Z coordinates but on
//different polygons have the same point normal , they will also get the same color
//while the object is lighted and this will hide the connecting line between
//any two polygons.
//
//
//When saving a world on the disk (using STATE_engine_save() or WorldBuilder()
//The engine automatically calculates the polygons normal. This means that if you
//use STATE_point_set_normal() to modify the normals you will then loose
//your changes when the world is saved. To keep your changes
//call STATE_engine_save() with the flag: SAVE_WITHOUT_CALCULATING_POINT_NORMALS
//
// Parameters:
//
// point_handle: a handle to a point.
//
// normal: a three values in the range of [-1 - 1] that corresponds with the
// X,Y,Z values to be set (normal[0] is the X value)
// Note that the normal is normalized internally so values such as Normal= {10,0, -20}
// can also be used to set a normal
//
// Note that internally the engine uses only 24 bits for the normal X,Y,Z values
// (for example, three double values would occupied 8*8*3=192 bits)
// This means that if one calls STATE_point_set_normal() with a normal_x == 0.123456789
// then internally it will be rounded to something like 0.123
//
// Return Value: OK or VR_ERROR.
//
// Example:
//
// A) double normal[3]={1,0,0};
// STATE_point_set_normal(point_handle, normal);
//
// B)
// The following example will set all the points normal to the same value
// of their respective polygon. This will make the edges of the polygon much sharper
// This effect is good for lighting a room were there should be a visible difference
// between the light that the floor and the wall receive.
//
// for(DWORD poly=STATE_polygon_get_first_polygon(); poly!=NULL; poly=STATE_polygon_get_next(poly) ) {
// double normal[4]; //The normal is the three first values
// STATE_polygon_get_plane(poly, normal);
// for(DWORD point=STATE_polygon_get_first_point(poly); point!=NULL ; point=STATE_point_get_next_point(point) ) {
// STATE_point_set_normal(point, normal);
// }
//
// }
//
// See also STATE_point_get_normal()
STATE_IMPORT int STATE_WINAPI STATE_point_set_normal(DWORD point_handle, double normal[3]);
// For more information see STATE_point_set_normal()
//
// Return Value: OK or VR_ERROR.
//
// Example:
//
// double normal[3];
// STATE_point_get_normal(point_handle, normal);
STATE_IMPORT int STATE_WINAPI STATE_point_get_normal(DWORD point_handle, double normal[3]);
//-----------------------------------------------------//
//======== T H E G R O U P A P I =================//
//-----------------------------------------------------//
// This API is used in editor mode to manipulate groups of polygons
// See also the OBJECT API for manipulating things in viewer_mode mode.
// With this API you can group polygons together.
// Example,
// say we have a room with three tables inside. Each table has four legs
// and each leg has 6 polygons. We will probably like to build it like that:
// Group "leg" contains the six polygons
// group "table" which will include the four "leg" groups and the table top polygons
// group "room" which will include the three tables and the walls polygons
// A general note for most of the functions in this API:
// After a new group is created, polygons can be associated with this group
// by calling STATE_polygon_set_group()
// IMPORTANT: if the polygons that are associated with the group are not part of the
// world (after creating a new polygon, we can add it to the world by calling STATE_engine_add_polygon() )
// most of the function in the group API wont work for those polygons.
// Returns YES or NO.
// YES , if the given handle is a group handle. NO if not.
// If it is not a group 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_GROUP()
// NOTE, unlike all the other IS_xxx function this function consider a NULL
// as a legal handle, since a NULL group means the whole world.
STATE_IMPORT int STATE_WINAPI STATE_group_is_group(DWORD group_handle, char *function_asking);
// returns a handle of the newly created group
// After a new group is created, polygons can be associated with this group
// by calling STATE_polygon_set_group()
// IMPORTANT: if the polygons that are associated with the group are not part of the
// world (after creating a new polygon, we can add it to the world by calling STATE_engine_add_polygon() )
// most of the function in the group API wont work for those polygons.
STATE_IMPORT DWORD STATE_WINAPI STATE_group_create(char *name);
// Just runs on the list of all the existing groups
STATE_IMPORT DWORD STATE_WINAPI STATE_group_get_first_group(void);
STATE_IMPORT DWORD STATE_WINAPI STATE_group_get_next(DWORD group_handle);
STATE_IMPORT DWORD STATE_WINAPI STATE_group_get_using_name(char *name);
STATE_IMPORT DWORD STATE_WINAPI STATE_group_get_first_polygon(DWORD group_handle);
STATE_IMPORT DWORD STATE_WINAPI STATE_group_get_next_polygon(DWORD group_handle, DWORD polygon_handle);
STATE_IMPORT DWORD STATE_WINAPI STATE_group_get_father_group(DWORD group_handle);
// We can call this function with father_group==NULL
// This will mean that this group is at the top of the hierarchy and it doesnt belong to any other group.
// If the function fails it is most likly that we tried to make a loop in hierarchy of the groups
// (for example, groupA father is groupB. groupB father is groupC, and groupC father is groupA ...)
// Returns OK or VR_ERROR.
//
// Example:
// STATE_group_set_father_group(leg_of_a_chair_group, chair_group);
STATE_IMPORT int STATE_WINAPI STATE_group_set_father_group(DWORD group_handle, DWORD father_group);
// Returns whether groupA is included in groupB.
// A NULL group_handle means the whole world
// Return value: Returns YES or NO.
//
// Note the following examples:
// 1) If groupA_handle==groupB_handle returns YES
// 2) If groupB_handle==NULL returns YES
//
// Parameters:
// groupA_handle, groupB_handle: checks wheter groupA belongs to groupB
//
// See also STATE_group_is_groupA_included_in_enabled_parts_of_groupB();
// Version note:
// In version 5.0 and before STATE_group_is_groupA_included_in_groupB() was identical to
// STATE_group_is_groupA_included_in_enabled_parts_of_groupB(). In other words, in old version
// there was only one function which behaved exactly as STATE_group_is_groupA_included_in_enabled_parts_of_groupB()
//
STATE_IMPORT int STATE_WINAPI STATE_group_is_groupA_included_in_groupB(DWORD groupA_handle, DWORD groupB_handle);
// Checks whether one group belongs to enabled parts of another group.
// (disabled parts are subgroups that are disabled. See STATE_group_disable() )
// A NULL group_handle means the whole world
// Return value: Returns YES or NO.
// Note the following examples:
// 1) If groupA_handle==groupB_handle returns YES
// 2) If groupB_handle==NULL it will return YES only if groupA does not belong to a disabled group.
// 3) If groupA belongs to a disabled group that belongs to groupB then returns NO
//
// Parameters:
// groupA_handle, groupB_handle: checks wheter groupA belongs to groupB
//
// Example:
// //check if a polygon belongs to a disabled group
// DWORD my_group=STATE_polygon_get_group(my_polygon)
// if(STATE_group_is_groupA_included_in_enabled_parts_of_groupB( my_group, NULL)==NO) {
// //my_group belongs to a disabled group !!!
// }
//
// See also STATE_group_is_groupA_included_in_groupB()
//
// Version note:
// In version 5.0 and before STATE_group_is_groupA_included_in_groupB() was identical to
// STATE_group_is_groupA_included_in_enabled_parts_of_groupB(). In other words, in old version
// there was only one function which behaved exactly as STATE_group_is_groupA_included_in_enabled_parts_of_groupB()
//
STATE_IMPORT int STATE_WINAPI STATE_group_is_groupA_included_in_enabled_parts_of_groupB(DWORD groupA_handle, DWORD groupB_handle);
// Returns the name of the group.
// 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_group_get_name(DWORD group_handle);
// A NULL group_handle will get the rotation reference point of the whole world
// This is the point that all the rotations will use as the center of rotation
STATE_IMPORT void STATE_WINAPI STATE_group_get_rotate_reference_point(DWORD group_handle, double center[3]);
// A NULL group_handle will get the rotation reference point of the whole world
// This is the point that all the rotations will use as the center of rotation
// see also STATE_object_set_rotation_center()
STATE_IMPORT void STATE_WINAPI STATE_group_set_rotate_reference_point(DWORD group_handle, double center[3]);
// A NULL group_handle will get the center of mass of all the world
// The operations set_location and move are done according to the center of mass
// This function calls STATE_group_get_bounding_box() and then
// calculates the center of the box.
STATE_IMPORT void STATE_WINAPI STATE_group_get_center_of_mass(DWORD group_handle, double center[3]);
// box[0][0] is the minimum X
// box[0][1] is the minimum Y
// box[0][2] is the minimum Z
// box[1][0] is the max X
// box[1][1] is the max Y
// box[1][2] is the max Z
// This function is not very speedy
// Unlike most of the get function which just return a value
// this function makes all the calculation going over all the vertexes
// in the group.
STATE_IMPORT void STATE_WINAPI STATE_group_get_bounding_box(DWORD group_handle, double box[2][3]);
STATE_IMPORT void STATE_WINAPI STATE_group_set_name(DWORD group_handle, char *name);
// A NULL group_handle means the whole world
//
// Reamarks:
// Polygons
STATE_IMPORT int STATE_WINAPI STATE_group_get_number_of_polygons(DWORD group_handle);
// Rotates a group around its rotation center.
// To set the rotation center call: STATE_group_set_rotate_reference_point()
// Groups that include a rotated polygon (See STATE_polygon_is_rotated ) cannot
// be rotated using this function (You can call this function but it will have no effect)
//
// Parameters:
// group_handle:
// A NULL group_handle means the whole world
//
// degrees: In how many degrees to rotate the group.
//
// space_flag: CAMERA_SPACE, OBJECT_SPACE, WORLD_SPACE
// axis_flag: 0 for the X axis. 1 for the Y axis. 2 for the Z axis
//
// see also STATE_group_is_rotation_enabled()
// STATE_group_set_rotate_reference_point()
// STATE_group_get_center_of_mass()
STATE_IMPORT void STATE_WINAPI STATE_group_rotate(DWORD group_handle, double degrees, int space_flag, int axis_flag);
// A NULL group_handle means the whole world
STATE_IMPORT void STATE_WINAPI STATE_group_rotate_using_matrix(DWORD group_handle, double rotate_matrix[3][3]);
STATE_IMPORT void STATE_WINAPI STATE_group_transform_using_matrix4x4(DWORD group_handle, double trans_matrix[4][4]);
// A NULL group_handle means the whole world
// moves the center of mass of the group to the given location
// Note that there is no STATE_group_get_location(), instead use
// STATE_group_get_center_of_mass().
STATE_IMPORT void STATE_WINAPI STATE_group_set_location(DWORD group_handle, double location[3]);
// ZZZ
// I am about to cancel this function since it is the same as
// STATE_group_get_center_of_mass().
// mean while I leave it just so I can link to the executable
STATE_IMPORT void STATE_WINAPI STATE_group_get_location(DWORD group_handle, double *X, double *Y, double *Z);
// A NULL group_handle means the whole world
// moves all the vertex belonging to the group. The result is that the
// center of mass also moves with the given step
// space flag could be: CAMERA_SPACE, OBJECT_SPACE, WORLD_SPACE
// Note that this function does not update the rotation center of the group
// This means that if you use STATE_group_rotate() after moving the group
// the rotation center will stay as before. See also STATE_group_set_rotate_reference_point()
// STATE_group_get_rotate_reference_point()
STATE_IMPORT void STATE_WINAPI STATE_group_move(DWORD group_handle, double step[3], int space_flag);
// A NULL group_handle means the whole world
// space flag could be: CAMERA_SPACE, OBJECT_SPACE, WORLD_SPACE
STATE_IMPORT void STATE_WINAPI STATE_group_scale(DWORD group_handle, int space_flag,double scale_x, double scale_y, double scale_z);
//Get the width, height and depth of the group. Please note that
//The dimensions will be returned inside the parameter "dimension"
// dimension[0] will become the depth
// dimension[1] will be the width
//dimension[2] will be the height
//the dimensions are according to the bottom and the front of the group.
//To declarea polygon as being the bottom of the group see those function
// STATE_polygon_set_orientation()
//Returns OK or VR_ERROR;
//Example:
// double size[3];
// STATE_group_get_dimensions(my_group, size);
STATE_IMPORT int STATE_WINAPI STATE_group_get_dimensions(DWORD group_handle, double dimensions[3]);
// deletes the group but not the polygon included
// group handle cannot be NULL
// Make sure you dont use the handle after it was ungrouped.
// Example:
// //The example shows how to go over all the polygons that belong to several group
// //Note that if we would go over all the polygons of the first group
// //and then over all the polygons of the second group we might go over some polygon
// //twice since it could be for example that groupA belongs to groupB
// //and therefore by going over all the polygons of groupB will also go
// //over all the polygons of groupA. The code below show how to do it right so we
// //go over each polygon only once. We do it by grouping several objects together and then ungroup them back
//
// DWORD top_group=STATE_group_creare("Top group");
// STATE_group_set_father_group(grpA, top_group);
// STATE_group_set_father_group(grpB, top_group);
// STATE_group_set_father_group(grpC, top_group);
// for( DWORD poly=STATE_group_get_first_polygon(top_group); poly!=NULL; poly=STATE_group_get_next_polygon(poly) ) {
//
// // Your code here ....
// }
//
// STATE_group_ungroup(top_group); // We can now delete the top group if we want to.
// my_group=NULL; //For safty since we cant use it anymore.
STATE_IMPORT void STATE_WINAPI STATE_group_ungroup(DWORD group_handle);
// deletes all the polygons that belong to this group
// and all the groups that belong to this group
// return the number of polygons that were deleted
// A NULL group_handle will delete the whole world.
STATE_IMPORT int STATE_WINAPI STATE_group_delete_members(DWORD group_handle);
// Returns YES or NO.
// The static/dynamic properties are relevant when we load the world
// in viewer mode. Only objects that are declared dynamic (not static) in
// editor mode will be able to move (using the object API)
// see also STATE_group_set_static(), STATE_group_set_dynamic()
STATE_IMPORT int STATE_WINAPI STATE_group_is_static(DWORD group_handle);
// The static/dynamic properties are relevant when we will load the world
// in viewer mode. Only objects that are declared dynamic (not static) in
// editor mode will be able to move (using the object API)
// see also STATE_group_is_static(), STATE_group_set_dynamic()
STATE_IMPORT void STATE_WINAPI STATE_group_set_static(DWORD group_handle);
// The static/dynamic properties are relevant when we will load the world
// in viewer mode. Only objects that are declared dynamic (not static) in
// editor mode will be able to move (using the object API)
// see also STATE_group_set_static(), STATE_group_is_static()
STATE_IMPORT void STATE_WINAPI STATE_group_set_dynamic(DWORD group_handle);
//Usually when we build a world (using STATE World Builder for example)
//we have many models which we want them to be disabled when the world
//is loaded (in viewer mode) . For example, we could have few models of a bird that
//are interchanged to form a 3D animation. If the movement is composed of
// 3 models, then two of them will always be disabled, and one will be enabled.
// Using this function you can decide who is going to be loaded as disabled and
// who as an enabled object.
//Note that this function is only relevant to groups that were set as dynamic
//( using STATE_group_set_dynamic() ).
// The default is NO
// See also STATE_object_disable()
STATE_IMPORT void STATE_WINAPI STATE_group_load_as_disabled(DWORD group_handle, int YES_or_NO);
//Returns YES or NO.
//See also STATE_group_load_as_disabled(), STATE_object_disable();
STATE_IMPORT int STATE_WINAPI STATE_group_get_load_as_disabled_status(DWORD group_handle);
// returns a handle to the new group
STATE_IMPORT DWORD STATE_WINAPI STATE_group_duplicate_tree(DWORD group_handle);
// The function get three arguments.
// group_handle: the group to rotate
// polygon_in_the_group: a polygon that belongs to the group
// reference_polygon: any polygon.
// inverse_flag: YES or NO. If YES the Normal of the reference polygon is inversed (as if we took the back side of the reference polygon)
// The function rotates the group so that "polygon_in_the_group" will
// be parallel to "reference_polygon"
// returns OK, VR_ERROR.
// A NULL group handle means the whole world
// Note this very nice trick:
// If the reference polygon also belongs to the group we can call
// this function several times consecutively.
// example say we have a box and we call this function as follows:
// STATE_group_rotate_to_match_polygon(grp, left_poly, front_poly);
// after the first call the box will rotate in 90 degrees so the left
// polygon is now were the front poly was. BUT the front poly is part of
// the group ,so it was rotated too. consecutive calls to this function
// will cause a 90 degrees rotation each time. like a dog trying to catch its tail.
STATE_IMPORT int STATE_WINAPI STATE_group_rotate_to_match_polygon(DWORD group_handle, DWORD polygon_in_the_group, DWORD reference_polygon, int inverse_flag);
// Similar to STATE_group_rotate_to_match_polygon()
// with the difference that here we have an auxiliary line (going through points p1 and p2)
// To make things clearer let's say we have a square polygon_in_the_group
// and a square reference_polygon, there are four final position for the group
// so that polygon_in_the_group points to the same direction as reference_polygon.
// (each one of the four edges of one group polygon can be aligned with an edge of the
// reference polygon). STATE_group_rotate_to_match_polygon() rotates so it will make
// the minimal rotation. This is usually what we want. So usually we will use
// STATE_group_rotate_to_match_polygon(). We will use this function when we want
// to turn around a specific line. All the rest is exactly like in STATE_group_rotate_to_match_polygon()
// Returns OK or VR_ERROR.
STATE_IMPORT int STATE_WINAPI STATE_group_rotate_around_line_to_match_polygon(DWORD group_handle, DWORD polygon_in_the_group, DWORD reference_polygon, int inverse_flag, double p1[3], double p2[3]);
// The same as STATE_group_rotate_to_match_polygon() only that uses a direction instead of a reference polygon.
STATE_IMPORT int STATE_WINAPI STATE_group_rotate_to_match_direction(DWORD group_handle, DWORD polygon_in_the_group, double direction[3]);
// The given group is moved so his given point will match
// "point_to_match" (the third argument);
// return OK or VR_ERROR.
STATE_IMPORT void STATE_WINAPI STATE_group_move_to_match_point(DWORD group_handle, DWORD point_belongs_to_group, DWORD point_to_match);
STATE_IMPORT int STATE_WINAPI STATE_group_is_bitmap_used(DWORD group_handle, DWORD bitmap_handle);
// finds how many intersections between polygons of groupA (that dont belong to grpB)
// and polygons of group B (that are not included in A)
// groupA or groupB could be NULL (means the whole world) or any other group
STATE_IMPORT int STATE_WINAPI STATE_group_count_intersections(DWORD groupA, DWORD groupB);
// Returns a handle to a polygon.
// The returned polygon is the first polygon that his orientation fits (according to the orientation field of the polygon)
// See also STATE_polygon_set_orientation() and STATE_polygon_get_orientation()
STATE_IMPORT DWORD STATE_WINAPI STATE_group_get_bottom_polygon(DWORD group_handle);
STATE_IMPORT DWORD STATE_WINAPI STATE_group_get_top_polygon(DWORD group_handle);
STATE_IMPORT DWORD STATE_WINAPI STATE_group_get_front_polygon(DWORD group_handle);
STATE_IMPORT DWORD STATE_WINAPI STATE_group_get_back_polygon(DWORD group_handle);
// What is orientation and why do we need it.
// When we want to drop an objectgroup on the ground (another surface) we need to know
// what surface of the objectgroup should be glued to the ground.
// The computer of course doesnt know on his own that a piano should stand on its legs ...
// With this flag the designer of the model can express his will that the piano should stand on its legs ...
//
// In order to fully define the orientation of a group, one polygon of the group should have ORIENTATION_BOTTOM or ORIENTATION_top
// and a second polygon should have ORIENTATION_FRONT or ORIENTATION_BACK beside those two polygons all the rest
// should have ORIENTATION_UNKNOWN. Nothing bad happens if they dont, it is just that it can cause contradiction.
//
// Going back to STATE_group_set_orientation(),
// the orientation_value should be one of the five values ORIENTATION_UNKNOWN ,ORIENTATION_TOP ORIENTATION_BOTTOM, ORIENTATION_FRONT, ORIENTATION_BACK
// if given ORIENTATION_UNKNOWN, then all the polygons of the group will be set with ORIENTATION_UNKNOWN.
// In this case polygon_handle could be NULL
// if given ORIENTATION_BOTTOM, then the given polygon will be set with ORIENTATION_BOTTOM, and all the other polygons of the group that had ORIENTATION_BOTTOM or ORIENTATION_TOP will be set with ORIENTATION_UNKNOWN
// if given ORIENTATION_TOP, then the given polygon will be set with ORIENTATION_TOP, and all the other polygons of the group that had ORIENTATION_BOTTOM or ORIENTATION_TOP will be set with ORIENTATION_UNKNOWN
// if given ORIENTATION_FRONT, then the given polygon will be set with ORIENTATION_FRONT, and all the other polygons of the group that had ORIENTATION_FRONT or ORIENTATION_BACK will be set with ORIENTATION_UNKNOWN
// if given ORIENTATION_BACK, then the given polygon will be set with ORIENTATION_BACK, and all the other polygons of the group that had ORIENTATION_FRONT or ORIENTATION_BACK will be set with ORIENTATION_UNKNOWN
// See also STATE_polygon_set_orientation()
STATE_IMPORT void STATE_WINAPI STATE_group_set_orientation(DWORD group_handle, DWORD polygon_handle, int orientation_value);
//Gets the group axis system according to the orientation of its polygons.
//If there are more than one polygon with the same orientation
// it will choose first, those polygons that belong directly to the group.
// In order to define the group axis system we need to have
// at least two polygons with the orientation flag given.
// one polygon should have the orientation FRONT or BACK and
// the other should be BOTTOM or TOP
// If there is only one polygon with orientation, the function will complete
// the rest according to the computer's understanding ....
// If there is no polygon with a given orientation it will again try to build
// the best system it can ...
// Return value
//--------------
// OK or VR_ERROR. In any case the axis_system given is legal.
// in case of error the axis system will be the same as the world axis system (1,0,0; 0,1,0; 0,0,1)
STATE_IMPORT int STATE_WINAPI STATE_group_calculate_axis_system(DWORD group_handle, double x_axis[3], double y_axis[3], double z_axis[3]);
/*
// Set the object to chase after
// the given argument should NOT be NULL
// Note that if the group was previously chasing a camera or a group
// , those chasing operation are canceled. (The group can chase only one thing at a time).
STATE_IMPORT void STATE_WINAPI STATE_group_set_object_to_chase(DWORD group_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_group_get_chased_object(DWORD group_handle);
// Set the camera to chase after
// the given argument should NOT be NULL
// Note that if the group 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_group_set_camera_to_chase(DWORD group_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_group_get_chased_camera(DWORD group_handle);
// Set the group to chase after
// the given argument should NOT be NULL
// Note that if the group 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_group_set_group_to_chase(DWORD group_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_group_get_chased_group(DWORD group_handle);
*/
// name could be a name of a camera , object or a group.
STATE_IMPORT void STATE_WINAPI STATE_group_set_name_to_chase(DWORD group_handle, char *name);
// If the return value is NULL it means nothing is being chased
STATE_IMPORT char * STATE_WINAPI STATE_group_get_chased_name(DWORD group_handle);
// return OK or VR_ERROR
// the offset is returned through argument "offset"
STATE_IMPORT int STATE_WINAPI STATE_group_get_chase_offset(DWORD group_handle, double offset[3]);
// return OK or VR_ERROR
STATE_IMPORT int STATE_WINAPI STATE_group_set_chase_offset(DWORD group_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_group_get_chase_softness(DWORD group_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_group_set_chase_softness(DWORD group_handle, double softness);
// look in the header file for possible values and their meanings
// (look for NO_CHASE, CHASE_LOCATION and others ...)
STATE_IMPORT char *STATE_WINAPI STATE_group_get_chase_type_name(DWORD group_handle);
// Like STATE_group_get_chase_type_name() only that returns the equivalent constant
STATE_IMPORT int STATE_WINAPI STATE_group_get_chase_type(DWORD group_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_group_set_chase_type(DWORD group_handle, int chase_type);
STATE_IMPORT void STATE_WINAPI STATE_group_set_track_name(DWORD group_handle, char *track_name);
STATE_IMPORT char * STATE_WINAPI STATE_group_get_track_name(DWORD group_handle);
// the offset is return through argument "offset"
STATE_IMPORT void STATE_WINAPI STATE_group_get_track_offset(DWORD group_handle, double offset[3]);
STATE_IMPORT void STATE_WINAPI STATE_group_set_track_offset(DWORD group_handle, double offset[3]);
// Calling this function will make the group fall down from
// it's track till it reaches "height_above_ground" distance from the ground
// fall_through_dynamic_objects could be YES or NO. the idea here is that if for example we have a runner (human being)
// and the track is very high in the air then it might fall on the top of the airplanes so we would like it to fall through the planes on the ground
// if on the other hand there are cars on the ground we would like it to fall on the top of the cars and not to pass through.
STATE_IMPORT void STATE_WINAPI STATE_group_set_falling_from_track(DWORD group_handle, double height_above_ground, int fall_through_dynamic_objects);
STATE_IMPORT void STATE_WINAPI STATE_group_unset_falling_from_track(DWORD group_handle);
// Returns the current status in the three params: set_flag, height_above_ground, fall_through_dynamic_objects
// set_flag could be YES or NO
// fall_through_dynamic_objects could be YES or NO . See STATE_group_set_falling_from_track() for more details
STATE_IMPORT void STATE_WINAPI STATE_group_get_falling_from_track_params(DWORD group_handle, int *set_flag, double *height_above_ground, int *fall_through_dynamic_objects);
STATE_IMPORT void STATE_WINAPI STATE_group_get_speed(DWORD group_handle, double speed[3]);
STATE_IMPORT void STATE_WINAPI STATE_group_set_speed(DWORD group_handle, double speed[3]);
STATE_IMPORT double STATE_WINAPI STATE_group_get_absolute_speed(DWORD group_handle);
STATE_IMPORT void STATE_WINAPI STATE_group_set_absolute_speed(DWORD group_handle, double speed);
// rotates the group so that the orientation of the group matches the given directions
// The given directions dont have to be normalized.
// one of the direction can be 0,0,0 in this case it is calculated automatically.
// If the given axis are not orthogonal, the function
// handle it by building an orthogonal system that is close as possible
// to the given axis.
// see also STATE_group_calculate_axis_system()
// 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_group_rotate_to_match_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_group_rotate_to_match_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_group_rotate_to_match_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_group_rotate_to_match_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_group_rotate_to_match_axis_system(x_axis, y_axis, z_axis);
//
// Returns OK or VR_ERROR.
STATE_IMPORT int STATE_WINAPI STATE_group_rotate_to_match_axis_system(DWORD group_handle, double x_axis[3], double y_axis[3], double z_axis[3]);
// Rotates the group around the given line.
// Returns OK or VR_ERROR.
STATE_IMPORT int STATE_WINAPI STATE_group_rotate_around_line(DWORD group_handle, double p1[3], double p2[3], double degrees);
// Stretch a bitmap on all the polygons that belong to a group.
// works best if the group is flat like floor or terrain.
// If group_handle==NULL it will effect the whole world
// If bitmap_handle==NULL it wont change the bitmap.
// Note that if you want the bitmap to repeat more than once on the model (tile mode)
// then the dimensions of the bitmap must be in the power of two (for example 32,64,128,256,512,1024,2048 etc ...
// all these numbers are powers of two).
// returns OK or VR_ERROR
STATE_IMPORT int STATE_WINAPI STATE_group_wrap_a_bitmap(DWORD group_handle, DWORD bitmap_handle, int repeat_x, int repeat_y);
// Obsolete, use STATE_group_create_reduced_copy() instead
// This function reduces the number of polygons by
// eliminating redundant polygons and by joining several polygons
// into one polygon.
// accuracy is used when we try to check whether two polygons
// have the same plane (so we can unite them to one polygon).
// If this number for example is 0.1 and
// the X component if the normals are planeA[0]=1 and planeB[0]=0.9
// then the join operation will take place.
// can be done only in editor mode.
// returns the number of polygons that were reduced.
// Returns VR_ERROR on failure on success returns the number of polygons that were reduced
STATE_IMPORT int STATE_WINAPI STATE_group_reduce_polygons_count(DWORD group_handle ,double accuracy);
//This is a very powerfull function for doing polygon reduction.
//optimization_level: a bigger number will give a stronger polygon reduction.
// one should play with this value to achieve the optimum result.
// tipical values are 0.1, 1, 10 , 100.
// a value of 1 for example will snap the model into a grid that
// its smallest unit is 1.
//
//returns a handle to the new group of polygons.
STATE_IMPORT DWORD STATE_WINAPI STATE_group_create_reduced_copy(DWORD group_to_copy, double optimization_level) ;
// similar to STATE_group_duplicate_tree() just that the new copy will be made of triangles only.
// Returns a handle to the new copy
STATE_IMPORT DWORD STATE_WINAPI STATE_group_create_copy_made_of_triangles(DWORD group_to_copy) ;
// Returns YES or NO.
// NO means that you cant use STATE_group_rotate() to rotate the group
// The function will return NO, only if the group has at least one rotated polygon inside
STATE_IMPORT int STATE_WINAPI STATE_group_is_rotation_enabled(DWORD group_handle);
//Returns OK or VR_ERROR
STATE_IMPORT int STATE_WINAPI STATE_group_convert_point_to_world_space(DWORD group_handle, double group_space_point[3], double result[3]);
STATE_IMPORT int STATE_WINAPI STATE_group_convert_point_to_group_space(DWORD group_handle, double world_space_point[3], double result[3]);
STATE_IMPORT void STATE_WINAPI STATE_group_set_chase_distance(DWORD group_handle, double chase_distance);
STATE_IMPORT double STATE_WINAPI STATE_group_get_chase_distance(DWORD group_handle);
//Exactly like STATE_polygon_delete_patches() only that it does it for the whole polygons of the group.
STATE_IMPORT void STATE_WINAPI STATE_group_delete_patches(DWORD group_handle, int type_of_patches_to_delete_or_serial_number);
//Set the color of all the patches in the group
// values for red green and blue should be in the range [0-255]
// patches_type should be one of the following: ALL_PATCHES, SHADOW_PATCHES, REGULAR_PATCHES
// or the serial number that was given when the patches were created
// Example A:
// //Setting the color to all the patches of the given group
// STATE_group_set_patches_color(my_room, ALL_PATCHES);
//
// Example B:
// //Setting the color to all the patches that were created using the functions
// //STATE_polygon_add_patch() and STATE_polygon_add_patch_easy()
// STATE_group_set_patches_color(my_room, REGULAR_PATCHES);
//
// Example C:
// Setting the color to all the patches that were created using the function STATE_engine_create_shadow()
// STATE_group_set_patches_color(my_room, SHADOW_PATCHES);
//
// Example D:
// Delete patches that were created using the function STATE_engine_create_shadow() with a serial_number==220
// STATE_group_set_patches_color(my_room, 39);
//
// See also: STATE_engine_create_shadow(), STATE_polygon_add_patch() ,STATE_polygon_add_patch_easy()
// STATE_polygon_delete_patches(), STATE_group_delete_patches()
STATE_IMPORT void STATE_WINAPI STATE_group_set_patches_color(DWORD group_handle, int red, int green, int blue, int patches_type);
STATE_IMPORT void STATE_WINAPI STATE_group_set_patches_bitmap(DWORD group_handle, DWORD bitmap_handle, int patches_type);
STATE_IMPORT void STATE_WINAPI STATE_group_set_patches_translucent(DWORD group_handle, BYTE translucent_type, int patches_type);
//The functions below are the equivalent of STATE_group_getset_physics_...
//They will be useful for you only if you build some kind of World Editor (Such as STATE World Builder)
//The functions wont show any change till we save the world and reload it in Viewer mode
//and when the chase_type is set to CHASE_PHYSICS.
//
// Return value: The rotation space (WORLD_SPACE or OBJECT_SPACE)
// through rotation_xyz[] the function returns the rotation angles
// rotation_xyz[0] is the number of angles that the object will rotate
// around the X axis, each time STATE_engine_render() is called
// see also STATE_object_set_physics_rotation()
//Note that this is only relevant when applied to a dynamic group and that CHASE_PHYSICS is applied (only in viewer mode)
STATE_IMPORT int STATE_WINAPI STATE_group_get_physics_rotation(DWORD group_handle, double rotation_xyz[3]);
STATE_IMPORT void STATE_WINAPI STATE_group_set_physics_rotation(DWORD group_handle, int rotation_space ,double rotate_around_x_axis, double rotate_around_y_axis, double rotate_around_z_axis);
// Set the force that will work on the object. 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_group_set_force(my_object,force);
//
//Note that this is only relevant when applied to a dynamic group and that CHASE_PHYSICS is applied (only in viewer mode)
STATE_IMPORT void STATE_WINAPI STATE_group_set_physics_force(DWORD group_handle, double force[3]);
//The force is returned through force argument.
STATE_IMPORT void STATE_WINAPI STATE_group_get_physics_force(DWORD group_handle, double force[3]);
//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 act like pressing on the gas
// The exact calculation.
// Each render the absolute_speed is multiply with (1-friction).
//
// Note, a negative number can use 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 ...
//Note that this is only relevant when applied to a dynamic group and that CHASE_PHYSICS is applied (only in viewer mode)
STATE_IMPORT double STATE_WINAPI STATE_group_get_physics_friction(DWORD group_handle);
STATE_IMPORT void STATE_WINAPI STATE_group_set_physics_friction(DWORD group_handle, double friction);
//This number is used when the object 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.
//Note that this is only relevant when applied to a dynamic group and that CHASE_PHYSICS is applied (only in viewer mode)
STATE_IMPORT double STATE_WINAPI STATE_group_get_physics_elasticity(DWORD group_handle);
STATE_IMPORT void STATE_WINAPI STATE_group_set_physics_elasticity(DWORD group_handle, double elasticity);
//Limits the maximum possible speed of an object.
//If there is no limit then by applying force on the object
//The speed could reach infinity (unless some friction is given too)
//Note that this is only relevant when applied to a dynamic group and that CHASE_PHYSICS is applied (only in viewer mode)
STATE_IMPORT double STATE_WINAPI STATE_group_get_physics_maxspeed(DWORD group_handle);
STATE_IMPORT void STATE_WINAPI STATE_group_set_physics_maxspeed(DWORD group_handle, double max_speed);
//This function is not so important ...
//This function associates a number with the group
//later (When the world is saved and load in viewer mode
//we can get this number using STATE_object_get_control_type_number()
//Note that the function does nothing it is just a set and get mechanism.
//The number that you give has no meaning to the Engine.
//The meaning is as given by the application that is using the engine.
//parameters:
// num: any integer that is equal or greater than 64
// (the first 63 numbers are reserved for future use)
STATE_IMPORT void STATE_WINAPI STATE_group_set_control_number(DWORD group_handle, int num);
STATE_IMPORT int STATE_WINAPI STATE_group_get_control_number(DWORD group_handle);
// Similar to STATE_group_wrap_a_bitmap()
// The difference is that STATE_group_wrap_a_bitmap() will
// stretch the bitmap so that the top right corner of the bitmap
// will fit to a corner of the group. This function
// will fit the corner of the bitmap the given location in the world
// locationXY_to_get_bitmap_top_left_corner[0], locationXY_to_get_bitmap_top_left_corner[1]
// This is the (X,Y) coordinate in the world that the top left corner of the bitmap will
// be associated with.
// This way the given group might only get a portion of the bitmap.
// In the special case where locationXY_to_get_bitmap_top_left_corner, and locationXY_to_get_bitmap_bottom_right_corner
// are the bounding box of the group then this function will do the same as
// STATE_group_wrap_a_bitmap()
// Returns OK or VR_ERROR
STATE_IMPORT int STATE_WINAPI STATE_group_wrap_a_bitmap_fixed(DWORD group_handle, DWORD bitmap_handle, int repeat_x, int repeat_y, double locationXY_to_get_bitmap_top_left_corner[2], double locationXY_to_get_bitmap_bottom_right_corner[2]);
// Obselete .(works only in software mode)
// Set the brightness of each polygon of the group according to the intensity of the light source.
// values for ambient and are in the range [0-400]
// values for light_intensity light_intensity are in the range [0-400]
// see STATE_polygon_set_brightness() for explanation of what those values mean
// ambient is the minimum light intensity that is, if the light source has zero intensity or points
// to the opposite direction , the polygon will have the ambient intensity. This is the light that reflects
// from the surroundings.
// Examples:
// A) direction[0]=1; direction[1]=0; direction[2]=0;
// STATE_group_light_group(grp, direction,20, 400) //A very strong source of light in a dark environment
//
// B) direction[0]=1; direction[1]=1; direction[2]=0; //The direction is diagonally
// STATE_group_light_group(grp, direction, 100, 100) //An average source of light in an average lit environment
//
// Note that actually one can also try negative values for the ambient and the light_intensity.
// note that the formula is final_intensity= ambient + angle_between_polygon_and_light_direction* light_intensity
// where angle_between_polygon_and_light_direction is normalized to the range [0-1]
// a negative light_intensity means that our light source gives darkness instead of light ! (a great new invention !)
STATE_IMPORT void STATE_WINAPI STATE_group_light_group(DWORD group_handle, double direction[3], double ambient, double light_intensity);
//Remove light from the group.
//If the given group was lit using the STATE_light API then
//this function could be used to restore the group normal appearance
//If the given group handle is NULL then light will be removed from the whole world.
//See also STATE_object_remove_light(), STATE_polygon_remove_light(), STATE_light_remove_light()
STATE_IMPORT void STATE_WINAPI STATE_group_remove_light(DWORD group_handle);
// Set the color of all the polygons that belong to the given group.
// rgb[0] ==red
// rgb[1]==green;
// rgb[2]==blue
//Example:
// BYTE rgb[3]={255,0,0}; //red color
// STATE_group_set_color(NULL, rgb); //Set the whole world to red
STATE_IMPORT void STATE_WINAPI STATE_group_set_color(DWORD group_handle, BYTE rgb[3]);
//Calls STATE_polygon_set_light() for all the polygons in the group
//For more details see STATE_polygon_set_light()
STATE_IMPORT void STATE_WINAPI STATE_group_set_light(DWORD group_handle, BYTE rgb[3]);
//Set the ambient light value to all the polygons contained in the given group
//For more details see STATE_polygon_set_ambient()
STATE_IMPORT void STATE_WINAPI STATE_group_set_ambient(DWORD group_handle, int value);
//Set the diffuse light value to all the polygons contained in the given group
//For more details see STATE_polygon_set_diffuse()
STATE_IMPORT void STATE_WINAPI STATE_group_set_diffuse(DWORD group_handle, int value);
//Set the specular light value to all the polygons contained in the given group
//For more details see STATE_polygon_set_specular()
STATE_IMPORT void STATE_WINAPI STATE_group_set_specular(DWORD group_handle, int value);
//The same as STATE_polygon_create_lightmap() only that it creates lightmaps bitmaps for all
//polygons of the given group.
//Returns the number of bitmaps that were created and assigned to the group.
//For more details see STATE_polygon_create_lightmap()
STATE_IMPORT int STATE_WINAPI STATE_group_create_lightmap(DWORD group_handle, int max_bm_side, int min_lightmap_size, double sample_rate, int force_ray_tracing, int bitmap_number);
//Disable or enabled a group.
//A disabled group is not included in rendering and in collision detection.
//This is a very important function for making large fast worlds using LOD (More details bellow)
//This function can be used to disable parts of the world that are not seen
//(This technique is done automatically when using the speed database)
// Another important usage is doing LOD (level of details)
// Each model in the world (building, mountain , a chair, etc ...) should be built
// several times. Each version of the model should use less polygons (for example the higher
// version should be built from 100 polygons, the second version from 50 polygons, the third from 20 polygons and
// the lowest level from just one rotated polygon that has a bitmap of the treechairbuilding or whatever model we
// are using).
// Before calling STATE_engine_render() check the distance between the camera (the view point)
// and each of the models that have LOD versions. Disable all the versions that should not be used
// and enable just the one that fits to the distance from the viewer
// The function is very fast (just set a flag and returns)
// Parameters:
// group_handle: the group to be disabled enabled
// YES_or_NO: YES to disable. NO to enable
//
// Example:
// //disabling a group
// STATE_group_disable(a_group_handle, YES);
STATE_IMPORT void STATE_WINAPI STATE_group_disable(DWORD group_handle, int YES_or_NO);
//Returns YES or NO. NO is return if the group is enabled.
//YES is returned if the group is disabled.
// See also STATE_group_disable();
STATE_IMPORT int STATE_WINAPI STATE_group_is_disable(DWORD group_handle);
//Set the given bitmap to all the polygon belonging to the given group.
// Parameters:
// group_handle: A handle to a group. NULL means the whole world.
// bitmap_handle: A handle to a bitmap to be set on all the polygons of the given group.
STATE_IMPORT void STATE_WINAPI STATE_group_set_bitmap(DWORD group_handle, DWORD bitmap_handle);
// Used to go over all the groups that belong to a certain group.
//
// Example:
// for(DWORD house_part=STATE_group_get_first_included_group(house_group); house_part!=NULL; house_part=STATE_group_get_next_included_group(house_group, house_part) ) {
// // Deal with the various house parts such as roof, windows, door etc ...
//
// }
//
// Note:
// Don't mix this function with STATE_group_get_first_group() and
// STATE_group_get_next() which are used to go over ALL the existing groups.
//
// To go over all the groups the belong to a certain object use STATE_object_get_group_handle() as the top group handle
//
STATE_IMPORT DWORD STATE_WINAPI STATE_group_get_first_included_group(DWORD top_group_handle);
// Used to go over all the groups that belong to a certain group.
//
// Example:
// for(DWORD house_part=STATE_group_get_first_included_group(house_group); house_part!=NULL; house_part=STATE_group_get_next_included_group(house_group, house_part) ) {
// // Deal with the various house parts such as roof, windows, door etc ...
//
// }
//
// Note:
// Don't mix this function with STATE_group_get_first_group() and
// STATE_group_get_next() which are used to go over ALL the existing groups
//
// To go over all the groups the belong to a certain object use STATE_object_get_group_handle() as the top group handle
//
STATE_IMPORT DWORD STATE_WINAPI STATE_group_get_next_included_group(DWORD top_group_handle, DWORD last_included_found);
//-----------------------------------------------------------//
//========= T H E 3 D _ A N I M A T I O N A P I =========//
//-----------------------------------------------------------//
//This API deals with 3D model animation (mesh morphing)
//A 3D animation is a set of 3D models that are slightly different from one another
//Those 3D models are called 3D frames. For example a 3D animation of a man walking
//would contain several frames for completing a whole walking cycle.
//Usually the 3D character has several movements that it can perform.
//(For example, walk, jump, hit, fall down etc ...) each movement is combined
// of several frames and is called a 3D sequence.
// To summarize it: Each 3D animation is built from many 3D frames. The 3D frames are divided
// into separate 3D sequences. If it all sounds complicated then the following example will
//clear things up.
// my_obj=STATE_object_create_from_file("woman.md2"); //The md2 files contain a 3D animation. The 3D animation is automatically loaded to the engine
// my_3danim=STATE_object_get_3D_animation(my_obj);
// walk_sequence=STATE_3D_animation_get_sequence_using_name(my_3danim,"walk");
// standing_sequence=STATE_3D_animation_get_sequence_using_name(my_3danim,"stand");
// undressing_sequence=STATE_3D_animation_get_sequence_using_name(my_3danim,"undress");
// if(key_1_is_pressed) STATE_object_set_3D_sequence(my_obj,walk_sequence);
// if(key_2_is_pressed) STATE_object_set_3D_sequence(my_obj,undressing_sequence);
// and so on ...
//
//Please also note the 3D_sequence API which is used in conjunction with this API
// This function, together with STATE_3D_animation_get_next()
// are used for going over all the defined 3D animations
// Example
// for(DWORD anim3d=STATE_3D_animation_get_first(); anim3d!=NULL; anim3d=STATE_3D_animation_get_next(anim3d) {
// //Write here the code to do for each anim3d
// }
// Note that the function STATE_3D_animation_create() adds a new anim3d
// to top of the queue. So STATE_3D_animation_get_first()
// will always return the last anim3d that was created.
// The same rule is for all STATE_xxxx_get_first() functions.
STATE_IMPORT DWORD STATE_WINAPI STATE_3D_animation_get_first(void);
STATE_IMPORT DWORD STATE_WINAPI STATE_3D_animation_get_next(DWORD anim3d_handle);
//Deletes all the existing 3d animations
STATE_IMPORT void STATE_WINAPI STATE_3D_animation_delete_all(void);
//Deletes the given anim3d.
// Note not to use the handle after it the anim3d was deleted
// Example:
// STATE_3D_animation_delete(my_anim3d);
// my_anim3d=NULL;
STATE_IMPORT void STATE_WINAPI STATE_3D_animation_delete(DWORD anim3d_handle);
//Returns a handle to the anim3d according to the given name
STATE_IMPORT DWORD STATE_WINAPI STATE_3D_animation_get_using_name(char *anim3d_name);
// Returns the name of the animation
// 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_3D_animation_get_name(DWORD anim3d_handle);
//Returns YES or NO. NO is returned if the given handle
//is not a handle of a 3D_animAtion. YES is returned otherwise
STATE_IMPORT int STATE_WINAPI STATE_3D_animation_is_3D_animation(DWORD anim3d_handle, char *function_asking);
// ===============================================================================
// === More 3D animation functions (beginners can skip this group of functions)===
// ===============================================================================
//
// Use the function below for the following purposes:
// 1) To change your 3d animation in real time
// For example your game character has been beaten severly
// you can now modify in real-time the points of the animation
// to create a swollen face damaged body etc ...
// To modify the 3D animation polygons use STATE_3D_animation_set_triangle_xyz()
//
// 2) To create various effects. For example you can build the first frame as a duplication of a house
// the second frame can be a car. When the engine will interpolates between the frames it will
// create 3D morphing animating gradually from a house to a car.
// You could get the same effect by building an md2 animation
// (using one of the md2 editors available on the Internet) with two frames.
// and loading the aniamtion into the engine (for example STATE_object_create_from_file("woman.md2") )
//
// 3) To write converters from other 3d animation formats to STATE.
// To do so simply, create an empty 3d animation using STATE_3D_animation_create_for_editing()
// Set the points of all the polygons in each frame to their right value
// according to the file format you want to import.
// Use STATE_3D_animation_set_triangle_xyz() and STATE_3D_animation_set_triangle_bmp_uv()
// to set the polygons. When finished call STATE_3D_animation_save()
// Example:
// //converting a 3D frames based animation from your favorite format to STATE anim3d format
// void main()
// {
// DWORD anim3d=STATE_3D_animation_create_for_editing("my_anim", 600, 20);
//
// int num_of_frames=STATE_3D_animation_get_number_of_frames(anim3d);
// int num_of_triangles=STATE_3D_animation_get_number_of_triangles(anim3d);
//
// for(int frame=0; frame< num_of_frames; frame++) {
// for(int tri=0; tri<num_of_triangles; tri++) {
// for(point=0; point<3; point++) {
// float xyz[3];
// get_the_point_from_your_favorite_format(frame, tri,point, xyz); //You should write your own implementation to this function
// float bmp_uv[2];
// get_the_point_texture_coords_from_your_favorite_format(frame, tri,point, xyz); //You should write your own implementation to this function
// STATE_3D_animation_set_triangle_xyz(anim3d, tri, i, frame, xyz);
// STATE_3D_animation_set_triangle_bmp_uv(anim3d, tri, i, frame, bmp_uv);
// }
// }
// }
//
// STATE_3D_animation_save(anim3d,"my_anim.anim3d");
// }
//Creates a new empty 3D animation that can be edited.
// Use the functions below to edit the 3D animation.
// Returns a handle to the newly created 3D Animation.
// After finishing editing call STATE_3D_animation_finished_editing()
// Only after calling STATE_3D_animation_finished_editing() one can use the 3D animation
// in functions such as STATE_object_set_3D_animation()
STATE_IMPORT DWORD STATE_WINAPI STATE_3D_animation_create_for_editing(char *name, int number_of_triangles, int number_of_frames);
//Rebuilds the animation sequances and make it ready for use.
//See also STATE_3D_animation_create_for_editing(), STATE_3D_animation_set_frame_name(),
//STATE_3D_animation_set_triangle_xyz()
STATE_IMPORT int STATE_WINAPI STATE_3D_animation_finished_editing(DWORD anim3d_handle);
//Note that when the different sequences are built (when STATE_3D_animation_finished_editing() is called)
//they are built according to the frames names. for example if we have 6 frames with the names
// walk1, walk2, walk3, run1, run2, run3
//then the engine will build 2 squences with the name Walk and Run.
//By setting the frames name you control later the names and number of the sequences.
STATE_IMPORT char *STATE_WINAPI STATE_3D_animation_get_frame_name(DWORD anim3d_handle, int frame_number);
STATE_IMPORT void STATE_WINAPI STATE_3D_animation_set_frame_name(DWORD anim3d_handle, int frame_number, char *name);
STATE_IMPORT int STATE_WINAPI STATE_3D_animation_get_number_of_triangles(DWORD anim3d_handle);
STATE_IMPORT int STATE_WINAPI STATE_3D_animation_get_number_of_frames(DWORD anim3d_handle);
//Returns a point of a given triangle in a given frame.
//The result is returned through xyzuv
// xyzuv[0] is the X value. xyzuv[1] is the Y value
//xyzuv[3] is the bitmap u coordinate of the requested point.
//xyzuv[4] is the bitmap v coordinate of the requested point.
//
// triangle_number
// The index of the triangle in the specified frame. 0 is the first triangle.
//
// frame_number
// The index of the animation frame . 0 is the first frame
//
// triangle_point
// can be 0,1,2. Determins the triangle point to retrieve information from.
//
// Returns OK or VR_ERROR.
STATE_IMPORT int STATE_WINAPI STATE_3D_animation_get_triangle_point(DWORD anim3d_handle, int triangle_number, int triangle_point, int frame_number, float xyzuv[5]);
//The same as STATE_3D_animation_get_triangle_point() only that it doesnt retrieve the bitmap coordinations
STATE_IMPORT int STATE_WINAPI STATE_3D_animation_get_triangle_xyz(DWORD anim3d_handle, int triangle_number, int triangle_point, int frame_number, float xyz[3]);
//Set a specific point of the animation
//See STATE_3D_animation_get_triangle_point() for more information
//
// Note 1
//--------
//Please remember to give a name to a frame before you change its point
//set the frame name using STATE_3D_animation_set_frame_name()
//The name should start with letters and end with digits. For example
//walk02. After calling STATE_3D_animation_finished_editing() all consequtive frames that have the same letters
//will be grouped into one sequence. For example walk01, walk02, walk03 will be grouped to sequence walk.
//
// Note 2
//--------
//Please note that modifying points of the animation doesnt work very well with the md2 file format
//This is because the md2 file format represent each point with three BYTES (Thats right, only one byte for X, one for Y and one for Z !!!)
//In order to modify an md2 animation in realtime it is best to convert it first to the anim3d format.
//To convert from md2 to the anim3d format simply do a short program that looks like this
//
// void main()
// {
// DWORD obj=STATE_object_create_from_file("woman.md2");
// DWORD anim3d=STATE_object_get_3D_animation(obj);
// STATE_3D_animation_save(anim3d,"woman.anim3d");
// }
//
// Note that the anim3d format is a lot better for manipulating frames in realtime
// though the file created is a lot bigger. This means that it will use more memory
// and thus is less recommended to use if you have many models and you are concern
// with the speed of your application.
//
STATE_IMPORT int STATE_WINAPI STATE_3D_animation_set_triangle_xyz(DWORD anim3d_handle, int triangle_number, int triangle_point, int frame_number, float xyz[3]);
//Set the bitmap coord of a specific animation
//See STATE_3D_animation_get_triangle_point() for more information
STATE_IMPORT int STATE_WINAPI STATE_3D_animation_set_triangle_bmp_uv(DWORD anim3d_handle, int triangle_number, int triangle_point, int frame_number, float bmp_uv[2]);
//Save the animation in STATE 3D animation file format.
//The saved file can be later loaded using STATE_object_create_from_file();
// One of the uses for this function could be if you are writing a converter
// from your own 3D animation file format to STATE.
STATE_IMPORT int STATE_WINAPI STATE_3D_animation_save(DWORD anim3d_handle, char *anim3d_file_name);
//-----------------------------------------------------------//
//========= T H E 3 D _ S E Q U E N C E A P I =========//
//-----------------------------------------------------------//
//This API deals with 3D animation sequence (mesh morphing)
// Each 3D animation is built from many 3D frames. The 3D frames are divided
// into separate 3D sequences. For example there could be a "walking sequence"
// which is made of several frames that animate a full walking cycle.
//See also the STATE_3D_animation API,
// STATE_object_set_3D_sequence(), STATE_object_get_3D_sequence()
// STATE_object_replace_3D_sequence_when_finished(), STATE_object_create_from_file()
// This function, together with STATE_3D_sequence_get_next()
// are used for going over all the defined 3D sequences
// Example
// for(DWORD seq3d=STATE_3D_sequence_get_first(); seq3d!=NULL; seq3d=STATE_3D_sequence_get_next(seq3d) {
// //Write here the code to do for each seq3d
// }
// Note that the function STATE_3D_sequence_create() adds a new seq3d
// to top of the queue. So STATE_3D_sequence_get_first()
// will always return the last seq3d that was created.
// The same rule is for all STATE_xxxx_get_first() functions.
STATE_IMPORT DWORD STATE_WINAPI STATE_3D_sequence_get_first(DWORD animation3D_handle);
STATE_IMPORT DWORD STATE_WINAPI STATE_3D_sequence_get_next(DWORD sequence3d_handle);
//Returns a handle to the seq3d according to the given name
STATE_IMPORT DWORD STATE_WINAPI STATE_3D_sequence_get_using_name(DWORD animation3D_handle, char *sequence3d_name);
// Returns the 3D sequence name.
// 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_3D_sequence_get_name(DWORD sequence3d_handle);
//Deletes all the existing 3d sequences
STATE_IMPORT void STATE_WINAPI STATE_3D_sequence_delete_all(DWORD animation3D_handle);
//Deletes the given seq3d.
// Note not to use the handle after it the seq3d was deleted
// Example:
// STATE_3D_sequence_delete(my_seq3d);
// my_seq3d=NULL;
STATE_IMPORT void STATE_WINAPI STATE_3D_sequence_delete(DWORD animation3D_handle,DWORD sequence3d_handle);
//Returns YES or NO. NO is returned if the given handle
//is not a handle of a 3D_sequence. YES is returned otherwise
STATE_IMPORT int STATE_WINAPI STATE_3D_sequence_is_3D_sequence(DWORD sequence3d_handle, char *function_asking);
//The default speed is 1. A speed of 2 means twice slower. A speed of 0.5 means twice as fast.
//The default duration between to consecutive frames is 1 tenth of a second.
// See also STATE_3D_sequence_set_frame_duration()
// Example:
// Lets assume that the frame duration wasn't changed from it default (you can change it using STATE_3D_sequence_set_frame_duration() )
//That means 1 tenth of a second between two frames.
//So if the speed is equal to two then the duration between consecutive frames will be 2 tenth of a second
STATE_IMPORT void STATE_WINAPI STATE_3D_sequence_set_speed(DWORD sequence3d_handle, double speed);
STATE_IMPORT double STATE_WINAPI STATE_3D_sequence_get_speed(DWORD sequence3d_handle);
//Returns the number of frames that belongs to the given sequence.
STATE_IMPORT int STATE_WINAPI STATE_3D_sequence_get_number_of_frames(DWORD sequence3d_handle);
//The time is in mili of seconds
//0 is the first frame of the sequence and (number_of_sequence_frames-1) is the last
//returns -1 if an error occurred.
STATE_IMPORT int STATE_WINAPI STATE_3D_sequence_get_frame_duration(DWORD sequence3d_handle, int frame_number);
//returns OK or VR_ERROR
STATE_IMPORT int STATE_WINAPI STATE_3D_sequence_set_frame_duration(DWORD sequence3d_handle, int frame_number, int duration);
//Returns YES or NO
//A cyclic sequence means that when the last frame is reached is starts all over again
// A non cyclic sequence will stop animating when the sequencs reaches the last frame.
STATE_IMPORT int STATE_WINAPI STATE_3D_sequence_is_cyclic(DWORD sequence3d_handle);
STATE_IMPORT void STATE_WINAPI STATE_3D_sequence_set_cyclic(DWORD sequence3d_handle, int YES_or_NO);
//Move the sequence to a specific position.
//current_frame should be in the range [0 - number_of_frames_in_sequence]
//Note that current_frame is double. Values like 3.76 are allowed
//In this case frames 3 and frame 4 will be interpolated to represent the given frame number
STATE_IMPORT void STATE_WINAPI STATE_3D_sequence_set_current_frame(DWORD sequence3d_handle, double current_frame);
//Note that current_frame is double. Values like 3.76 mean
//that frames 3 and frame 4 are interpolated in the correct proportions
//
STATE_IMPORT double STATE_WINAPI STATE_3D_sequence_get_current_frame(DWORD sequence3d_handle);
//Will stop the animation (model morphing)
STATE_IMPORT void STATE_WINAPI STATE_3D_sequence_pause(DWORD sequence3d_handle);
//This function will continue playing the animation after it was paused.
STATE_IMPORT void STATE_WINAPI STATE_3D_sequence_play(DWORD sequence3d_handle);
//Return YES or NO
STATE_IMPORT int STATE_WINAPI STATE_3D_sequence_is_paused(DWORD sequence3d_handle);
//Change the direction of the 3D sequence. For example
//If our character walks then one we will walk backwards we will want to change
//the order of the sequence.
STATE_IMPORT void STATE_WINAPI STATE_3D_sequence_backwards_play(DWORD sequence3d_handle, int YES_or_NO);
STATE_IMPORT int STATE_WINAPI STATE_3D_sequence_is_backwards(DWORD sequence3d_handle);
//Returns the number of times that we have passed the last frame in the sequence
//If the sequence is not cyclic then this function will return 0 or 1.
//This function can be used to check if the sequence was finished.
STATE_IMPORT int STATE_WINAPI STATE_3D_sequence_get_number_of_laps(DWORD sequence3d_handle);
//This function is very useful and is often used
// together with STATE_object_set_3D_sequence()
//This function creates a copy of the given sequence and add it
//to the 3D_sequence list of the given 3D_animation.
//Usually the given animation3D_handle is the 3D animation that
// sequence_to_duplicate belongs too.
// Using this function we can create for each object
// its own copy of the 3D_sequence thus when we will change the sequence
// properties it will effect only this object.
// name is the name to be given to the duplicated copy.
//Return value: The function returns a handle to the new sequence that was created.
//See also STATE_object_set_3D_sequence() (very recommended)
// Example:
// STATE_3D_sequence_duplicate(robot_animation, walk_sequence,"robot1_walk");
STATE_IMPORT DWORD STATE_WINAPI STATE_3D_sequence_duplicate(DWORD animation3D_handle, DWORD sequence_to_duplicate, char *name);
//----------------------------------------------//
//========= T H E L I G H T A P I =========//
//----------------------------------------------//
//This API deals with making light. It supports dynamic colored Gouraud shading light !
// Please also notice this powerful function: STATE_engine_create_shadow()
// STATE_engine_create_shadow() uses projection method techniques for creating light
// while the light API is using Gouraud shading technique. Both methods
// could be mixed together to create great effects.
// Please also note that Gouraud shading is using vertex lighting.
// This means that the effects will be much better if there are more vertexes (that means more polygons)
//Use this function to create a new light.
// light_name is the name you want to call this light (give what ever name you want)
// The location is the x,y,z coordinates of the light location
// The location can be moved later using the function STATE_light_set_location()
// Example:
// double position[3]={10,20,30} ; //x=10, y=20, z=30
// DWORD light=STATE_light_create("my_light",position);
STATE_IMPORT DWORD STATE_WINAPI STATE_light_create(char *light_name, double location[3]);
#define LIGHT_SET 0
#define LIGHT_ADD 1
#define LIGHT_SUBTRACT 2
// This function is the function that actually creates the light !
// You wont see any light till you call this function.
// For dynamic lighting this function should be call over and over
// each time there is some change (for example the lit object changed position)
// For faster lighting in viewer mode use the function
// STATE_light_set_entity_to_light(my_light,my_object);
// to light every object in the world separately.
// The light operation could be any one of the following
// LIGHT_SET, LIGHT_ADD, LIGHT_SUBTRACT
// Here is what each one will do:
// LIGHT_ADD:
// The calculated light will be added to the existing light.
// Each call will make the illuminated entity brighter
// LIGHT_SUBTRACT:
// This will cause the light source to create darkness !!!
// In the real world we dont have an equivalent for that.
// Subsequent calls will make the illuminated entity becomes darker on each call
// LIGHT_SET:
// The entity will be illuminated while ignoring previous illuminations.
// Normally you will use this option.
// Subsequent calls wont make any different unless
// The location, direction or other properties of the light have changed between calls or
// that we are illuminating a dynamic objects that has change it position
// (and thats why we have to recalculate its illumination)
// Example:
// STATE_light_activate(my_light, LIGHT_SET);
//
// The light is created with the following defaults:
// * A non-directional light ( use STATE_light_set_type_of_light() to change it and then use STATE_light_set_direction() to set the direction).
// * Infinite distance. The light could reach an infinite distance without getting less intense . Use STATE_light_set_distance_reach() to change it.
// * The whole world is illuminated. Use STATE_light_set_entity_to_light() to change it. This will make this function much faster.
// * White color. The default color is white (255,255,255) Use STATE_light_set_color() to change it.
STATE_IMPORT void STATE_WINAPI STATE_light_activate(DWORD light_handle, int light_operation);
//Returns a handle to the light according to the given name
STATE_IMPORT DWORD STATE_WINAPI STATE_light_get_using_name(char *light_name);
// This function, together with STATE_light_get_next_light()
// are used for going over all the defined lights
// Example
// for(DWORD light=STATE_light_get_first_light(); light!=NULL; light=STATE_light_get_next_light(light) {
// //Write here the code to do for each light
// }
// Note that the function STATE_light_create() adds a new light
// to top of the queue. So STATE_light_get_first_light()
// will always return the last light that was created.
// The same rule is for all STATE_xxxx_get_first_xxxx() functions.
STATE_IMPORT DWORD STATE_WINAPI STATE_light_get_first_light(void);
STATE_IMPORT DWORD STATE_WINAPI STATE_light_get_next_light(DWORD light_handle);
//Sets the location of the light.
// Example
// double location[3]={10,20,30} //setting the X,Y,Z coordinates
// STATE_light_set_location(my_light,location);
STATE_IMPORT void STATE_WINAPI STATE_light_set_location(DWORD light_handle, double location[3]);
STATE_IMPORT void STATE_WINAPI STATE_light_get_location(DWORD light_handle, double location[3]);
// Sets the direction of the light. The direction of the light is relevant only if the
// light type is set to be directional.
// The direction is set by giving a point in the world towards which the light should be pointed
// See also STATE_light_set_direction()
// Example:
// double location[3]={0,0,10000}; //we make a sun so let put it up in the sky
// DWORD my_light=STATE_light_create("the sun", location);
// double point={0,0,0}; //The sun should be pointing down
// STATE_light_point_at(my_light, point);
// STATE_light_set_type_of_light(my_light, LIGHT_DEFAULT_POINTED_LIGHT); //by default the light is not directional.
// STATE_light_activate(my_light, LIGHT_SET); //let there be light ...
STATE_IMPORT void STATE_WINAPI STATE_light_point_at(DWORD light_handle, double point[3]);
//Sets the direction of the light. The direction of the light is relevant only if the
// light type is set to be directional.
// Note that a direction of {1,1,1} is exactly the same as {2,2,2}
// Example:
// double location[3]={0,0,0}
// DWORD my_light=STATE_light_create("my_light", location);
// double direction={1,1,0};
// STATE_light_set_direction(my_light, direction);
// STATE_light_set_type_of_light(my_light, LIGHT_DEFAULT_POINTED_LIGHT); //by default the light is not directional.
// STATE_light_activate(my_light, LIGHT_SET); //let there be light ...
STATE_IMPORT void STATE_WINAPI STATE_light_set_direction(DWORD light_handle, double direction[3]);
STATE_IMPORT void STATE_WINAPI STATE_light_get_direction(DWORD light_handle, double direction[3]);
//Set the color of the light. The default is {255,255,255} which is white.
STATE_IMPORT void STATE_WINAPI STATE_light_set_color(DWORD light_handle, BYTE color[3]);
STATE_IMPORT void STATE_WINAPI STATE_light_get_color(DWORD light_handle, BYTE color[3]);
//Remove light from the entity that is associated with the light source.
//Use STATE_light_set_entity_to_light() for choosing the entity that
//the light will be removed from.
//Note !! The function does not delete the light itself
//for deleting the light use STATE_light_delete()
//See also STATE_polygon_remove_light(), STATE_object_remove_light(), STATE_group_remove_light()
STATE_IMPORT void STATE_WINAPI STATE_light_remove_light(DWORD light_handle);
// Constant values for type_of_light (The values could be ored together e.g LIGHT_DIRECTIONAL | LIGHT_AMBIENT
#define LIGHT_DIRECTIONAL 1
#define LIGHT_EFFECTED_BY_DISTANCE_LINEAR 2
#define LIGHT_EFFECTED_BY_DISTANCE_SQUARE 4
#define LIGHT_AMBIENT 8
#define LIGHT_DIFFUSE 16
#define LIGHT_SPECULAR 32
//In most cases you will probably use one of the two combinations below
#define LIGHT_DEFAULT (LIGHT_EFFECTED_BY_DISTANCE_LINEAR | LIGHT_AMBIENT |LIGHT_DIFFUSE | LIGHT_SPECULAR)
#define LIGHT_DEFAULT_POINTED_LIGHT (LIGHT_DIRECTIONAL | LIGHT_EFFECTED_BY_DISTANCE_LINEAR | LIGHT_AMBIENT |LIGHT_DIFFUSE | LIGHT_SPECULAR)
#define LIGHT_DEFAULT_FAST (LIGHT_EFFECTED_BY_DISTANCE_LINEAR | LIGHT_AMBIENT |LIGHT_DIFFUSE )
#define LIGHT_DEFAULT_SUPER_FAST (LIGHT_EFFECTED_BY_DISTANCE_LINEAR | LIGHT_AMBIENT)
// The type of light can be combined from the following options
// LIGHT_DIRECTIONAL
// Denote that the light is directional. The direction could be set by STATE_light_get_direction()
// LIGHT_EFFECTED_BY_DISTANCE_LINEAR
// The light is reduced according to the distance from the light source location
// The reduction is linear
// This flag is included in the default light type though
// NOTE that in order to feel its effect you have first to define the light source
// maximum reach. Do that with STATE_light_set_distance_reach()
// LIGHT_EFFECTED_BY_DISTANCE_SQUARE
// The effect is that the light reduction is small near the light sourse and very strong
// near the end of the light reach area
// LIGHT_AMBIENT 8
// If this flag is not set then the ambient light component will not be used
// LIGHT_DIFFUSE 16
// If this flag is not set then the diffuse light component will not be used
// LIGHT_SPECULAR 32
// If this flag is not set then the ambient light component will not be used
//In most cases you will probably use one of the two combinations below
// LIGHT_DEFAULT (LIGHT_EFFECTED_BY_DISTANCE_LINEAR | LIGHT_AMBIENT |LIGHT_DIFFUSE | LIGHT_SPECULAR)
// LIGHT_DEFAULT_POINTED_LIGHT (LIGHT_DIRECTIONAL | LIGHT_EFFECTED_BY_DISTANCE_LINEAR | LIGHT_AMBIENT |LIGHT_DIFFUSE | LIGHT_SPECULAR)
//
// The default light type is LIGHT_DEFAULT
// Example A:
// //Setting a directional light
// STATE_light_set_type_of_light(my_light,LIGHT_DEFAULT_POINTED_LIGHT);
// Example B:
// //using LIGHT_EFFECTED_BY_DISTANCE_SQUARE
// STATE_light_set_type_of_light(my_light, LIGHT_DIRECTIONAL | LIGHT_EFFECTED_BY_DISTANCE_SQUARE | LIGHT_AMBIENT |LIGHT_DIFFUSE | LIGHT_SPECULAR);
STATE_IMPORT void STATE_WINAPI STATE_light_set_type_of_light(DWORD light_handle, int type_of_light);
STATE_IMPORT int STATE_WINAPI STATE_light_get_type_of_light(DWORD light_handle);
//Gives much more accurate lighting that takes into account obstacles between
// the lit surface and the source of light.
// The disadvantage is that lighting is much more slower when it is on.
// Dont use it for lighting every render.
// The default is NO (not activated)
// Example:
// STATE_light_set_ray_tracing(my_light, YES);
STATE_IMPORT void STATE_WINAPI STATE_light_set_ray_tracing(DWORD light_handle, int YES_or_NO);
STATE_IMPORT int STATE_WINAPI STATE_light_is_ray_tracing(DWORD light_handle);
//Set the distance that the light source can reach. The strength of the light is
// decreasing as it gets further away from the light source.
// A distance reach of -1 has a special meaning. It means an infinite reach.
// This is the default (infinite reach) so in order to see the effect of the distance
// one needs to call this function first with a value different than -1.
// Returns OK or VR_ERROR.
// Example:
// STATE_light_set_distance_reach(my_light, 100000);
STATE_IMPORT void STATE_WINAPI STATE_light_set_distance_reach(DWORD light_handle, double distance_reach);
STATE_IMPORT double STATE_WINAPI STATE_light_get_distance_reach(DWORD light_handle);
//Set the target object that will be lit by our light.
// entity_to_light could be a handle to a group an object or a polygon.
// The default entity is the whole world
// To make the function STATE_light_activate() you should change it to illuminate just the
// the entity that needs lighting.
// Examples:
// A)
// STATE_light_set_entity_to_light(my_light, polyogn_handle);
// In this case when the light will be activated it will only influence
// the given polygon.
// B)
// STATE_light_set_entity_to_light(my_light, NULL);
// NULL is a valid group_handle. It means the whole world
// In this case when the light will be activated it will influence
// the whole world.
// C)
// STATE_light_set_entity_to_light(my_light, chair_group_handle);
// When the light will be activated it will only light the chair
// This is a nice way to paint a specific item in the world.
//
// Returns OK or VR_ERROR
STATE_IMPORT int STATE_WINAPI STATE_light_set_entity_to_light(DWORD light_handle, DWORD entity_to_light);
STATE_IMPORT DWORD STATE_WINAPI STATE_light_get_entity_to_light(DWORD light_handle);
// Activates the light automatically before each render.
// The usage of this function is for dynamic lighting.
// If the light source moves every render (or other property of the light is changed)
// then the light has to be updated as well
// If however the light source properties do not change between every render then you
// should not use this method (it will waste CPU time).
// Another use for this method is for lighting dynamic objects.
// Again use it only if the dynamic object moves or rotates every render
// otherwise it is better to call STATE_light_activate() explicitly after
// each time that the object changes its position.
//
// Parameters:
//
// light_operation:
// Determines how the light is going to be activated every render.
// possible values are: LIGHT_ADD, LIGHT_SUBTRACT and LIGHT_SET
// Normally you would give LIGHT_SET. The other two options can be
// used for creating special effects like gradually darkening the world
// or a "get killed" effect when the screen turns into red (using a red colored light)
// The light_operation argument is only relevant if YES_or_NO==YES
//
// YES_or_NO:
// YES to enable. Give No to stop activating the light before each render. The default is NO
//
//
//
// Important:
// Dynamic lighting can be very slow if not done correctly. Note the following points:
// 1) Never light the whole world every render. Instead light only the moving objects that need to be re-lighted
// 2) Don't use ray tracing for dynamic lighting.
// See example "C" below.
//
//Examples:
// A)
// STATE_light_activate_before_each_render(my_light, YES, LIGHT_SET);
// B)
// //Disable dynamic lighting.
// STATE_light_activate_before_each_render(my_light, NO, 0); //doesnt matter what number is given (for the light operation)
//
// C) //Creating fast dynamic lighting.
// //In this example to light sources are used to illuminate to dynmaic (moving) objects.
//
// STATE_light_set_entity_to_light(light1, object1);
// STATE_light_set_entity_to_light(light2, object2);
//
// STATE_light_set_type_of_light(light1, LIGHT_DEFAULT_FAST);
// STATE_light_set_type_of_light(light1, LIGHT_DEFAULT_FAST);
// STATE_light_activate_before_each_render(light1, YES, LIGHT_SET);
// STATE_light_activate_before_each_render(light2, YES, LIGHT_SET);
STATE_IMPORT void STATE_WINAPI STATE_light_activate_before_each_render(DWORD light_handle, int YES_or_NO, int light_operation);
//The function also returns in the light_operation param the type of operation.
// Example:
// int light_operation;
// STATE_light_is_activated_before_render(my_light, &light_operation);
STATE_IMPORT int STATE_WINAPI STATE_light_is_activated_before_render(DWORD light_handle, int *light_operation);
// Each source of light is combined of three different channels, they are
// called Ambient, Diffuse and specular.
// Ambient light:
// Ambient light is light that doesn't come from any particular direction
// Objects illuminated by ambient light are evenly lit on all surfaces.
// For example if we create a room with a few light sources then even
// if all the light sources are turned off we will still have some light in the room.
// The ambient channel used to simulate this non-directional environment light
// Diffuse light:
// Diffuse light comes from a particular direction but is reflected evenly of the surface
// A good example of a diffuse light source is fluorescent lighting.
//
// Every source light is actually a combination of the three type of lights
// Feel free to play with these values till you get the desired results.
// The rule is that if it looks good then it is correct..
// The resulted lighting is a combination of the material characteristic and the type of light
// For controlling the material light properties see STATE_polygon_set_ambient(), STATE_group_set_ambient(), STATE_object_set_ambient()
//
// The given value should be a positive number or zero.
// The default is one. Common values are in the range of 0 to 10
// Examples:
// A)
// STATE_light_set_ambient(my_light, 1); //the default
// B)
// STATE_light_set_ambient(my_light, 2.8); //A very strong ambient lighting.
// C)
// STATE_light_set_ambient(my_light, 0); //Shutting off the ambient channel
// //It is better by not including the ambient light
// //flag when calling STATE_light_set_type_of_light()
//
// The same goes for the diffuse and specular lighting.
STATE_IMPORT void STATE_WINAPI STATE_light_set_ambient(DWORD light_handle, double value);
STATE_IMPORT void STATE_WINAPI STATE_light_set_diffuse(DWORD light_handle, double value);
STATE_IMPORT void STATE_WINAPI STATE_light_set_specular(DWORD light_handle, double value);
STATE_IMPORT double STATE_WINAPI STATE_light_get_ambient(DWORD light_handle);
STATE_IMPORT double STATE_WINAPI STATE_light_get_diffuse(DWORD light_handle);
STATE_IMPORT double STATE_WINAPI STATE_light_get_specular(DWORD light_handle);
// Use this function to control the size of the light spot that
// the specular lighting is creating.
// The default value is 1.
// The smaller the number is the bigger the light spot is.
// Values should be any positive number or zero.
// Normally values would be in the range of 0 to 10
STATE_IMPORT void STATE_WINAPI STATE_light_set_specular_shining(DWORD light_handle, double value);
STATE_IMPORT double STATE_WINAPI STATE_light_get_specular_shining(DWORD light_handle);
//Returns YES or NO. NO is returned if the given handle
//is not a handle of a light. YES is returned otherwise
STATE_IMPORT int STATE_WINAPI STATE_light_is_light(DWORD light_handle, char *function_asking);
//Deletes all the existing lights
STATE_IMPORT void STATE_WINAPI STATE_light_delete_all(void);
//Deletes the given light.
// Note that the object in the world will stay litted even after the light was deleted
// To remove the light effect from the objects use STATE_light_remove_light()
// or STATE_group_remove_light()
// Note not to use the handle after it the light was deleted
// Example:
// STATE_light_delete(my_light);
// my_light=NULL;
STATE_IMPORT void STATE_WINAPI STATE_light_delete(DWORD light_handle);
//Returns the light source name
// 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_light_get_name(DWORD light_handle);
STATE_IMPORT void STATE_WINAPI STATE_light_set_name(DWORD light_handle, char *name);
//Disables or enables a light source.
//This function is used before creating a light map (STATE_polygon_create_lightmap() )
//A light source that is disabled wont be included in the process of generating a lightmap
// See also STATE_light_is_disabled()
//
// Example:
// STATE_light_disable(my_light, YES);
STATE_IMPORT void STATE_WINAPI STATE_light_disable(DWORD light_handle, int YES_or_NO);
STATE_IMPORT int STATE_WINAPI STATE_light_is_disabled(DWORD light_handle);
//Calling this function with NO will omit the given light source when saving the world.
// The default is YES.
//Example: STATE_light_set_save_flag(my_light, NO);
STATE_IMPORT void STATE_WINAPI STATE_light_set_save_flag(DWORD light_handle, int YES_or_NO);
//--------------------------------------------------------//
//=========== T H E A N I M A T I O N A P I =========//
//--------------------------------------------------------//
// animation is a set of bitmaps that replaces itself according
// to a given time sequence.
// A polygon can have a regular bitmap or it can have an animation.
// The idea is that one can just give a list of bitmaps with time sequence
// and the engine deals with all the rest.
// Animations are very useful when used on a rotated polygons.
// You can then define animation sequences from 8 sides
// and the graphic engine sees that the right bitmap is
// shown each time.
// Each animation can include up to 8 different bitmap sequences
// This is used for representing a rotated polygon from 8 different sides.
// actually there are only 5 bitmaps sequences (the rest are figured automatically
// by the engine by mirroring some bitmaps)
// Here are the 5 constants that represent the 5 different list
#define BITMAP_LIST_FRONT 1 //a list of bitmaps representing the view from the front
#define BITMAP_LIST_FRONT_SIDED 2 //a list of bitmaps representing the view from the front-side (45 degrees) angle
#define BITMAP_LIST_SIDE 3 //a list of bitmaps representing the view from the side
#define BITMAP_LIST_BACK_SIDED 4 //a list of bitmaps representing the view from the back-side (135 degrees) angle
#define BITMAP_LIST_BACK 5 //a list of bitmaps representing the view from the back
//
// To understand animation better, just look at one of the sample worlds
// that contain an animation. Try playing with the list of bitmaps and the other params.
// Returns YES or NO.
// YES , if the given handle is an animation handle. NO if not.
// If it is not an animation 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_ANIMATION()
STATE_IMPORT int STATE_WINAPI STATE_animation_is_animation(DWORD animation_handle, char *function_asking);
// The given name should be in capital letters
// If the return value is 0 it means
// that there is no animation with the given name.
STATE_IMPORT DWORD STATE_WINAPI STATE_animation_get_handle(char *animation_name);
STATE_IMPORT DWORD STATE_WINAPI STATE_animation_get_first_animation(void);
STATE_IMPORT DWORD STATE_WINAPI STATE_animation_get_next(DWORD animation_handle);
//Creates an empty animation
//name: give any name you want.
// NOTE that if the name is already in use by another animation
// the function would automatically add a number to the end of the name
// After creating the animation use STATE_animation_add_bitmap() to add bitmaps
STATE_IMPORT DWORD STATE_WINAPI STATE_animation_create(char *name);
// bitmap_list: is one of the five constants: BITMAP_LIST_FRONT, BITMAP_LIST_FRONT_SIDED, BITMAP_LIST_SIDE, BITMAP_LIST_BACK_SIDED, BITMAP_LIST_BACK
// bitmap_handle: is the frame to add
// bitmap_position_index: 0 means put this frame as the first frame
// 1 means that we want to insert the bitmap after the first bitmap
// (our bitmap will become the second bitmap)
// n means that we want to insert the bitmap AFTER the n bitmap
// -1 has a special meaning it will put the frame as the last one
// If the given index is too big than the frame will be set as the last frame.
//
// The return value: returns the location of the added bitmap in the given list.
// usually this value is equal to the given "bitmap_position_index" argument (unless
// bitmap_position_index==-1 or is too big)
STATE_IMPORT int STATE_WINAPI STATE_animation_add_bitmap(DWORD animation_handle, int bitmap_list ,DWORD bitmap_handle, int bitmap_position_index);
// removes a bitmap from the given list
// bitmap_list: is one of the five constants: BITMAP_LIST_FRONT, BITMAP_LIST_FRONT_SIDED, BITMAP_LIST_SIDE, BITMAP_LIST_BACK_SIDED, BITMAP_LIST_BACK
// bitmap_position_index: 0 means remove the first frame
// 1 means remove the second frame etc ...
// -1 has a special meaning it will remove the frame at the end of the list
// If the given index is too big than the last frame will be removed.
//
STATE_IMPORT int STATE_WINAPI STATE_animation_remove_bitmap(DWORD animation_handle, int bitmap_list ,int bitmap_position_index);
// Returns a handle to the bitmap in the specified list and index
// bitmap_list: is one of the five constants: BITMAP_LIST_FRONT, BITMAP_LIST_FRONT_SIDED, BITMAP_LIST_SIDE, BITMAP_LIST_BACK_SIDED, BITMAP_LIST_BACK
// bitmap_position_index: 0 will return the first bitmap
// 1 the second bitmap etc ...
STATE_IMPORT DWORD STATE_WINAPI STATE_animation_get_bitmap(DWORD animation_handle, int bitmap_list ,int bitmap_position_index);
// time_for_each_frame: should be equal to STATE_animation_get_number_of_frames()
// before calling this function you should initialize the array ( DWORD time_for_each_frame[])
// the time is in hundreds of seconds.
// Returns OK or VR_ERROR
// Example:
// time_for_each_frame[0]= 100; //The first frame will be shown for one second