射击游戏

开发平台：

Visual C++

3DSTATE.H：源码内容

NOTE: to use it directly from the wld file, add _FALLxx to the
chase_type. for example CHASE_TRACK_AIRPLANE would become CHASE_TRACK_AIRPLANE_FALL17
17 here is the height above ground that we want to fall.
*/
// Calling this function will make the object fall down from
// its track till it reaches "height_above_ground" distance from the ground
// Here is an example for an ocasion that makes this function very useful:
// If we have a terrain and we want a runner to run on a square track on this terrain then using
// this function we can use a track with only 4 points (a square) that will be up in the air.
// The engine will automatically place our runner at the right spot on the terrain.
// 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.
// See also STATE_object_get_location_on_track_before_falling()
STATE_IMPORT void STATE_WINAPI STATE_object_set_falling_from_track(DWORD object_handle, double height_above_ground, int fall_through_dynamic_objects);
//Calling this function would cancel previous calls to STATE_object_set_falling_from_track()
//See also STATE_object_set_falling_from_track()
STATE_IMPORT void STATE_WINAPI STATE_object_unset_falling_from_track(DWORD object_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_object_set_falling_from_track() for more details
STATE_IMPORT void STATE_WINAPI STATE_object_get_falling_from_track_params(DWORD object_handle, int *set_flag, double *height_above_ground, int *fall_through_dynamic_objects);
//This function is relevant only when STATE_object_set_falling_from_track() is used.
// It is not a very important function though if you are using STATE_object_set_falling_from_track()
//you might want to take a look at it.
//Lets imagine that we have a world that has some mountains. Our object is a car that
//is following a square track in the air. We tell the engine by using STATE_object_set_falling_from_track()
//to drop the car from the air to the ground so that the car drive in a square path on the terrain.
//We can use this function to find out that the location of the object before the object was dropped.
//See also STATE_object_set_falling_from_track()
STATE_IMPORT void STATE_WINAPI STATE_object_get_location_on_track_before_falling(DWORD object_handle, double location[3]);
//Relevant only when CHASE_PHYSICS is used.
//Set the speed of the object.
// Example
// //Give the object speed of 10 in the positive direction of the Y axis
// STATE_object_set_speed(object, 0,10,0);
//
// See also STATE_object_set_speed_units()
//
STATE_IMPORT void STATE_WINAPI STATE_object_set_speed(DWORD object_handle, double speed[3]);
STATE_IMPORT void STATE_WINAPI STATE_object_get_speed(DWORD object_handle, double speed[3]);
//Returns the size of the speed.
//Using this function we can only retrieve the magnitude of the speed but not its direction.
//For example if the function returns 10, it means that the speed of the object is 10.
//Q: "speed of ten" to which direction ?
//A: To know the direction of the speed call STATE_object_get_speed()
//
STATE_IMPORT double STATE_WINAPI STATE_object_get_absolute_speed(DWORD object_handle);
//Relevant only when CHASE_PHYSICS or CHASE_TRACK is used.
//Set the size of the speed.
//
// Read the example below to learn how it all works.
//
// Example:
// STATE_object_set_speed(object, 0,10,0);
// speed_size=STATE_object_get_absolute_speed(object);
// //speed_size is now 10
//
// STATE_object_set_absolute_speed(object, 100);
//
// double speed[3];
// STATE_object_get_speed(object, speed);
// //speed is now { 0, 100, 0}
//
//
// Advanced:
// In physics speed is a vector it has a size and a direction
// Q: If the speed vector is 6,8,0 ( STATE_object_set_speed(object, 6,8,0) );
// what is the size of the speed (what will STATE_object_get_absolute_speed(object) return ?)
//
//
// A: Let calculate the vector size according to Pythagoras Theorem
// speed size= Square root of ( A*A+ B*B+ C*C ) = square root of ( 6*6 + 8*8 + 0*0) = Square root of (100) == 10
//
//
STATE_IMPORT void STATE_WINAPI STATE_object_set_absolute_speed(DWORD object_handle, double speed);
// 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_object_set_force(my_object,force);
//
// Note that this will only relevant when CHASE_PHYSICS is applyed
STATE_IMPORT void STATE_WINAPI STATE_object_set_force(DWORD object_handle, double force[3]);
STATE_IMPORT void STATE_WINAPI STATE_object_get_force(DWORD object_handle, double force[3]);
//Similar to STATE_object_setget_absolute_speed() only that it works on the size of the force vector
STATE_IMPORT double STATE_WINAPI STATE_object_get_absolute_force(DWORD object_handle);
STATE_IMPORT void STATE_WINAPI STATE_object_set_absolute_force(DWORD object_handle, double force_size);
//This function doesn't change the size of the speed but only changes the speed direction according to the given value
//Relevant only for CHASE_PHYSICS
//
// Why do we need this function
// ----------------------------
//
// Consider the following example: You use CHASE_PHYSICS for moving a car missile bullet or whatever.
// now you want to change the direction of the missile. If you call STATE_object_set_direction()
// or STATE_object_rotate_z() it will only change orientation of the car missile model.
// It is not going to change the direction in which it is heading. For example if your
// car turns in 90 degrees it will continue going in the same direction as before according to the car speed vector
// (only that after you turn it, it will look as if the car is sliding sideways)
// For these cases we actually want to do several things. To turn the car (shapewize) but
// also to turn the direction in which it is heading. We might also want to change the
// direction of the force (simulating the car engine). The car engine pushes the car
// forward in the direction of the car so if our object is a car or a missile we would like
// to also adjust the force direction according to the new direction. If the source of force
// is external (gravity force for example) then we would not want to change the direction of the force
// since gravity is not influenced by the car turning ...
//
// Example A:
//
// double direction[3];
// STATE_object_get_direction(obj, &direction[0], &direction[1], &direction[2]);
// //set the direction of movement to the direction of the object
// STATE_object_set_speed_direction(obj, direction);
//
// Example B:
//
// //STATE_object_set_speed_direction() code is equivalent to the following code
// STATE_object_set_speed_direction(DWORD object_handle, double direction[3])
// {
// double save_speed_size=STATE_object_get_absolute_speed(object_handle);
// STATE_object_set_speed(object_handle, direction);
// //restore speed size
// STATE_object_set_absolute_speed(object_handle, save_speed_size);
// }
//
//
STATE_IMPORT void STATE_WINAPI STATE_object_set_speed_direction(DWORD object_handle, double direction[3]);
//This function doesn't change the size of the force but only changes the force direction according to the given value
//Relevant only for CHASE_PHYSICS
//Similar to STATE_object_set_speed_direction() only that it works on the force.
//For more details see STATE_object_set_speed_direction()
STATE_IMPORT void STATE_WINAPI STATE_object_set_force_direction(DWORD object_handle, double direction[3]);
//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 will only relevant when CHASE_PHYSICS is applyed
STATE_IMPORT void STATE_WINAPI STATE_object_set_max_speed(DWORD object_handle, double value);
STATE_IMPORT double STATE_WINAPI STATE_object_get_max_speed(DWORD object_handle);
//Friction is a value smaller or equal to 1
// if friction==0 it means no friction
// if friction==1 it means infinite friction nothing can move
// if friction is smaller than 0, it act like pressing on the gas
// The exact calculation.
// Each render the absolute_speed is multiplied by (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 a number carefully.
// typical numbers can be 0.03 or -0.03 etc ...
STATE_IMPORT void STATE_WINAPI STATE_object_set_friction(DWORD object_handle, double value);
STATE_IMPORT double STATE_WINAPI STATE_object_get_friction(DWORD object_handle);
//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.
STATE_IMPORT void STATE_WINAPI STATE_object_set_elasticity(DWORD object_handle, double value);
STATE_IMPORT double STATE_WINAPI STATE_object_get_elasticity(DWORD object_handle);
// advance all the objects. If STATE_engine_advance_objects_automatically(YES) is called
// then this function will be called automatically each time we do render
// Note works only in viewer mode (viewer mode is the default mode)
STATE_IMPORT void STATE_WINAPI STATE_object_advance_all();
// Moves it according to the chase type.
// Note works only in viewer mode (viewer mode is the default mode)
STATE_IMPORT void STATE_WINAPI STATE_object_advance(DWORD object_handle);
//This function is probably useless for 99.9999% of our users.
//You will need it only if you choose to write your own version STATE_engine_render()
//The 3D_animation is updated automatically according to need each time that STATE_engine_render()
//is called and the given object is seen. If one doesn't call STATE_engine_render()
//(because one chooses to use his own renderer) then the 3D_animation frame is not updated.
// Only in this case you should call this function so that your external renderer can benefit from
// the 3D_animation API.
STATE_IMPORT void STATE_WINAPI STATE_object_update_3D_animation_frame(DWORD object_handle);
//When the engine moves dynamic objects according to their chase type it also monitor
//the distance that these object have passed. Calling this function will reset this counter.
//Please note that the counter is not updated when calling functions such as
//STATE_object_set_location() , STATE_object_move(). The counter is only updated when
//the object is automatically moved by the engine according to its chase type.
STATE_IMPORT void STATE_WINAPI STATE_object_reset_distance_counter(DWORD object_handle);
//Returns the distance that the given object has passed. For more details please see
//STATE_object_reset_distance_counter()
STATE_IMPORT double STATE_WINAPI STATE_object_get_distance_counter(DWORD object_handle);
// 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
STATE_IMPORT void STATE_WINAPI STATE_object_get_bounding_box(DWORD object_handle, double box[2][3]);
//Create a copy of a given object
//Returns a handle to the created object
//If an error occurred it will return NULL
// duplicate_polygons_flag can be YES or NO.
// if NO is given then the source and the new copy will
// use the same polygons. That means that if we will change the bitmap or the color
// of a polygon it will effect all the copies too.
// If the object is big then duplicating all its polygons can be time consuming,
// That's why we might prefer to set duplicate_polygons_flag to NO.
// Note also that if the polygons are not really duplicated then many
// functions that receive a polygon will fail.
// For example if we call STATE_polygon_get_location()
// and we send a polygon that belongs to a copy of an object.
// then since we didnt duplicate the object's polygons there is only
// one polygon for both objects so in this case the function will return
// the location of the polygon from the original object.
// The Same story is with functions like STATE_polygon_add_shadow_patch()
STATE_IMPORT DWORD STATE_WINAPI STATE_object_duplicate(DWORD object_handle, int duplicate_polygons_flag);
//Note that after doing delete you cant use the handle any more
//so good practice is to do the following:
// STATE_object_delete(obj_handle);
// obj_handle=NULL;
STATE_IMPORT void STATE_WINAPI STATE_object_delete(DWORD object_handle);
#define STATE_DELETE 1
#define STATE_DISABLE 2
// This function set a timer and an event that should happen after
// the time has elapsed.
// There only two events that could be used.
// STATE_DELETE and STATE_DISABLE.
// If STATE_DELETE is chosen then the object
// will be automatically deleted after the time has elapsed
// If STATE_DISABLE is chosen then the object
// will be automatically disabled after the time has elapsed
// The time is in milliseconds
// Setting the timer to 0 will cancel any going event for this object.
// Note that after doing delete you cant use the handle any more
// so good practice is to do the following:
// STATE_object_set_event(obj_handle,1000, STATE_DELETE);
// obj_handle=NULL;
//
// Arguments:
// object_handle: The object that should be associated with the event.
//
// time_in_milliseconds: How long till the event will take place
//
// event: STATE_DELETE or STATE_DISABLE. See remarks.
//
//
// examples:
// A)
// Setting the timer to two seconds
// STATE_object_set_event(obj_handle, 2000, STATE_DISABLE);
// B)
// Canceling the timer
// STATE_object_set_event(obj_handle, 0, any_number_will_do);
STATE_IMPORT void STATE_WINAPI STATE_object_set_event(DWORD object_handle, int time_in_milliseconds, int event);
//This is a very usefull function.
//The main useage of this function is to delete objects automatically after
// a 2D animation on a specific polygon has ended (explosion effect animation for example)
//Example:
//After shooting down a helicoter we would like to have an explosion
//to do that we do the following:
//1) Using WorldBuilderWebmaker we create an object that contains usually one polygon with explosionfire animation
//2) At the beginning of the program we disable this object so it is not seen
//3) When we need to create an explosion we do the following:
// - We duplicate the explosion effect object (using STATE_object_duplicate() )
// - We move the new copy to the location where we need the effect ( STATE_object_get_location() and STATE_object_set_location() ) make sure that the copy is enabled
// - And here comes our function. We set an event using STATE_object_set_event_on_animation_frame()
// to delete the object automatically once the animation is over.
// This function is similar to STATE_object_set_event() only that the event is triggered
// by an animation frame and not by time.
// When the animation on the given polygon will finish showing the given frame.
// The event will take place.
// Note that the given polygon must belong to the given object
// There only two events that could be used.
// STATE_DELETE and STATE_DISABLE.
// Example for usage: Lets say we have an explosion and now we have created
// an object for showing the smoke, the smoke will be an animation on a polygon.
// the animation will show smoke evaporating. using this function we can automatically delete
// the object once the animation is finished
// If animation_frame==-1 it has a special meaning, it means expire after the last frame.
// Note that after doing delete you cant use the handle any more
// so good practice is to do the following:
// STATE_object_set_event_on_animation_frame(obj_handle, polygon_handle, animation_frame, STATE_DELETE);
// obj_handle=NULL;
// Arguments:
// object_handle: The object that should be associated with the event.
//
// polygon_handle: A polygon of the object that has an animation
//
// animation_frame: The animation frame number that should trigger the event.
//
// event: STATE_DELETE or STATE_DISABLE. See remarks.
STATE_IMPORT void STATE_WINAPI STATE_object_set_event_on_animation_frame(DWORD object_handle, DWORD polygon_handle, int animation_frame, int event);
//Objects that are disabled are not drawn and are not
//taking CPU time (they also dont take part in collision detection).
STATE_IMPORT void STATE_WINAPI STATE_object_disable(DWORD object_handle);
//Enables the given object.
//See STATE_object_disable() and STATE_object_is_enabled()
STATE_IMPORT void STATE_WINAPI STATE_object_enable(DWORD object_handle);
//Returns YES or NO.
//Returns whether this object is enabled or disabled.
//Objects that are disabled are not drawn and are not
//taking CPU time (they also dont take part in collision detection).
//By default all objects are enabled.
//See also STATE_object_disable(), STATE_object_enable()
STATE_IMPORT int STATE_WINAPI STATE_object_is_enabled(DWORD object_handle);
#define UNITS_PER_HUNDREDTH_OF_A_SECOND 1
#define UNITS_PER_RENDER 2
// This function is only relevant for object that have their chase type set to
// CHASE_TRAKE or CHASE_TRACK_AIRPLANE or CHASE_PHYSICS (relevant for CHASE_PHYSICS
// only when collison detection for chase physics is turned off. See STATE_object_cancel_collision_test_for_chase_physics() for more details)
//
// When objects are set to go according to a specific track
// they have speed. We have two ways two work with the speed. The given speed could be render cycle related or
// time related. The default is according to time (UNITS_PER_HUNDREDTH_OF_A_SECOND).
// We recommend not to use the default and to call this function after loading the world with UNITS_PER_RENDER
// (example STATE_object_set_speed_units(UNITS_PER_RENDER) );
// If you want to make your world based on time you should use STATE_engine_get_computer_speed_factor() instead.
//
// The reason why we recommend not using UNITS_PER_HUNDREDTH_OF_A_SECOND is because
// when using UNITS_PER_HUNDREDTH_OF_A_SECOND the engine checks the Windows system clock every render
// in order to calculate the correct advancement that should be applied. The problem is that
// the Windows system clock might not be updated as frequently as FPS of the application.
// For example if there are 100 frames per second in your game and the system clock is updated
// only ten time a second, the result will be that the object will move only in every tenth of a second ...
// To solve this you should alaways work according to render cycles but in order to make your
// program run the same on ewvery computer you should use STATE_engine_get_computer_speed_factor()
// at the beginning of your program to determine the computer speed.
//
//
// Parameters:
//
//1- UNITS_PER_HUNDREDTH_OF_A_SECOND
// This is the default mode. The advantage of this mode is that
// objects will move at the same speed no matter what is the size of the world
// or the strength of the computer. On slower computers the objects will simply
// move in bigger steps thus make the movement less smooth.
// For example an object that has an absolute speed of 10 will
// move in a speed of 10 units per 1 hundredth of a second which means
// 1000 virtual units in a second.
//
//2-
// UNITS_PER_RENDER
// Each render the object is advance by the speed, notice that we will
// get a different speed for slow computers than on fast ones, though
// the steps that the object is doing each render will always be equal.
//
//
// The default is UNITS_PER_HUNDREDTH_OF_A_SECOND.
//
//
//
//
// Remarks:
// * The speed_units_system is always set for all the objects.
//
// Question: What is the length of one virtual unit ?
// Answer: This depends on your world. For example lets say that your world
// is just one big house. When you build this house in a 3D editor
// you can make the length of the house 1 million units or maybe just 100 units
// it is up to you. You decide what is the length of one unit inside your world.
// The engine doesn't care whether you have chosen to build your world so that one unit is
// equal to one meter, one centimeter or one inch.
//
STATE_IMPORT void STATE_WINAPI STATE_object_set_speed_units(int speed_units_system);
STATE_IMPORT int STATE_WINAPI STATE_object_get_speed_units(void);
//Returns a handle to a polygon that belongs to the object and has
//the given name. If polygons_name==NULL, it will return a random polygon from the object.
//If the return value is NULL, it means that no polygon with the given name belongs
//to the object.
STATE_IMPORT DWORD STATE_WINAPI STATE_object_get_polygon(DWORD object_handle, char *polygons_name);
//Returns YES if the given polygon is part of the given object
// NO otherwise.
STATE_IMPORT int STATE_WINAPI STATE_object_is_polygon_part_of(DWORD object_handle, DWORD polygon_handle);
STATE_IMPORT int STATE_WINAPI STATE_object_get_number_of_polygons(DWORD object_handle);
// polygons_array[] is an array of DWORD. This array will be filled with handles to
// all the polygons of the object.
// NOTE: you must allocate memory for the array before calling this function
// Example:
// int num_of_polys=STATE_object_get_number_of_polygons(obj_handle);
// // allocating mem using new or malloc etc ...
// DWORD *poly_array=(DWORD *)malloc(num_of_polys*sizeof(DWORD));
// STATE_object_get_all_polygons(obj_handle, poly_array);
STATE_IMPORT void STATE_WINAPI STATE_object_get_all_polygons(DWORD object_handle, DWORD polygons_array[]);
//Only relevent when using CHASE_PRECISE.
// It then detrmines the distance between the given object and the object that we chase.
// Arguments:
// object_handle: a handle to the object
// chase_distance: The distance that the given object should keep from the chased entity
STATE_IMPORT void STATE_WINAPI STATE_object_set_chase_distance(DWORD object_handle, double chase_distance);
//Only relevent when using CHASE_PRECISE.
// It returns the chase distance
//For more details see STATE_object_set_chase_distance()
STATE_IMPORT double STATE_WINAPI STATE_object_get_chase_distance(DWORD object_handle);
// Ignore this object for collision detection
// purposes. This means that when other object will call STATE_object_is_movement_possible()
// ( or STATE_engine_is_movement_possible() ) they would never get collision with
// this object. This function is useful for object like clouds, smoke, grass etc ...
// The default is that all the objects are collisional
STATE_IMPORT void STATE_WINAPI STATE_object_make_non_collisional(DWORD object_handle);
// This is the default.
STATE_IMPORT void STATE_WINAPI STATE_object_make_collisional(DWORD object_handle);
// Returns YES or NO
// For more details please see STATE_object_make_non_collisional() , STATE_object_make_collisional()
STATE_IMPORT int STATE_WINAPI STATE_object_is_collisional(DWORD object_handle);
// The following three functions are only relevant when the chase type of
// the object is CHASE_PHYSICS. For example if your object is a billiard ball
// then the engine will automatically calculate its direction when it
// hits the tables edges. If you cancel collision test then the engine would
// still calculate the speed and the friction etc ... but when the ball would hit
// the the table edge it will continue moving as if it was air.
// So why would you want to cancel the automatic collision detection ?
// You will want to cancel it when you do your own checking.
// Say for example that your object is a missile, that is planed to blow up
// when it is near the target. For this case you have to do your own test ...
// The default is: enabled
// Canceling the collision check also improves performaces so if you don't realy need the collision detection
// then we would recommend to cancel it.
//
// Important:
// Canceling the collision detection also changes the speed units to UNITS_PER_RENDER(this is a design bug in the engine that wasn't fix in order
// to maintain backwards compatibility). To make life easier we recommend of the following:
// A) After loading the world call STATE_object_set_speed_units(UNITS_PER_RENDER)
// B) In order to have your program run the same on all computers and have the same speed in all parts of your world
// do factor=STATE_engine_get_computer_speed_factor() in every render cycle. Factor all your objects spped like that
// new_speed=original_speed*factor;
//
// C) Cancel STATE_object_cancel_collision_test_for_chase_physics() for object that do not need a constant collision detection.
//
//
// Going according to our recommendation will give you the following benefits:
// 1) Your program will be faster.
// 2) The object will move smoother.
// 3) Your program will move at the same speed in all parts of your world
// and in all computers.
// 4) Calling STATE_object_cancel_collision_test_for_chase_physics() will have no undesired effect on the speed units.
//
//
// For more details about this please see STATE_object_set_speed_units()
//
//
//
STATE_IMPORT void STATE_WINAPI STATE_object_cancel_collision_test_for_chase_physics(DWORD object_handle);
//Enables the collision detection for the given object (relevant only for CHASE_PHYSICS)
//For more details please see STATE_object_cancel_collision_test_for_chase_physics()
STATE_IMPORT void STATE_WINAPI STATE_object_enable_collision_test_for_chase_physics(DWORD object_handle);
//Returns YES if collision detection test is performed (when the chase type is CHASE_PHYSICS)
// otherwise returns NO
STATE_IMPORT int STATE_WINAPI STATE_object_is_collision_test_for_chase_physics(DWORD object_handle);
//This function is only relevant when the chase_type is set to CHASE_PHYSICS.
//Use this function to make the object rotate around its center.
//rotation_space: choose between WORLD_SPACE and OBJECT_SPACE
//rotate_around_x_axis: The number of angles that the object will rotate
// around the X axis, each time STATE_engine_render() is called
// see also STATE_object_get_physics_rotation()
STATE_IMPORT void STATE_WINAPI STATE_object_set_physics_rotation(DWORD object_handle, int rotation_space ,double rotate_around_x_axis, double rotate_around_y_axis, double rotate_around_z_axis);
//This function is only relevant 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()
STATE_IMPORT int STATE_WINAPI STATE_object_get_physics_rotation(DWORD object_handle, double rotation_xyz[3]);
//Set the rotation center of the object. The default is the center of the object
STATE_IMPORT void STATE_WINAPI STATE_object_set_rotation_center(DWORD object_handle, double center[3]);
STATE_IMPORT void STATE_WINAPI STATE_object_get_rotation_center(DWORD object_handle, double center[3]);
//Determines whether the object will be moved automatically according to his chase type (The movement is done each time render is called)
// yes_no_flag should be YES or NO.
//The default is YES
STATE_IMPORT void STATE_WINAPI STATE_object_advance_automatically(DWORD object_handle, int yes_no_flag);
// The following functions are used for creating a hierarchy among objects and manipulating
// multiple number of objects together. For example let's say
// that we want to have a human model in our application. We should construct the model from
// several objects, the hands, the legs, the head etc ... Each object can be constructed from
// smaller objects, the hands for example could contain objects for the fingers.
// When we move the hand we will want the finger objects to move together with the
// hand object. We do it by setting the hand object as the father of each finger object.
// Later we can call STATE_object_move_including_sons(hand_object_handle) This will
// move the hand objects including all the fingers.
// Terminology: The usage of the word TREE
// Setting father-sons relations creates a structure similar to a family tree
//
// We can call this function with father_object==NULL
// this will mean that there is no father for this object.
// Returns OK or VR_ERROR.
// If the function fails it means that we tried to make a loop in hierarchy of the objects
// (for example setting object B as the father of object A and then setting object A as the father of B)
STATE_IMPORT int STATE_WINAPI STATE_object_set_father_object(DWORD object_handle, DWORD father_object);
STATE_IMPORT DWORD STATE_WINAPI STATE_object_get_father_object(DWORD object_handle);
// returns YES or NO.
// A NULL object_handle means the whole world
// Note that if objectA_handle==objectB_handle it will return YES
// If objectB_handle==NULL it will always return YES.
STATE_IMPORT int STATE_WINAPI STATE_object_is_objectA_included_in_objectB(DWORD objectA_handle, DWORD objectB_handle);
//Returns the first son of the given object. This function together with STATE_object_get_next_son()
// create an easy way for going over all the descendants (son, grandchild etc ...) of an object.
// for example:
// for(son=STATE_object_get_first_son(car_object); son!=NULL; son=STATE_object_get_next_son(son)) {
// //your code here ....
// }
// Note that if you just want to go over all the direct sons (no grandchildren ...) you should
// use STATE_object_get_first_direct_son() and STATE_object_get_next_direct_son()
STATE_IMPORT DWORD STATE_WINAPI STATE_object_get_first_son(DWORD object_handle);
STATE_IMPORT DWORD STATE_WINAPI STATE_object_get_next_son(DWORD object_handle, DWORD son_handle);
//Returns the first immediate son of the given object. This function together with STATE_object_get_next_direct_son()
// create an easy way for going over all the direct son (the close family) of an object.
// for example:
// for(son=STATE_object_get_first_direct_son(car_object); son!=NULL; son=STATE_object_get_next_direct_son(son)) {
// //your code here ....
// }
// Note that if you want to go over all the descendants (including grandchildren ...) you should
// use STATE_object_get_first_son() and STATE_object_get_next_son()
STATE_IMPORT DWORD STATE_WINAPI STATE_object_get_first_direct_son(DWORD object_handle);
STATE_IMPORT DWORD STATE_WINAPI STATE_object_get_next_direct_son(DWORD object_handle, DWORD son_handle);
// Advance the object (move relative) including all of its descendants
// space_flag could be WORLD_SPACE or OBJECT_SPACE or CAMERA_SPACE
// space_flag determines if the step is according to the objects
// coordinate system or the world coordinate system etc ...
// for example if space_flag==OBJECT_SPACE and step==(-1,0,0)
// This means that the object will advance forward (If it is a car than
// forward is the direction of the front window).
// Try both option and see what happens.
STATE_IMPORT void STATE_WINAPI STATE_object_move_including_sons(DWORD top_object_handle, int space_flag, double x, double y, double z);
// Calculates the center of the collection of objects defined by the given object and all of its descendants
// The result is saved in the center argument.
// ("tree" means the whole family tree of the object)
//Return value: returns the number of objects in the tree
STATE_IMPORT int STATE_WINAPI STATE_object_get_center_of_tree(DWORD top_object_handle, double center[3]);
#define CENTER_OF_TOP_OBJECT 1
#define CENTER_OF_TREE 2
#define CENTER_AS_GIVEN 3
// Move the object and all its descendants to a new location. center_flag can be one of the two: CENTER_OF_TOP_OBJECT or CENTER_OF_TREE
// If CENTER_OF_TREE is given then after calling this function the center of the tree will be in the given new location.
// If CENTER_OF_TOP_OBJECT then after calling this function the center of the top object will be in the given new location.
STATE_IMPORT void STATE_WINAPI STATE_object_set_location_of_tree(DWORD top_object_handle, double new_location[3], int center_flag);
//The object and all its descendants will be rotated according to the given arguments:
// degrees: The number of degrees to rotate.
// axis: this could be 1 or 2 or 3. Give one for rotating around the X axis. 2 for rotating around the Y axis and 3 for the Z axis
// space_flag: OBJECT_SPACE or WORLD_SPACE. If we have chosen for example to rotate around the X axis
// this flag determines whether it is the X axis of the object or the X axis of the world.
// center_flag: Could be one of the three, CENTER_OF_TOP_OBJECT, CENTER_OF_TREE, CENTER_AS_GIVEN.
// This flag determines the center of rotation.
// center: this argument is only relevant if the center_flag is CENTER_AS_GIVEN. In this case the point given by this
// argument will define the center of rotation.
STATE_IMPORT void STATE_WINAPI STATE_object_rotate_including_sons(DWORD top_object_handle, double degrees, int axis, int space_flag, int center_flag, double center[3]);
//Remove light from the given object.
//If the given object was lit using the STATE_light API then
//this function could be used to restore the object normal appearance
//See also STATE_group_remove_light(), STATE_polygon_remove_light(), STATE_light_remove_light()
STATE_IMPORT void STATE_WINAPI STATE_object_remove_light(DWORD object_handle);
//Sets the given bitmap to all the polygons of the object. The bitmap serves as a skin.
//Returns OK or VR_ERROR
STATE_IMPORT void STATE_WINAPI STATE_object_set_bitmap(DWORD object_handle, DWORD bitmap_handle);
//Creates an empty object and returns its handle.
//The object is automatically added to the engine
//Use STATE_object_add_polygon() to add polygons to the object.
STATE_IMPORT DWORD STATE_WINAPI STATE_object_create(char *name);
//Similar to STATE_engine_add_world() the difference is that
//the added world file is added as a dynamic object.
//This function is most useful for adding md2 file (quake files)
//If the world contains a 3d animation (all md2 files contain 3d animation)
//The 3D animation will automatically be added to the engine
//see the 3D_animation API and the 3D_sequence API
//Example:
// girl=STATE_object_create_from_file("people\girl.md2");
STATE_IMPORT DWORD STATE_WINAPI STATE_object_create_from_file(char *file_name);
//Returns the object 3D_animation or NULL if it doesnt have any 3D animation
// Example:
// 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();
// walk_sequence=STATE_3D_sequence_get_using_name(my_3danim,"walk");
// standing_sequence=STATE_3D_sequence_get_using_name(my_3danim,"stand");
// undressing_sequence=STATE_3D_sequence_get_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 ...
STATE_IMPORT DWORD STATE_WINAPI STATE_object_get_3D_animation(DWORD object_handle);
//Returns OK or VR_ERROR
//Used to attach a 3D animation to an object.
// animation3d_handle could also be NULL (to detach the current used animation)
//For more details please see STATE_object_get_3D_animation()
STATE_IMPORT int STATE_WINAPI STATE_object_set_3D_animation(DWORD object_handle, DWORD animation3d_handle);
//Replaces the current sequence with a new one.
// The engine will interpolate between the old sequence and the new one
// The duration of the interpolation process is controlled by transition_period
// transition_period is in mili seconds.
// If transition_period==0 then the engine wont do any interpolation between the old and the
// new sequences.
// Returns OK or VR_ERROR
// Note that usually this function is used
// together with STATE_3D_sequence_duplicate()
// This is because if two objects use the same 3D_sequence then
// changing the speed of the sequence (or other properties) will
// effect both objects
// Examples:
// A) //A simple example
// STATE_object_set_3D_sequence(my_object, walking_sequence, 100);
//
// B) //A simple example with full code
// DWORD obj=STATE_object_create_from_file("robot.md2");
// DWORD anim3d=STATE_object_get_3D_animation(obj);
// //Every md2 file might have different sequence names depending on the animated character
// //to know the names of the sequences you have to go through all of them using STATE_3D_sequence_get_first() and get next mechanism (and of course STATE_3D_sequence_get_name)
// DWORD walking_sequence=STATE_3D_sequence_get_using_name("walk");
// STATE_object_set_3D_sequence(my_object, walking_sequence, 100);
//
// C) //How to do it when a multiple number of objects might use the same 3D sequence
// //Normally you will do it like in this sample
// DWORD robot1=STATE_object_create_from_file("robot.md2");
// DWORD anim3d=STATE_object_get_3D_animation(robot1);
// //Every md2 file might have different sequence names depending on the animated character
// //to know the names of the sequences you have to go through all of them using STATE_3D_sequence_get_first() and get next mechanism (and of course STATE_3D_sequence_get_name)
// DWORD walking_sequence=STATE_3D_sequence_get_using_name("walk");
// robot1_walk=STATE_3D_sequence_duplicate(walking_sequence, "robot1_walk");
// STATE_object_set_3D_sequence(robot1, robot1_walk, 100);
// //Note ! now that this object has its own sequence then changing the sequence speed wont effect
// //other objects which use the same sequence
STATE_IMPORT int STATE_WINAPI STATE_object_set_3D_sequence(DWORD object_handle, DWORD sequence3d_handle, int transition_period);
STATE_IMPORT DWORD STATE_WINAPI STATE_object_get_3D_sequence(DWORD object_handle);
//new_sequence3d_handle is the handle to the sequence that we want to play when the current sequence
//reaches its last frame.
// arguments:
// transition_period
// The engine is going to interpolate between the old and the new animation and thus create a smooth animation
// The duration of this transition period is given by the argument transition_period
// If this value is 0 then the switch to the new sequence will happen immediately
// transition_period is in mili seconds.
STATE_IMPORT void STATE_WINAPI STATE_object_replace_3D_sequence_when_finished(DWORD object_handle, DWORD new_sequence3d_handle, int transition_period);
//Scale the object (in object space).
//Example:
// double scale[3]={1,2,3}; //make it twice as wide and triple tall
// STATE_object_set_scale(my_object, scale);
STATE_IMPORT void STATE_WINAPI STATE_object_set_scale(DWORD object_handle, double scale[3]);
//Returns the scaling factor. The default is 1,1,1
// After calling this function
// scale[0] will hold the X scaling factor
// scale[1] will hold the Y scaling factor
// scale[2] will hold the Z scaling factor
// Example:
// double scale[3];
// STATE_object_get_scale(my_object,scale);
STATE_IMPORT void STATE_WINAPI STATE_object_get_scale(DWORD object_handle, double scale[3]);
//Returns the handle to the group that represent this object.
STATE_IMPORT DWORD STATE_WINAPI STATE_object_get_group_handle(DWORD object_handle);
//Calls STATE_polygon_set_light() for all the polygons in the object
//For more details see STATE_polygon_set_light()
STATE_IMPORT void STATE_WINAPI STATE_object_set_light(DWORD object_handle, BYTE rgb[3]);
//Adds a polygon to the object.
//Please note that the points of the polygon should be in OBJECT_SPACE
//(for example 0,0,0 is the center of the object and not the center of the world)
// Adding polygons that are defined in the object space is very easy because we don't
//have to take care whether the object has moved or turned around. For example
//if we have an airplane that is flying then in object space the coordinates
//of the points that define a polygon on the airplane wing will always stay the same
//no matter how many maneuvers the airplane did.
//One can use the function STATE_object_convert_point_to_object_space()
//If the points of the polygon are only known in world space.
//Returns OK or VR_ERROR
//If the return value is VR_ERROR it is probably because that the polygon is not valid.
//(for example it has only two points. 4 points not on the same plane. not convex,
//bitmap coordination are not valid etc ...see the STATE.log to catch the error)
STATE_IMPORT int STATE_WINAPI STATE_object_add_polygon(DWORD object_handle, DWORD polygon_handle);
//The same as STATE_polygon_create_lightmap() only that it creates lightmaps bitmaps for all
//polygons of the given object.
//Returns the number of bitmaps that were created and assigned to the object.
//For more details see STATE_polygon_create_lightmap()
STATE_IMPORT int STATE_WINAPI STATE_object_create_lightmap(DWORD object_handle, int max_bm_side, int min_lightmap_size, double sample_rate, int force_ray_tracing, int bitmap_number);
//Deletes a polygon from the object. Returns OK or VR_ERROR
STATE_IMPORT int STATE_WINAPI STATE_object_delete_polygon(DWORD object_handle, DWORD polygon_handle);
// Drops the object down till it hits the floorground.
//
// Return Value.
// Returns a handle to the polygon bellow.
//
// Parameters:
// object_handle: the object to be dropped.
//
// fall_through_dynamic_objects: Could be set to YES or NO.
// Notice the following code sample:
// Lets assume that we have a terrain world and we want to move our character forward
//
// STATE_object_move(my_object, OBJECT_SPACE, -10, 0, 0); //Move the object 10 units forward. If we are in front
// //of a mountain slope, it could get us into the mountain.
// STATE_object_move(my_object, WORLD_SPACE, 0, 0, 10000000); //Move the object up in the air so if we have penetrated the mountain
// //with our previous move then now we are above the mountain
// STATE_object_drop_down(my_object, NO); //Drop the player nicely on the ground
//
// The code above will work very nicely till there is a helicopter or a bird that
// flys above our player. If so, our player will drop down on a the helicopter instead
// of on the ground. In this case of this game we better call with fall_through_dynamic_objects==YES
//
//
//
// Example
//
// DWORD floor_polygon=STATE_object_drop_down(my_object);
// if(floor_polygon==NULL)
// error_message("The object has nothing below !!!);
//
// Remarks:
// See also STATE_object_drop_down_fast();
//
STATE_IMPORT DWORD STATE_WINAPI STATE_object_drop_down(DWORD object_handle, int fall_through_dynamic_objects);
// Drops the object down till it hits the floorground.
//
// Return Value.
// Returns a handle to the polygon bellow.
//
// Parameters:
// object_handle: the object to be dropped.
//
// object_height: The height of our object.
// You can calculate the height of the object using the object bounding box
// Give a value bigger than the object height if you want the object to be above the ground
// Give a value smaller than the object height if you want the object to be sunken in the ground
// Calculating the height should be a one time operation that should be done at the beginning of the program.
// The fact that this function doesnt have to do calculate the height on its own
// make this function a little bit faster then STATE_object_drop_down(). Except that the functions are the same
//
// fall_through_dynamic_objects: Could be set to YES or NO.
// Notice the following code sample:
// Lets assume that we have a terrain world and we want to move our character forward
//
// STATE_object_move(my_object, OBJECT_SPACE, -10, 0, 0); //Move the object 10 units forward. If we are in front
// //of a mountain slope, it could get us into the mountain.
// STATE_object_move(my_object, WORLD_SPACE, 0, 0, 10000000); //Move the object up in the air so if we have penetrated the mountain
// //with our previous move then now we are above the mountain
// STATE_object_drop_down(my_object, NO); //Drop the player nicely on the ground
//
// The code above will work very nicely till there is a helicopter or a bird that
// flies above our player. If so, our player will drop down on a the helicopter instead
// of on the ground. In this case of this game we better call with fall_through_dynamic_objects==YES
//
//
//Example:
// //calculate the height:
// //This is a one time operation that should be done at the beginning of the program.
// //The fact that this function doesnt have to do
// double box[2][3];
// STATE_object_get_bounding_box(my_object, box);
// double height= box[1][2]-box[0][2];
// STATE_object_drop_down_fast(my_object, height, NO);
//
STATE_IMPORT DWORD STATE_WINAPI STATE_object_drop_down_fast(DWORD object_handle, double object_height, int fall_through_dynamic_objects);
// Use this function to turn offon 3D animation interpolation.
// This function is only relevant to objects that are using 3D animation such as md2 or anim3d
// (see the STATE_3D_animation_ API). By default the STATE engine interpolates
// between frames of the current used 3D sequence. Interpolation means that if for example
// we have in one frame a monster creature standing and in the very next frame we have the monster
// is dismantled into bits and pieces (explosion effect), the engine will be able to create all the frames
// in between. This ability of the engine makes it possible to create very smooth 3D animations
// with only using some very few frames. Usually you will never want to turn this feature off.
// The only reasons for turning 3D interpolation off will be:
// 1) If you specially need to have a jerky looking animation
// 2) You might save some CPU cycles if 3D animation interpolation is turned off
//
// Parameters:
//
// object_handle: The handle of the object
//
// ON_or_OFF: OFF to switches 3D animation interpolation OFF. ON, to enable it again.
// The default is ON.
//
//Example:
// //Turn off 3D animation interpolation.
// DWORD my_object=STATE_object_create_from_file("monster.md2");
// STATE_object_set_3D_animation_interpolation_mode(my_object, OFF);
STATE_IMPORT void STATE_WINAPI STATE_object_set_3D_animation_interpolation_mode(DWORD object_handle, int ON_or_OFF);
//One can use this function to associate your own data structure to an object.
//Whether one decides to use this function or not depends on one's programming style.
//The obvious alternative for using this function is to have your own structure or class
//for each object and that one of the fields in your class would be the object_handle through which
//you can access the STATE functions.
//
// Parameters:
// object_handle:
// a handle to an object
//
// my_own_data:
// A pointer to a class or structure or even a function. This pointer can points
// to whatever you want it to point. The Engine doesnt do anything with this pointer
// it simply save it for you so you can call STATE_object_get_my_own_data() to retrieve it.
//
// Example:
//
// typedef struct object_data
// {
// int health;
// int power;
// int number_of_times_that_got_hit;
// double height;
// int weapon_type;
// //And anyother data you might need in your program
// } object_data;
//
// object_data obj_data; //or use new(), malloc() or whatever ...
// STATE_object_attach_my_own_data(my_object, &obj_data);
STATE_IMPORT void STATE_WINAPI STATE_object_attach_my_own_data(DWORD object_handle, void *my_own_data);
STATE_IMPORT void *STATE_WINAPI STATE_object_get_my_own_data(DWORD object_handle);
// Copies the speed, the location and the force of one object to another.
// This function is useful when we want to change the shape of an object with another object
// The function also makes sure that object with chase type CHASE_PHYSICS will have a smooth transition
// from one to another.
//
// Remarks
// The function could be used also when the chase type is not CHASE_PHISYCS or when there is no chase type at all
// though the function real need is when CHASE_PHYSICS is used.
// When CHASE_PHYSICS is used one should use this function instead of writing one own version (for coping the location and speed)
// because this function also synchronize the timing for maximum smooth transition.
//
// Example:
//
// //lets say we have an airplane that was hit by a missile and now we want to
// //replace the airplane shape with a shape of an airplane which is a bit burnt and has a hole.
//
// STATE_object_disable(good_airplane_handle); //Disable the intact airplane
// STATE_object_enabled(burnt_airplane_handle); //Enable the damaged airplane. From now on, this object will be used.
// STATE_object_copy_physics(burnt_airplane_handle, good_airplane_handle); //set the location and other properties of
// //damaged jet so that we will have a smooth transition between the two.
//
STATE_IMPORT void STATE_WINAPI STATE_object_copy_physics(DWORD dest_object, DWORD src_object);
//--------------------------------------------------------//
//=========== T H E P O L Y G O N A P I =============//
//--------------------------------------------------------//
// This API deals with polygons. Creating, setting the color or the bitmap etc ...
// Returns YES or NO.
// YES , if the given handle is a polygon handle. NO if not.
// If it is not a polygon 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_POLYGON()
STATE_IMPORT int STATE_WINAPI STATE_polygon_is_polygon(DWORD polygon_handle, char *function_asking);
// returns the handle to the polygon
STATE_IMPORT DWORD STATE_WINAPI STATE_polygon_get_handle_using_name(char *polygon_name);
// returns OK or VR_ERROR
STATE_IMPORT int STATE_WINAPI STATE_polygon_set_name(DWORD poly_handle, char *polygon_name);
// Returns the name of the polygon.
// 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_polygon_get_name(DWORD poly_handle);
STATE_IMPORT DWORD STATE_WINAPI STATE_polygon_get_handle_using_id_num(int poly_id_num);
STATE_IMPORT DWORD STATE_WINAPI STATE_polygon_get_first_polygon(void);
STATE_IMPORT DWORD STATE_WINAPI STATE_polygon_get_next(DWORD polygon_handle);
//Note that the normal is the three first values .N==( plane[0], plane[1], plane[2])
STATE_IMPORT void STATE_WINAPI STATE_polygon_get_plane(DWORD polygon_handle, double plane[4]);
// if red==-1 && green == -1 && blue== -1
// the current color will be used
STATE_IMPORT void STATE_WINAPI STATE_polygon_set_color_fill(DWORD polygon_handle, int red, int green, int blue);
// returns OK or VR_ERROR
STATE_IMPORT int STATE_WINAPI STATE_polygon_set_bitmap_fill(DWORD polygon_handle, DWORD bitmap_handle);
// If the return is NULL then no bitmap is associated with the polygon.
// The return value is the name of the bitmap without the extention.
// The bitmap's name is the name+path relative to the path given in STATE_engine_load_world()
// If a bitmap exists in the world file but the engine couldnt find the bitmap file than it will still return its name.
// This is used when loading a world from the Internet, at first only the world is loaded
// and then we start streaming the bitmaps. We use this function to get the bitmap file name.
//If you want to check if the bitmap is in used then use STATE_polygon_get_bitmap_handle()
// Examples:
//
// A)
// char *name;
// name=STATE_polygon_get_bitmap_name();
//
// B)
// The following example is relevent only when the world is saved without the SAVE_FLAT_BITMAP_PATH (not very common ...)
// In this case the bitmaps are not nessecerally in one directory.
// the executable path is d:projectstest
// the bitmap path == d:projectstestbitmapsanimaldogboxer.bmp
// the bitmap path given in STATE_engine_load_world() == "bitmaps"
// the return string here will be == "animaldogboxer"
//
// See also STATE_bitmap_get_name()
STATE_IMPORT char * STATE_WINAPI STATE_polygon_get_bitmap_name(DWORD polygon_handle);
// if the return is NULL then no bitmap is associated with the polygon
STATE_IMPORT DWORD STATE_WINAPI STATE_polygon_get_bitmap_handle(DWORD polygon_handle);
STATE_IMPORT void STATE_WINAPI STATE_polygon_get_color(DWORD polygon_handle, int *red, int *green, int *blue);
// returns OK or VR_ERROR if no transparent color is set for this polygon
STATE_IMPORT int STATE_WINAPI STATE_polygon_get_transparent_rgb(DWORD polygon_handle, int *red, int *green, int *blue);
// Returns -1 if we transparent is not used for the given polygon
// else return the index to the transparent color, usually it
// will be 0 which means that the most used color is the transparent color
// if the return value is 1 it means that the second most popular
// color is the transparent color etc ...
STATE_IMPORT int STATE_WINAPI STATE_polygon_get_transparent_index(DWORD polygon_handle);
// returns OK or VR_ERROR
// if transparent_index== -1 transparent will be canceled for this polygon
// Obsolete. Use STATE_bitmap_load() instead
//STATE_IMPORT int STATE_WINAPI STATE_polygon_set_transparent_index(DWORD polygon_handle, int transparent_index);
// returns OK or VR_ERROR
// if red and green and blue all equal to -1 transparent will be canceled for this polygon
// Obsolete. Use Morift_bitmap_load() instead
//STATE_IMPORT int STATE_WINAPI STATE_polygon_set_transparent_rgb(DWORD polygon_handle, int red, int green, int blue);
// returns YES or NO
// a rotated polygon will always turn itself to
// face the direction of the camera.
// this technique is used to make 2D images look like a 3D object
// usually we will use this technique for trees animals etc ...
// Objects that look the same from all direction are excellent candidates
// (for example a tree or a vase)
STATE_IMPORT int STATE_WINAPI STATE_polygon_is_rotated(DWORD polygon_handle);
// For more information see STATE_polygon_is_rotated()
// Parameters:
// yes_no_flag: should be YES for setting the given polygon as rotated
// NO to set it as a normal polygon
STATE_IMPORT void STATE_WINAPI STATE_polygon_set_rotated(DWORD polygon_handle, int yes_no_flag);
// The given value should describe the percentage of fog increment per 1000 units
// Give 0 to cancel fog for a particular polygon.
// This might come handy when working with translucent polygons.
// Returns OK, VR_ERROR
STATE_IMPORT int STATE_WINAPI STATE_polygon_set_light_diminution(DWORD polygon_handle, double value);
STATE_IMPORT double STATE_WINAPI STATE_polygon_get_light_diminution(DWORD polygon_handle);
// return YES or NO
// light intensity values are used with bitmap filled polygons
// instead of using several bitmaps in different
// brightness levels we can simply use this function
// we can also specify a different brightness value for each point
// of the polygon (using the POINT API functions)
// In that case the rendering of the polygon will be slower
// if all the points have the same brightness the rendering time
// is not damaged.
// relevant only for bitmap fill
// see also:
// STATE_polygon_get_brightness()
// STATE_polygon_set_brightness()
// STATE_point_get_brightness()
// STATE_point_set_brightness()
STATE_IMPORT int STATE_WINAPI STATE_polygon_is_uniform_brightness(DWORD polygon_handle);
// If the brightness is not the same for all the
// points we return the average.
// relevant only for bitmap fill
// see also:
// STATE_polygon_set_brightness()
// STATE_polygon_is_uniform_brightness()
// STATE_point_get_brightness()
// STATE_point_set_brightness()
STATE_IMPORT double STATE_WINAPI STATE_polygon_get_brightness(DWORD polygon_handle);
// returns OK, VR_ERROR
// 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_is_uniform_brightness()
// STATE_point_get_brightness()
// STATE_point_set_brightness()
STATE_IMPORT int STATE_WINAPI STATE_polygon_set_brightness(DWORD polygon_handle, int value);
STATE_IMPORT int STATE_WINAPI STATE_polygon_get_num_of_points(DWORD polygon_handle);
// deletes the polygon
// Note an attempt to use a handle after it was
// deleted will crash the program.
// Deleting a polygon will automatically deletes all his points and all its patches polygons.
// Note that you can also call this function to delete a patch polygon
// see also STATE_polygon_delete_patches();
STATE_IMPORT void STATE_WINAPI STATE_polygon_delete(DWORD polygon_handle);
// Note an attempt to use a handle after it was
// deleted will crash the program.
STATE_IMPORT void STATE_WINAPI STATE_polygon_delete_point(DWORD polygon_handle, DWORD point_handle);
// Checks if all the points are on the same plane
// if there are less than three points etc ... The function also sets internal info
// returns YES if the polygon is valid or NO (if not valid).
// If the answer is NO it is usually because the polygon is
// not convex or because the points are not on the same
// plane or the bitmap cords are not good or the light intensity cords are not good.
// When doing STATE_engine_add_polygon() this check is done
// automatically so it is impossible to add a bad polygon
STATE_IMPORT int STATE_WINAPI STATE_polygon_is_valid(DWORD polygon_handle);
//Return YES if the polygon is convex.
// returns NO if the polygon is concave
// all polygons added to the world must be convex
STATE_IMPORT int STATE_WINAPI STATE_polygon_is_convex(DWORD polygon_handle);
//Return YES or NO
// check that all points are on the same plane
// Will also return NO if there are less than 3 points in the poly, or if
// two of the three first points are identical.
STATE_IMPORT int STATE_WINAPI STATE_polygon_are_all_points_on_one_plane(DWORD polygon_handle);
//Returns YES or NO
STATE_IMPORT int STATE_WINAPI STATE_polygon_are_bitmap_x_cords_ok(DWORD polygon_handle);
//Returns YES or NO
STATE_IMPORT int STATE_WINAPI STATE_polygon_are_bitmap_y_cords_ok(DWORD polygon_handle);
//Returns YES or NO
STATE_IMPORT int STATE_WINAPI STATE_polygon_are_brightness_cords_ok(DWORD polygon_handle);
// returns the number of points that are on the same line
// 0 means no redundant points
STATE_IMPORT int STATE_WINAPI STATE_polygon_count_redundant_points(DWORD polygon_handle);
// remove points that are on the same line
// return the number of points that where removed
// a negative number means that an error occurred
STATE_IMPORT int STATE_WINAPI STATE_polygon_remove_redundant_points(DWORD polygon_handle);
// Returns a handle to the first point of a polygon
// use STATE_point_get_next_point() the get the next points
//
//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_polygon_get_first_point(DWORD polygon_handle);
// Creates a new empty polygon.
// Returns a handle to the new polygons
// or NULL if an error occurred.
// Note ! the polygon won't be seen or checked for errors
// till you do STATE_engine_add_polygon()
// Use STATE_polygon_add_point() to add points to the created polygon.
STATE_IMPORT DWORD STATE_WINAPI STATE_polygon_create(void);
// returns a handle to the new point
// or NULL if an error occurred.
// Add the point as the last point (add to tail)
STATE_IMPORT DWORD STATE_WINAPI STATE_polygon_add_point(DWORD polygon_handle, double xyz_bmX_bmY_brightness[6]);
// returns a handle to the new point
// or NULL if an error occurred.
// Add the point as the first point (add to head)
STATE_IMPORT DWORD STATE_WINAPI STATE_polygon_add_point_to_head(DWORD polygon_handle, double xyz_bmX_bmY_brightness[6]);
STATE_IMPORT void STATE_WINAPI STATE_polygon_rotate_bitmap(DWORD polygon_handle);
// how many rotation should be done in comparison to the original bitmap
STATE_IMPORT void STATE_WINAPI STATE_polygon_set_bitmap_rotation(DWORD polygon_handle, int rotation_count) ;
STATE_IMPORT void STATE_WINAPI STATE_polygon_mirror_horizontal_bitmap(DWORD polygon_handle);
STATE_IMPORT void STATE_WINAPI STATE_polygon_mirror_vertical_bitmap(DWORD polygon_handle);
// the rotation is around the center of the polygon
STATE_IMPORT void STATE_WINAPI STATE_polygon_rotate_x(DWORD polygon_handle, double degrees);
STATE_IMPORT void STATE_WINAPI STATE_polygon_rotate_y(DWORD polygon_handle, double degrees);
STATE_IMPORT void STATE_WINAPI STATE_polygon_rotate_z(DWORD polygon_handle, double degrees);
// for general rotation operations.
STATE_IMPORT void STATE_WINAPI STATE_polygon_rotate(DWORD polygon_handle, double trans_mat[3][3]);
STATE_IMPORT void STATE_WINAPI STATE_polygon_move(DWORD polygon_handle, double step[3]);
// the location is according to the center of the polygon
STATE_IMPORT void STATE_WINAPI STATE_polygon_set_location(DWORD polygon_handle, double location[3]);
// The location is according to the center of the polygon
// Note that if this polygon belongs to a dynamic object then you
// have to add the location of the dynamic object to the result.
// (This note is not relevant in editor mode)
// The location is according to the center of the polygon
// A note regarding the function STATE_object_duplicate() :
// Note that this function will fail if the polygon belongs to an object
// that was duplicated with the "dont_duplicate_polygons_flag"
// In this case we will get the location of the polygon on the original copy of the object
STATE_IMPORT void STATE_WINAPI STATE_polygon_get_location(DWORD polygon_handle, double location[3]);
// the scaling is according to the center of the polygon
STATE_IMPORT void STATE_WINAPI STATE_polygon_scale(DWORD polygon_handle, double scale_x, double scale_y, double scale_z);
// reverse the direction in which the polygon is visible
// remember that all the polygons have only one side which is visible.
STATE_IMPORT void STATE_WINAPI STATE_polygon_flip_visible_side(DWORD polygon_handle);
// tries to join the two polygons to one polygon.
// if it is possible it deletes the two polygons create a new
// one and return the handle to the new one
// on failure returns NULL.
STATE_IMPORT DWORD STATE_WINAPI STATE_polygon_join(DWORD polygon1_handle, DWORD polygon2_handle);
// The bitmap cords of the target poly are set so they match the source_poly bitmap cords
// If the polys are adjacent calling this function would make the move from
// polygon to another smooth on the connection. If the polys are not on the same
// plane then the connection line will be smooth but the bitmap density would be
// different.
// returns OK unless an error occurred (like a polygon with 2 points was received etc ...)
// returns VR_ERROR in case of error.
STATE_IMPORT int STATE_WINAPI STATE_polygon_match_bitmap_cords(DWORD source_polygon_handle, DWORD target_polygon_handle);
// Duplicates a polygon.
// returns a handle to the new created polygon.
// Note that in order to see the new polygon it should be added to the engine
// by calling STATE_engine_add_polygon() or STATE_object_add_polygon()
STATE_IMPORT DWORD STATE_WINAPI STATE_polygon_duplicate(DWORD polygon_handle);
// The given polygon is rotated so it will be parallel to
// "reference_polygon_handle" (the second argument);
// return OK or VR_ERROR.
STATE_IMPORT int STATE_WINAPI STATE_polygon_rotate_to_match_polygon(DWORD polygon_handle, DWORD reference_polygon_handle);
// The given polygon 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_polygon_move_to_match_point(DWORD polygon_handle, DWORD point_belongs_to_polygon, DWORD point_to_match);
// Gets a point in space. returns the handle to a vertex of the polygon that
// is the closest to the given point.
// One important use of this function is in conjunction with STATE_engine_2D_point_to_3D()
// When calling STATE_engine_2D_point_to_3D() keep the 3d point and call this
// function with the 3d point.
STATE_IMPORT DWORD STATE_WINAPI STATE_polygon_get_closest_point(DWORD polygon_handle, double p3d[3]);
//This function is not very important.
// Gets a point in space. returns the handle to a vertex of the polygon that
// is the furthest away from the given point.
//See also STATE_polygon_move_to_match_point()
STATE_IMPORT DWORD STATE_WINAPI STATE_polygon_get_furthest_point(DWORD polygon_handle, double p3d[3]);
//---------------------------------//
//-Polygons operations with groups-//
//---------------------------------//
// set the group that this polygon belongs to.
STATE_IMPORT void STATE_WINAPI STATE_polygon_set_group(DWORD polygon_handle, DWORD group_handle);
STATE_IMPORT DWORD STATE_WINAPI STATE_polygon_get_group(DWORD polygon_handle);
// returns YES or NO
STATE_IMPORT int STATE_WINAPI STATE_polygon_is_in_group(DWORD polygon_handle, 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 contradict.
//
// See also STATE_group_set_orientation()
STATE_IMPORT void STATE_WINAPI STATE_polygon_set_orientation(DWORD polygon_handle, int orientation_value);
//see also STATE_group_get_orientation()
STATE_IMPORT int STATE_WINAPI STATE_polygon_get_orientation(DWORD polygon_handle);
//Note that this function works only if the polygon is convex.
//The function doesn't check whether the point is on the polygon plane
// to check if the point is on the plane first use STATE_polygon_are_all_points_on_one_plane()
//
// actually this STATE_polygon_is_point_inside_polygon determines whether a point is inside the infinity cylindertube shape that
// the given polygon is its profile.
// So we can also call STATE_polygon_is_point_inside_polygon() with a point that is not
// on the plane the function
//Returns YES or NO.
STATE_IMPORT int STATE_WINAPI STATE_polygon_is_point_inside_polygon(DWORD polygon_handle, double pnt[3]);
//The function doesn't check whether the point is on the polygon plane
//Use this function if the polygon could also be concave, otherwise use STATE_polygon_is_point_inside_polygon()
//Returns YES or NO.
STATE_IMPORT int STATE_WINAPI STATE_polygon_is_point_inside_polygon_concave(DWORD polygon_handle, double pnt[3]);
STATE_IMPORT int STATE_WINAPI STATE_polygon_set_animation(DWORD polygon_handle, DWORD animation_handle);
STATE_IMPORT DWORD STATE_WINAPI STATE_polygon_get_animation(DWORD polygon_handle);
// Assuming that there is an animation associated with the given polygon
// then this function makes it possible to jump to a specific frame.
// If animation_frame==-1 then the last frame will be chosen.
// If the given animation_frame is bigger than the last frame then the last frame will be chosen.
// The first frame is numbered as 0
STATE_IMPORT void STATE_WINAPI STATE_polygon_set_animation_frame(DWORD polygon_handle, int animation_frame);
STATE_IMPORT int STATE_WINAPI STATE_polygon_get_animation_frame(DWORD polygon_handle);
// calculate the center and returns in parameter "center"
// A note regarding the function STATE_object_duplicate() :
// Note that this function will fail if the polygon belongs to an object
// that was duplicated with the "dont_duplicate_polygons_flag"
// In this case we will get the location of the polygon on the original copy of the object
STATE_IMPORT void STATE_WINAPI STATE_polygon_get_center(DWORD polygon_handle, double center[3]);
//YES or NO. If NO the polygon wont be saved when doing STATE_engine_save() with the SAVE_RELEASE flag
//One can also use this function for simply marking polygons with boolean value,
//since the function is very fast and has no effect beside when doing save
STATE_IMPORT void STATE_WINAPI STATE_polygon_set_release_save_flag(DWORD polygon_handle, int YES_or_NO);
STATE_IMPORT int STATE_WINAPI STATE_polygon_get_release_save_flag(DWORD polygon_handle);
//Polygons that are disabled are not drawn and are not
//taking CPU time (they also dont take part in collision detection) .
//Note the following cases:
// The polygon is not visible and does not take part in collision detection ==> use STATE_polygon_disable
// The polygon is visible and does not take part in collision detection ==> use STATE_polygon_make_non_collisional()
// The polygon is not visible takes part in collision detection ==> name the polygon $$TRANSPARENT that will tell the engine not to draw it
//
// Naming the polygon $$TRANSPARENT (not seen but participate in collision detection) is useful in order to restrict the player
// from getting out of certain areas. They act like transparent walls.
STATE_IMPORT void STATE_WINAPI STATE_polygon_disable(DWORD polygon_handle);
STATE_IMPORT void STATE_WINAPI STATE_polygon_enable(DWORD polygon_handle);
//returns YES if the polygon is disabled. NO if it is enabled
STATE_IMPORT int STATE_WINAPI STATE_polygon_is_disabled(DWORD polygon_handle);
// Ignore this polygon for collision detection
// purposes. This means that when STATE_object_is_movement_possible()
// will be called ( or STATE_engine_is_movement_possible() ) they would never get collision with
// this polygon. This function is useful for polygons representing clouds, smoke, curtains ,grass etc ...
// The default is that all the polygons are collisional
// see also STATE_polygon_make_collisional() ,STATE_polygon_is_collisional(), STATE_polygon_disable()
//Note the following cases:
// The polygon is not visible and does not take part in collision detection ==> use STATE_polygon_disable
// The polygon is visible and does not take part in collision detection ==> use STATE_object_make_non_collisional()
// The polygon is not visible takes part in collision detection ==> name the polygon $$TRANSPARENT that will tell the engine not to draw it
//
// Naming the polygon $$TRANSPARENT (not seen but participate in collision detection) is useful in order to restrict the player
// from getting out of certain areas. They act like transparent walls.
STATE_IMPORT void STATE_WINAPI STATE_polygon_make_non_collisional(DWORD polygon_handle);
//This is the default. see also STATE_polygon_make_non_collisional() and STATE_polygon_is_collisional()
STATE_IMPORT void STATE_WINAPI STATE_polygon_make_collisional(DWORD polygon_handle);
//Return YES or NO. see also STATE_polygon_make_collisional() and STATE_polygon_make_non_collisional()
STATE_IMPORT int STATE_WINAPI STATE_polygon_is_collisional(DWORD polygon_handle);
// ------------------------------------------------------
// | Constants for glass types used for blending |
// | with the function STATE_polygon_set_translucent() |
// | Note that these constants are only relevant when |
// | hardware rendering is used. |
// ------------------------------------------------------
//
// One doesnt really have to read the explanations (though it
// is quite simple) , you can test the different options and
// pick the one you like.
//The default. The polygon will be 100% opaque.
#define DISABLE_BLENDING 0
// Filter glass can be used to block rgb channels
// like when looking through a cellophane paper
// For example if the color of the polygon is (red==255,0,0)
// Then when looking through this polygon the whole world will
// be painted with red. The blending formula for DARK_FILTER_GLASS
// is NEW_PIXEL=SRC*DEST (SRC is the pixel of our polygon. DEST
// is the pixel in the background and NEW_PIXEL is final result.
// Example: We have a room with a window. We look outside through
// the window. Lets examine the rendering process
// when rendering a specific pixel of the window.
// The computer takes a pixel from the window
// (for example 0,0,64 == dark blue == 0.25, 0.25, 0.25 in [0-1] rgb scale)
// and another pixel from outside the room that is exactly on the
// line connecting between the eye (camera) and the pixel of the window
// for example lets say that this line hits a cloud so our second pixel
// is gray (rgb== 128,128,128 == 0.5, 0.5, 0.5 in [0-1] rgb scale) now
// lets calculate the final pixel that we will have on the window
// according to the function NEW_PIXEL=SRC*DEST == (0,0, 0.25)*(0.5, 0.5, 0.5)
// == 0*0.5, 0*0.5, 0.25*0.5= (0,0,0.125) == (0,0,32 in [0-255] scale)
// == very dark blue.
// This blending formula is called DARK_... because the result pixel is
// darker or equal to the src pixel
#define DARK_FILTER_GLASS 0x31
//The blending formula for FILTER_GLASS is NEW_PIXEL=2*SRC*DEST
//This formula is usually better than DARK_FILTER_GLASS since
// the result pixel is less dark.
#define FILTER_GLASS 0x33
//The blending formula for OPAQUE_FILTER_GLASS is
// NEW_PIXEL=SRC*SRC + SRC*DEST. It is similar to FILTER_GLASS
// It is called OPAQUE_... since it is a little bit more opaque than
// FILTER_GLASS
#define OPAQUE_FILTER_GLASS 0x43
// Create the effect of normal glass. Here is what happens when looking through
// this glass: The light from bright objects easily penetrates the window
// while the light from darker objects is reflected from the glass (in this case
// you get to see the bitmap of the window and not what is outside ...)
// Using this type of glass you can control the level of translucency
// Bright pixel in the bitmap will be totally opaque while dark pixel will
// blend with the background. Make a bright bitmap if you want your window
// to be more opaque. Make a dark bitmap if you want it to be more transparent.
// Note this side effect, the view outside the window will always look brighter
// than what it really is. This effect simulate our eye behavior. When we sit
// in a dark room and we open a window we are overwhelmed by the light. Once we get outside,
// we get used to it and it doesnt seem to be as bright as we felt before
// Here is the blending formula for this window:
// NEW_PIXEL= SRC(1-DEST)+DEST. Note that if DEST=(R,B,G) than 1-DEST is (1-R, 1-G,1-B)
// when working in [0-1] scale.
#define NORMAL_GLASS 0x52
// It is the only glass
// that make a real blending without decreasing or increasing the light.
// It is also the only one who gives a total control on the level of
// transparency, from being total opaque to being total transparent.
// Bright pixel in the bitmap will be totally opaque while dark pixel will
// be transparent. Make a bright bitmap if you want your window
// to be more opaque. Make a dark window if you want it to be more transparent.
// The blending formula for this glass is
// NEW_PIXEL=SRC*SRC+DEST*(1-SRC)
#define CONTROL_GLASS 0x44
// Has the side effect of making the outside look brighter
// It is called transparent because the glass is a little bit
// more transparent than the other types.
// A dark bitmap (for the window) will make a very transparent glass
// a bright bitmap will make a bright blend between the window and the outside.
// Here is the blending formula:
// NEW_PIXEL=DEST+SRC*DEST
#define BRIGHT_TRANSPARENT_GLASS 0x32
//Similar to BRIGHT_TRANSPARENT_GLASS only a little bit less transparent
//Here is the blending formula:
// NEW_PIXEL=DEST+SRC*SRC
#define BRIGHT_TRANSLUCENT_GLASS 0x42
//similar to BRIGHT_TRANSLUCENT_GLASS only that
//the glass is more opaque. This glass can also be used to block color channels
//like with the filter modes (FILTER_GLASS).
//Here is the blending formula:
// NEW_PIXEL=SRC+SRC*DEST
#define BRIGHT_OPAQUE_GLASS 0x23
//This glass is special. It has the
//simple blending formula NEW_PIXEL=SRC+DEST
//Usually this type of blending is used for
//simulating light because of its additive characteristic
//If used as a window glass then we should use a dark bitmap
//otherwise we will have a very bright saturated window.
#define LIGHT_SOURCE_GLASS 0x22
//This glass creates a special effect. When looking
//through it, it inverts the world that we see.
//The blending formula is:
//NEW_PIXEL=SRC*(1-DEST).Note that if DEST=(R,B,G) than 1-DEST is (1-R, 1-G,1-B)
// when working in [0-1] scale.
#define INVERSE_GLASS 0x51
//Makes the polygon transparent as if it was glass
//Above are the different types of glass.
//call this function with DISABLE_BLENDING to
//change to normal rendering (100% opaque)
//The default is DISABLE_BLENDING
//Example: STATE_polygon_set_translucent(my_poly,NORMAL_GLASS);
// Note that it will only work with hardware rendering
// ( see STATE_3D_card_check_hardware_support())
STATE_IMPORT void STATE_WINAPI STATE_polygon_set_translucent(DWORD polygon_handle, BYTE glass_type);
//see STATE_polygon_set_translucent()
STATE_IMPORT BYTE STATE_WINAPI STATE_polygon_get_translucent(DWORD polygon_handle);
//Patches are polygons that are always in front of their father polygon
//For example if we shoot a wall in a game then we can add a patch polygon to
//make it look like a whole in the wall. Another example will be in a racing car
//game when we want to leave wheel marks on the road. We can easily do that
//by using STATE_engine_is_movement_possible() to get the polygon of the road
//that is under the wheel and then to use this function to paste a wheel mark
//on the road polygon.
// The first parameter to this function is the polygon that we want to paste the
// patch on it.
// The second argument is the patch it self.
// Note that it is your responsibility to set the location and bitmaps of
// the patch polygon.
// See also STATE_polygon_add_patch_easy() which saves you all the calculations.
STATE_IMPORT void STATE_WINAPI STATE_polygon_add_patch(DWORD polygon_handle, DWORD patch_polygon_handle);
// For explanation about patches see STATE_polygon_add_patch()
// This function is similar to STATE_polygon_add_patch()
// only that it is much easier to use. For example if we shoot a wall in a game then we can add a patch polygon to
// make it look like a whole in the wall. With this function you just
// have to specify the point on the wall where you want the patch to be put,
// the size of the patch and the bitmap that it will be using.
// The point and the polygon where your bullet hit the wall can be easily obtained
// by using STATE_engine_is_movement_possible()
//
// Parameters
// ----------
// father_polygon
// The polygon on which we want to place a patch
// NOTE: the pach will inherit the father_polygon properties
// so if the father polygon is translucent the patch will also be translucent
// if the father_polygon is rotated so will be the patch
// If you want the patch to have different properties you
// have to set them after the patch was created. For example:
// double direction[3]={0,0,1};
// int rgb[3]={255,0,0} ; //red
// DWORD patch=STATE_polygon_add_patch_easy(father_polygon, center, radius, direction, bitmap_handle,rgb);
// STATE_polygon_set_rotated(patch,NO); //making sure that the patch wont be rotated
// STATE_polygon_set_translucent(patch,DISABLE_BLENDING); //making sure that the patch wont be translucent
// A note regarding the function STATE_object_duplicate():
// This function will fail if the father_polygon belongs to an object
// that was duplicated with the "dont_duplicate_polygons_flag" set
//
// center
// A point on the father polygon that will be the center of the patch
// radius
// Used to specify the size of the patch. Note that the patches are actually
// square polygons. This parameter gives the distance between the center of the square and one of the
// square edges.
// direction
// The direction of the patch. For example, if we have a car racing game
// and we want the wheels to leave marks then we would like the wheel mark
// to be in the direction of the car. So in this case we would give the direction
// of the car as the direction of the patch. If you dont know, or if you dont care
// about the direction you can give direction={0,0,0}.
// texture
// The texture that is used to paint the patch.
// If NULL then the rgb color will be used
// rgb
// Used only when texture==NULL. Specifies the color
// rgb[0] is red. rgb[1] is green and rgb[2] is blue .
//
//
// Return value: returns a handle to the created patch polygon.
//
// See also STATE_engine_set_patches_offset()
STATE_IMPORT DWORD STATE_WINAPI STATE_polygon_add_patch_easy(DWORD father_polygon, double center[3], double radius, double direction[3], DWORD bitmap_handle,int rgb[3]);
#define ALL_PATCHES 1 //delete all the patches of a given polygon
#define REGULAR_PATCHES 2 //delete all the regular patches of a given polygon (patches that were mad using the function STATE_polygon_add_patch() and STATE_polygon_add_patch_easy() )
#define SHADOW_PATCHES 4 //delete all the shadow patches of a given polygon (patches that were created in the process of creating shade
//Delete patches of the given polygon. If the given polygon is a patch in itself
//then the function will return immediately (without deleting)
// Example A:
// //Deleting all the patches of a given polygon
// STATE_polygon_delete_patches(my_polygon, ALL_PATCHES);
//
// Example B:
// //Deleting all the patches that were created using the functions
// //STATE_polygon_add_patch() and STATE_polygon_add_patch_easy()
// STATE_polygon_delete_patches(my_polygon, REGULAR_PATCHES);
//
// Example C:
// Delete all the patches that were created using the function STATE_engine_create_shadow()
// STATE_polygon_delete_patches(my_polygon, SHADOW_PATCHES);
//
// Example D:
// Delete patches that were created using the function STATE_engine_create_shadow() with a serial_number==220
// STATE_polygon_delete_patches(my_polygon, 220);
//
// See also: STATE_engine_create_shadow(), STATE_polygon_add_patch() ,STATE_polygon_add_patch_easy()
// STATE_group_delete_patches()
STATE_IMPORT void STATE_WINAPI STATE_polygon_delete_patches(DWORD polygon_handle, int type_of_patches_to_delete_or_serial_number);
//Returns the patch type or serial number. This function can be used to decide whether a certain polygon
//is a patch or not. If the polygon is not a patch then 0 is returned.
//to learn more about the different types of patches please see
// STATE_polygon_delete_patches(), STATE_engine_create_shadow(), STATE_polygon_add_patch() ,STATE_polygon_add_patch_easy()
// STATE_group_delete_patches()
STATE_IMPORT int STATE_WINAPI STATE_polygon_get_patch_type(DWORD polygon_handle);
//Checks whether the given line segment intersect the given polygon.
//Returns YES if there is an intersection. Returns NO otherwise.
//The line segment is define by two points: double P1[3] and double P2[3]
//If there is an intersection the intersection point is saved within double intersection[3]
// Wont work in VIEWER_MODE with polygons that belong to a dynamic object (See the STATE_object API)
STATE_IMPORT int STATE_WINAPI STATE_polygon_check_intersection_with_line_segment(DWORD polygon_handle, double P1[3], double P2[3], double intersection[3]);
//Checks whether the two given polygons intersect each other.
//Returns YES if there is an intersection. Returns NO otherwise.
//If there is an intersection the intersection point is saved within double intersection[3]
// Wont work in VIEWER_MODE with polygons that belong to a dynamic object (See the STATE_object API)
STATE_IMPORT int STATE_WINAPI STATE_polygon_check_intersection_with_another_polygon(DWORD polygon1, DWORD polygon2, double intersection[3]);
//----------------------------------------------------------------------------
//=== Polygon function that has to do with light. See also the Light API =====
//----------------------------------------------------------------------------
// There are four properties that influence how light effects polygons, these are ambient, diffuse specular and specular_shining.
// Every defined light that is activated (see the light API) is combined internally of
// three types of lights (ambient, diffuse and specular)
// By using these functions one can modify how a surface react with each type of light.
// Different materials react differently For example
// materials that tend to reflect light better (metals, marble etc ...)
// will have higher values of the specular property.
// The value given should be a positive number
// The default value is 86. Typical values are between 0 to 500
// Feel free to play with those values till you get the desired effect
// Here is some more info about the light properties
// Specular:
// The specular property defines for a surface how close it is to an ideal reflecting surface
// A mirror for example is a perfect reflecting surface.
// Different materials have different values .For example
// materials that tend to reflect light better (metals, marble etc ...)
// will have higher values of the specular property.
// Diffuse:
// Diffuse light comes from a particular direction but is reflected evenly of the surface
// Dull surfaces like solid matte plastic exhibit what is called diffuse reflection
// Ambient:
// Ambient light is light that doesn't come from any particular direction
// Objects illuminated by ambient light are evenly lit on all surfaces.
STATE_IMPORT void STATE_WINAPI STATE_polygon_set_ambient(DWORD polygon_handle, int value);
STATE_IMPORT int STATE_WINAPI STATE_polygon_get_ambient(DWORD polygon_handle);
STATE_IMPORT void STATE_WINAPI STATE_polygon_set_diffuse(DWORD polygon_handle, int value);
STATE_IMPORT int STATE_WINAPI STATE_polygon_get_diffuse(DWORD polygon_handle);
STATE_IMPORT void STATE_WINAPI STATE_polygon_set_specular(DWORD polygon_handle, int value);
STATE_IMPORT int STATE_WINAPI STATE_polygon_get_specular(DWORD polygon_handle);
// The shining property influences only the specular light
// The default is 1. Typical values are between 0 to 10
// The lower this value is the bigger the light spot created from the specular lighting will be.
STATE_IMPORT void STATE_WINAPI STATE_polygon_set_specular_shining(DWORD polygon_handle, BYTE value);
// The shining property influences only the specular light
// The default is 1. Typical values are between 0 to 10
// The lower this value is the bigger the light spot created from the specular lighting will be.
STATE_IMPORT BYTE STATE_WINAPI STATE_polygon_get_specular_shining(DWORD polygon_handle);
//Remove light from the polygon.
//If the given polygon was lit using the STATE_light API then
//this function could be used to restore the polygon normal appearance
//See also STATE_object_remove_light(), STATE_group_remove_light(), STATE_light_remove_light()
STATE_IMPORT void STATE_WINAPI STATE_polygon_remove_light(DWORD polygon_handle);
//Exactly like STATE_group_wrap_a_bitmap_fixed(0 but just for one polygon.
// See also STATE_group_wrap_a_bitmap()
// returns OK or VR_ERROR
STATE_IMPORT int STATE_WINAPI STATE_polygon_wrap_a_bitmap_fixed(DWORD polygon_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]);
//A very useful function.
//Set the light values of each vertex directly
//Actually this function merely calls STATE_point_set_rgb() for all the points of the given polygon
//Here are some uses of this function:
//1) make a polygon brighter or darker or to alter its color.
//2) Set different colors to each vertex (If a texture is used for this polygon
// the the color of the vertixes will be mixed with the color of the texture
// (a multiply mix so one can never make the texture brighter than the origibal)
//3) The light API actually creates the illusion of light by manipulating the color of the
// vertixes. One can use this function (together with STATE_point_set_rgb) to create an alternative light mechanism
// though usually it is easier to use the light API to set the vertices color.
//4) Create nice effects such as fading the polygon to the color of the background.
//
//Note that this function will only work in hardware rendering mode
//See also STATE_point_set_rgb()
STATE_IMPORT void STATE_WINAPI STATE_polygon_set_light(DWORD polygon_handle, BYTE rgb[3]);
//Creates two new polygons. The handles to the newly created polygons are returned
//through the arguments back_piece and front_piece.
//The polygon is divided into two pieces according to the given split_plane.
//You can use the function STATE_math_points_to_plane() to create the splitting plane
// Note that the two created polygons are not added to the engine
// so they wont be rendered until STATE_engine_add_polygon() is called
//Returns OK or VR_ERROR.
//If the given plane does not intersect the given polygon then the function will return NULL
//for both back_part and front_part. In this case the return value will be OK.
//
//
// Example:
//
// DWORD back_part=NULL;
// DWORD front_part=NULL;
// int rc=STATE_polygon_split(my_poly, splitting_plane, &back_part, &front_part);
//
STATE_IMPORT int STATE_WINAPI STATE_polygon_split(DWORD polygon_to_split, double split_plane[4], DWORD *front_piece, DWORD *back_piece);
// Sets the second bitmap of the polygon. When rendering, the second
// bitmap will be blended into the first one.
// When the first bitmap is not used (for example after calling
// STATE_polygon_set_color_fill() ) then also the second bitmap wont be used.
// See also STATE_polygon_create_lightmap()
// returns OK or VR_ERROR
STATE_IMPORT int STATE_WINAPI STATE_polygon_set_second_bitmap(DWORD polygon_handle, DWORD texture_handle);
STATE_IMPORT DWORD STATE_WINAPI STATE_polygon_get_second_bitmap(DWORD polygon_handle);
// General information about lightmaps and their use in the STATE Engine.
//--------------------------------------------------------------------------
// Lightmaps are very important for achieving more
// realistic graphics quality. Lightmaps are regular bitmaps. The reason they are called
// lightmaps is because they contain information regarding shadowed and lit areas.
// Although they are mainly used for creating light and shadows, they can also be used for other special effects.
// Since version 4.2 polygons can have two bitmaps. Usually the second bitmap is a lightmap.
// When rendering using the 3D card the two bitmaps will be blended into one.
// The blending is done by multiplying one bitmap with another according to this formula:
// For each pixel new_rgb=rgb1*rgb2/255;
// For example rgb1=(255, 10, 10) == bright red.
// rgb2=(128, 128,128) ==grey.
// new_rgb= (128, 5,5) == half of rgb1 == a darker red.
//
// Note that the new_rgb will never be brighter than rgb1 or rgb2.
// Thats why in many games the environment tend to be quite dark.
//
// Here is an example of common use of lightmaps:
// Assume we have a small brick bitmap tiled on the floor in our virtual world.
// This usually looks unrealistic since in the real world we will have many light
// and shadow effects. Light from a lamp, from the door, from an openedd window etc ...
// In the real world we should also have many shadows. If there are chairs in the room
// They should create some shadow on the floor and so on.
// The idea is that we take an additional bitmap that will include information
// about the lit and shadowed area. This bitmap is not tiled. The combination
// of the lightmap bitmap and our tiled brick bitmap will give a realistic
// image of the floor.
//
// Q: How do we create this second bitmap that has all the information about
// the lit and shadowed area ?
//
// A: It is very simple we just call STATE_polygon_create_lightmap() (there are function for object and group as well)
// and the bitmap is created automatically according the light source that
// are defined in the world. (To define light sources use the STATE_light_ API
//
//
// Q: Whats the big deal about having a second texture, after all if we have
// the lightmap bitmap and the original bitmap then we can merge them together
// using any 2D painting program (Photo Shop, Corel Photo Paint etc ...)
// Then we can take the result bitmap and use it for our polygon. This way
// there is no need for two bitmaps for our polygon.
//
// A: If we have a big wall or floor then in order to get a good graphics quality
// We will have to use a huge bitmap (1024x1024 as an example == 2MB in 16bit color depth). If we use a tiled bitmap and a lightmap
// as a second bitmap we could do quite well with two bitmaps of 128x128 that is
// 2x 128x128 == 2x16K==32K (64K in 16bit color depth). This way we consume just 1/32
// of bitmaps memory. In software rendering the second bitmap is not blended
// with the first bitmap so creating one big bitmaps as suggested in the question
// is the only way to go.
//
//
// Q: Are lightmaps supported in software rendering ?
//
// A: The second bitmap is ignored when doing software rendering. Even though
// the functions for creating lightmaps are very useful in software rendering.
// As mentioned in the previous question, functions like STATE_polygon_create_lightmap()
// can be used in off-line to create the lightmap then by using a 2D painting program
// the lightmap can be blended with the texture.
//
//
// Q: There are three methods for creating light.
// 1) Using the functions: STATE_engine_create_shadow() and STATE_engine_create_dynamic_shadow()
// 2) Through the Light API (STATE_light_ ....)
// 3) Using lightmaps.
// The qustions is: what difference is there between the three and when should each of one be used.
// Another question is why have three methods, that is confusing. It would be preferred to have
// just one set of functions.
//
// A: Creating nice lights and shadows is one of the important steps in creating
// realistic 3D environments. In real-time application not only we want it to look good
// we also it to run in high frames per second rate.There is no one lighting method that
// can give best results in all the cases. Thats why there are several methods.
// Generally speaking we could give the following guidelines:
// Use lightmaps when: Use lightmaps for big polygons such as floors and walls.
// Lightmaps are only good for static light (light that comes from an open window
// but not that comes from a moving flashlight).
// If lightmaps are used only where they have a strong impact (big polygons)
// then the effect on the FPS is small (about 10%).
//
// Use STATE_engine_create_dynamic_shadow() to create dynamic lights (and shadow)
// for example to make a light spot from a moving flashlight. This function could be very fast
// if it is used correctly. For example projecting the flashlight glass lid (one polygon)
// on top of the six polygons of the room will be very fast (Order 1X6=6). On the other hand
// projecting.
//
// Use STATE_light API functions for both dynamic and static lights.
// The light API will give good results only when a high polygon count object is lit.
// The reason is that light is only calculated for the vertices (Goraud shading)
// so using it to light floors or walls will only result a darker or a brighter floor
// but it wont create nice light spots and shadows. We suggest that lightmaps will be used
// for big polygons like walls and floors and the light API will be used to
// illuminate objects with many small polygons.
//
// In games like Unreal small lightmaps are used for the walls and floors and when the
// room is lit (someone is shooting a rocket for example) then they use Goraud
// shading (The light API) to increase the overall brightness.
//
//
// Q: What are the light sources that are used to build a lightmap.
//
// A: Each pixel in the light map is calculated according to the total intensity all the light sources
// at that point. The light sources are the same light sources that are used by
// STATE light API (STATE_light_create()
//
//
// STATE_object_create_lightmap()
//=================================
// Creates a bitmap that includes lighting information for that polygon.
// The light that reaches the polygon is calculated according to the light
// sources in the world (STATE_light_create() ...) and the geometry of the world
// (different objects can block the light from some source lights.
//
// Arguments:
// sample_rate: Determines the size of the lightmap according to the size of the polygon in the 3D world.
// For example, if we have a floor in the size of 1000x1000 virtual units and the sample rate
// argument is set to 100 then every pixel in the light map will match to a square of 100x100 virtual units on the floor.
// that means that that the light map bitmap that will be created will be created will be in the size of 10x10.
// Though it is a very small bitmap it still contains 100 light samples. Compare it to the four samples one gets
// when using Goraud shading (values are calculated only the vertices).
// If a value of 0 is given for sample_rate then all the bitmaps will be in the size of max_bm_side X max_bm_side
//
// max_bm_side: The maximum alowed height or width of the created bitmap.
// For example a value of 256 will allow bitmaps like 128x256 but not 512x128.
// Many 3D cards (like Voodoo 3 ) dont support bitmaps bigger than 256.
// Thats why it is not recommended to give higher values.
// If your application will run primarily in software mode then bigger bitmaps can be freely used.
// min_lightmap_size:
// In many cases tiny lightmaps are not useful (for example 1x1 or 2x2 size bitmaps)
// We can decide that if the number of pixels in the lightmap is less than min_lightmap_size
// then no lightmap will be created for the specific polygon.
// force_ray_tracing: YES or NO. Gives much more accurate lighting that takes into account obstacles between
// the lit surface and the source of light. Usually you will set it to YES.
// The disadvantage is that creating the lightmap will be slower when.
// Consider giving NO only when you plan to calculate lightmap dynamically.
// bitmap_number: defines whether the light map will be set
// as the first bitmap or the second bitmap (possible values are 1 or 2).
//
//
// Returns a handle to the lightmap bitmap handle.
//
// See also: STATE_group_create_lightmap(), STATE_object_create_lightmap()
// STATE_polygon_set_second_bitmap(), STATE_bitmap_merge(), STATE_polygon_switch_between_primary_and_secondary_bitmaps()
// STATE_polygon_merge_bitmaps()
//
//
// Example:
//
// double location[3]={0,0,0};
// STATE_polygon_get_center(floor_poloygon, location);
// location[2]+=100; // put the light 100 units above the floor
// DWORD my_light=STATE_light_create("light1", location);
// STATE_light_set_distance_reach(my_light,150); //This will create a nice light spot on the floor
// DWORD lightmap=STATE_polygon_create_lightmap(floor_polygon, 256, 4, 8, YES, 1); //The meaning of the arguments is: Create a light map that wont be bigger
//than 256x256. If there are less than 4 pixels then dont create a bitmap.
//Every pixel in the light map should correspond with a 8x8 square area on
//the polygon. Check for objects that cast shadow over the polygon. The
//light bitmap will be set as the primary bitmap.
STATE_IMPORT DWORD STATE_WINAPI STATE_polygon_create_lightmap(DWORD polygon_handle, int max_bm_side, int min_lightmap_size, double sample_rate, int force_ray_tracing, int bitmap_number);
//Switches between the first bitmap and the second bitmap of the polygon.
//This function is usually used with STATE_polygon_create_lightmap()
STATE_IMPORT void STATE_WINAPI STATE_polygon_switch_between_primary_and_secondary_bitmaps(DWORD polygon_handle);
//Merges the two bitmaps of the polygon into a new bitmap.
//Set this new bitmap as the primary bitmap. The second bitmap is canceled.
//This function is very useful in the following cases:
// 1) When we want to have the lightmap effects in software rendering.
// In software rendering we can use only one bitmap so this function helps in
// creating one bitmap from the two.
// 2) Merging the two bitmaps together using this function can lead to much better results
// than the merge that is done in realtime using the 3D card hardware.
// The disadvantage of using this function is that in many times the merged bitmap is
// a lot bigger than the sum of the two source bitmaps.
// This happens when one of the source bitmaps is tiled.
//
// To understand the other arguments of this function please see STATE_bitmap_merge().
//
//
// Question: Why do I need this function when I have STATE_bitmap_merge()
//
// Answer: Imagine we have a floor. The floor texture is a stone brick tiled 10x10.
// We want to merge the floor with the lightmap we have created for the floor.
// Calling STATE_bitmap_merge() will create a new bitmap that is a merge between
// our brick (1x1 brick) and the lightmap. This is of course not what we wanted.
//
STATE_IMPORT void STATE_WINAPI STATE_polygon_merge_bitmaps(DWORD polygon_handle, int is_lightmap_on_secondary_bitmap, int merge_function_type, double f1, double f2, int max_brightness);
//Moves the bitmap of the polygon
//If you intend to shift the bitmap of only one polygon you should use STATE_polygon_shift_bitmap_including_fractions() instead
//See note below.
//
// Parameters:
// -----------
//Delta_x: The desired change in the x coordinates of the bitmap. 0 means no change. numbers could also be negative.
//Delta_y: The desired change in the y coordinates of the bitmap. 0 means no change. numbers could also be negative.
//bitmap_number: 1 or 2. 1 for moving the primary bitmap. 2 for moving the secondary bitmap
//
// note that if delta_x or delta_y are assigned with an integer number it is as if it is assigned with 0.
// it is like rotating an object 0 degrees oo 360 degrees or -720 degrees. It will all give the same result.
// Examples:
// A)
// // Shifting the x coordinates of the primary bitmap half way
// STATE_polygon_shift_bitmap(poly, 0.5, 0, 1);
//
// B)
// // Shifting the y coordinates of the secondary bitmap one tenth in the oposit direction
// STATE_polygon_shift_bitmap(poly, 0, -0.1, 2);
//
// IMPORTANT NOTE:
// If you intend to shift the bitmap of only one polygon you should use STATE_polygon_shift_bitmap_including_fractions()
// For example if you want to shift the bitmap on a polygon that is used as a sky
// If the sky are made of one polygon then use STATE_polygon_shift_bitmap_including_fractions() insted
// If the sky are made of several polygons (Works better to have the sky made from several triangles if you are using fog)
// you should continue reading the note below.
// When the world is loaded some of the polygons
// are split into smaller fractions (as part of BSP Tree creation)
// so it could be that you will have to shift the bitmap of several polygons, not just the one you intended.
// For example lets assume that you put a very big polygon in the sky
// (to create clouds effect using LIGHT_SOURCE_GLASS, see STATE_polygon_set_translucent() ) now you want to shift the bitmap
// you do DWORD sky=STATE_polygon_get_handle_using_name() and you call STATE_polygon_shift_bitmap()
// Now it is very possible that you will notice that only a small part of your polygon shift its bitmap.
// Here is how to solve it:
// At the beginning of your program collect all the fractions that make your sky
// like that:
// for(DWORD poly=STATE_polygon_get_first_polygon(); poly!=NULL; poly=STATE_polygon_get_next(poly)) {
// char *name=STATE_polygon_get_name(poly);
// if(strcmp(name, "My_Sky")==0) {
// m_sky_polygons[m_number_of_sky_polygons]=poly;
// m_number_of_sky_polygons++;
//
// }
//
// }
//
// Now to shift the bitmap do:
// for(int i=0; i<m_number_of_sky_polygons; i++) {
// STATE_polygon_shift_bitmap(m_sky_polygons[i], wind_speed, 0, 1);
// }
//
//
STATE_IMPORT void STATE_WINAPI STATE_polygon_shift_bitmap(DWORD polygon_handle, double delta_x, double delta_y, int bitmap_number);
//See STATE_polygon_shift_bitmap() for information.
//Use this function instead of STATE_polygon_shift_bitmap() when you are NOT shifting a collection of polygons that belongs to one shape
STATE_IMPORT void STATE_WINAPI STATE_polygon_shift_bitmap_including_fractions(DWORD polygon_handle, double delta_x, double delta_y, int bitmap_number);
//One can use this function to associate your own data structure to a polygon.
//Whether one decides to use this function or not depends on one's programming style.
//The obvious alternative for using this function is to have your own structure or class
//for each polygon and that one of the fields in your class would be the polygon_handle through which
//you can access the STATE functions.
//
// Parameters:
// polygon_handle:
// a handle to an polygon
//
// my_own_data:
// A pointer to a class or structure or even a function. This pointer can points
// to whatever you want it to point. The Engine doesnt do anything with this pointer
// it simply save it for you so you can call STATE_polygon_get_my_own_data() to retrieve it.
//
// Example:
//
// typedef struct polygon_data
// {
// int any_data1;
// int number_of_times_that_got_hit;
// //And anyother data you might need in your program
// } polygon_data;
//
// polygon_data poly_data; //or use new(), malloc() or whatever ...
// STATE_polygon_attach_my_own_data(my_polygon, &poly_data);
STATE_IMPORT void STATE_WINAPI STATE_polygon_attach_my_own_data(DWORD polygon_handle, void *my_own_data);
STATE_IMPORT void *STATE_WINAPI STATE_polygon_get_my_own_data(DWORD polygon_handle);
// This function is probably useless for 99.9999% of our users.
// You will need it only if you choose to write your own version STATE_engine_render()
// The 2d polygon animation is updated automatically according to need each time that STATE_engine_render()
// is called and a polygon with animation is rendered. If one doesn't call STATE_engine_render()
// (because one chooses to use his own renderer) then the 3D_animation frame is not updated.
// Only in this case you should call this function so that your external renderer can benefit from
// the 2d animation mechanism.
STATE_IMPORT void STATE_WINAPI STATE_polygon_update_animation(DWORD polygon_handle, DWORD camera_used_for_rendering);
// Returns the first patch that is attached to the given polygon.
// If the given polygon is a patch in itself then the function will return NULL.
// To check whether a polygon is a patch or not, use STATE_polygon_get_patch_type()
// See also STATE_polygon_get_patch_father.
//
// Example
//
// //here is how to make a function that counts how many patches are attached to a given polygon
//
// int count_patches(DWORD polygon_handle)
// {
// int count=0;
// check_patch=STATE_polygon_get_patch_type(polygon_handle);
// if(check_patch!=0) {
// MessageBox("The given polygon is a patch in itself !
// return(-1); //instead we could do polygon_handle=STATE_polygon_get_patch_father(polygon_handle);
// //and continue normal execution of the function
// }
//
// for(DWORD poly=STATE_polygon_get_first_patch(polygon_handle); poly!=NULL; poly=STATE_polygon_get_next_patch(poly) )
// count++;
//
// return(count);