射击游戏

开发平台：

Visual C++

3DSTATE.H：源码内容

// time_for_each_frame[1]= 200; //The second frame will be shown for one second
// STATE_animation_set_times(my_animation, time_for_each_frame, 2);
//
STATE_IMPORT int STATE_WINAPI STATE_animation_set_times(DWORD animation_handle, DWORD time_for_each_frame[], int size_of_array);
// time_for_each_frame: should be equal to STATE_animation_get_number_of_frames()
// the time is in hundreds of seconds.
// Returns OK or VR_ERROR
// Example:
// DWORD time_for_each_frame[10]
// STATE_animation_set_times(my_animation, time_for_each_frame, 10);
//
STATE_IMPORT int STATE_WINAPI STATE_animation_get_times(DWORD animation_handle, DWORD time_for_each_frame[], int size_of_array);
//Get the duration of the given frame. (in hundreds of seconds)
// frame_index: 0 means the first frame
// 1 means the second frame etc ...
// to get the last frame frame_index should be equal to the numbers of frames minus one.
//For Example:
// time=STATE_animation_get_frame_time(my_anim,0); // This would return the time
// // in hundreds of second that
// // the first bitmap will be shown
// // before it replaced by the second bitmap frame.
STATE_IMPORT DWORD STATE_WINAPI STATE_animation_get_frame_time(DWORD animation_handle, int frame_index);
// Set the duration of the given frame. (in hundreds of seconds)
// returns OK or VR_ERROR
// For Example:
// STATE_animation_set_frame_time(my_anim,0,100); // This would set the duration
// // in hundreds of second (100== 1 second) of
// // the first bitmap will be shown
// // before it replaced by the second bitmap frame.
STATE_IMPORT int STATE_WINAPI STATE_animation_set_frame_time(DWORD animation_handle, int frame_index, DWORD time);
// Returns the animation name.
// The function returns a pointer to the name which is stored internally inside the 3D Engine
// Visual Basic users should use STATE_entity_get_name() instead.
// See also STATE_entity_get_namel()
STATE_IMPORT char * STATE_WINAPI STATE_animation_get_name(DWORD animation_handle);
//NOTE that if the name is already in use by another animation
//the function would automatically add a number to the end of the name
STATE_IMPORT void STATE_WINAPI STATE_animation_set_name(DWORD animation_handle, char *name);
// examples:
// factor==10 would make the animation ten time slower
// factor==0.1 would make the animation ten time faster
// only if all the numbers in the array are bigger then 10
// Say we have this times series 1, 2, 20
// now if we call with factor 0.1 we get the series 1, 1, 2
// Note !! If we call again with factor=10
// we get back the series we started with 1,1,2 => 1,2,20
// The mechanism is smart enough to deal with that.
STATE_IMPORT void STATE_WINAPI STATE_animation_factor_speed(DWORD animation_handle, double factor);
// speed==1 means restore normal speed
// speed==2 means twice slower then normal speed
// speed==0.5 means twice faster then normal speed
// animation frames are never skipped. See
// remarks on STATE_animation_factor_speed() to
// understand the implication.
STATE_IMPORT void STATE_WINAPI STATE_animation_set_speed(DWORD animation_handle, double speed);
STATE_IMPORT void STATE_WINAPI STATE_animation_delete_all(void);
//Note that you cant use the handle after it was deleted
// A good practice will be like that:
// STATE_animation_delete(my_animation);
// my_animation=NULL;
STATE_IMPORT void STATE_WINAPI STATE_animation_delete(DWORD animation_handle);
// sending YES will write the given animation to file after call to STATE_engine_save() with SAVE_ONLY_WHATS_NEEDED
// Note that if STATE_engine_save() is called without SAVE_ONLY_WHATS_NEEDED, all the animations will be saved
// Note ! If the animation is used directly by one of the polygons
// in the saved group it will be saved no matter how the save_flag is set !
// The need for this function is because though the engine can figure out itself
// what animations are needed to the saved group it doesn't know what animation will
// be needed in run time. Using this flag one can determine the animation resources
// to use in run-time.
STATE_IMPORT void STATE_WINAPI STATE_animation_set_save_flag(DWORD animation_handle, int yes_no_flag);
// returns YES or NO
// see STATE_animation_set_save_flag() for more details
STATE_IMPORT int STATE_WINAPI STATE_animation_get_save_flag(DWORD animation_handle);
//Returns the number of frames in the animation.
// On Error returns 0
// Example: Say we have an animation of a runner. The animation is combined
// from 5 bitmaps series, the runner from the front,45 degrees, side, 135 degrees, and from the back
// (look how it is defined in the wld file, FRONT, FRONT_SIDED, SIDE, BACK).
// Every series must contain the same number of bitmaps.
// calling this function will return the number of bitmap in each series.
STATE_IMPORT int STATE_WINAPI STATE_animation_get_number_of_frames(DWORD animation_handle);
//Returns the number of bitmaps in the animation.
// On Error returns 0
// Example: Say we have an animation of a runner. The animation is combined
// from 5 bitmaps series, the runner from the front,45 degrees, side, 135 degrees, and from the back
// (look how it is defined in the wld file, FRONT, FRONT_SIDED, SIDE, BACK).
// Every series must contain the same number of bitmaps.
// calling this function will return the number of bitmap in each series multiply by the number
// of series.
STATE_IMPORT int STATE_WINAPI STATE_animation_get_number_of_bitmaps(DWORD animation_handle);
// This function returns an array with the handle to all the
// bitmaps.
// bitmaps_array[] is an array of DWORD. This array will be filled with handles to
// all the bitmaps of the animation.
// NOTE: you must allocate memory for the array before calling this function
// Example:
// int num_of_bitmaps=STATE_animation_get_number_of_bitmaps(animation_handle);
// // allocating mem using new or malloc etc ...
// DWORD *bitmaps_array=(DWORD *)malloc(num_of_bitmaps*sizeof(DWORD));
// STATE_animation_get_all_bitmaps(animation_handle, bitmaps_array);
//
// Note that if a certain bitmaps is used twice by the animation, than its handle will
// appear twice in the bitmaps_array.
// handles
STATE_IMPORT void STATE_WINAPI STATE_animation_get_all_bitmaps(DWORD animation_handle, DWORD bitmaps_array[]);
// Returns YES if the last world that was loaded, using STATE_engine_load_world()
// or STATE_engine_add_world().
// Returns NO otherwise
STATE_IMPORT int STATE_WINAPI STATE_animation_is_part_of_the_last_world(DWORD animation_handle);
// Returns the number of polygons that are using the given bitmap
STATE_IMPORT int STATE_WINAPI STATE_animation_get_number_of_polygons_with_animation(DWORD animation_handle);
//Create a new animation that has the same bitmaps and timing as the given animation.
// Returns the new animation. If an error occurred, it will return NULL.
//
// Here are some ideas for using this function.
// You will need this function if you want to use the same animation but with different timing.
// For example, let say that your animation is a tree blowing in the wind. You probably
// have lots of trees and each of them use the same animation. Now if you dont want
// all the trees to move as one then you can do one of the following:
// 1) Use STATE_polygon_set_animation_frame() to give each tree a different frame
// Or
// 2) Use this function to duplicate an animation and then to give different timing.
STATE_IMPORT DWORD STATE_WINAPI STATE_animation_duplicate(DWORD animation_handle, char *new_name);
// This function can be used to replace the bitmap of a certain frame in the animation.
// bitmap_list: is one of the five constants: BITMAP_LIST_FRONT, BITMAP_LIST_FRONT_SIDED, BITMAP_LIST_SIDE, BITMAP_LIST_BACK_SIDED, BITMAP_LIST_BACK
// frame_index: 0 means the first frame. -1 has a special meaning, it means the last frame
// bitmap_handle: A handle of the bitmap that will be set for the given frame.
// See also STATE_animation_get_bitmap()
// Return OK or VR_ERROR
STATE_IMPORT int STATE_WINAPI STATE_animation_set_bitmap(DWORD animation_handle, int bitmap_list ,int frame_index, DWORD bitmap_handle);
//The return value is The name of the bitmap without the extension
// the bitmap_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_animation_get_handle()
STATE_IMPORT char *STATE_WINAPI STATE_animation_get_frame_bitmap_name(DWORD animation_handle, int bitmap_list ,int frame_index);
//This function is very similar to STATE_bitmap_get_transparent_index()
//For info check STATE_bitmap_get_transparent_index()
//This function is needed only in the rare cases that some of the
//animation bitmaps could not be loaded when the world was loaded.
//For example 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 transparent index
//If you want to check if the bitmap is in used then use STATE_animation_get_frame_bitmap_handle()
STATE_IMPORT int STATE_WINAPI STATE_animation_get_frame_transparent_index(DWORD animation_handle, int bitmap_list ,int frame_index);
//--------------------------------------------------------//
//=========== T H E B I T M A P A P I ================//
//--------------------------------------------------------//
// This API deals with bitmaps and the way they are used by the Engine
// Returns YES or NO.
// YES , if the given handle is a bitmap handle. NO if not.
// If it is not a bitmap 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_BITMAP()
STATE_IMPORT int STATE_WINAPI STATE_bitmap_is_bitmap(DWORD bitmap_handle, char *function_asking);
// Returns a handle to a previously loaded bitmap (using the file name)
// If the return value is NULL it means
// that no bitmap with the given name and the given transparent index was loaded to the engine.
//Think of the transparent_index as part of the name
//there could be several bitmaps with the same name but each can have a different
//transparent index. Note that the engine keeps a separate copy for each transparent index
//Example:
// STATE_bitmap_get_handle("bitmaps\people\man12.bmp",-1);
STATE_IMPORT DWORD STATE_WINAPI STATE_bitmap_get_handle(char *file_name, int transparent_index);
STATE_IMPORT DWORD STATE_WINAPI STATE_bitmap_get_first_bitmap(void);
STATE_IMPORT DWORD STATE_WINAPI STATE_bitmap_get_next(DWORD bitmap_handle);
// File name extension (if given) is ignored. The engine will search
// for recognized extensions (jbm, bmp or jpg) and will load which ever
// exists. If the engine finds more then one recognized extension
// (for example grass.bmp and grass.jpg) it will load the file
// which was most recently modified
// If the specified bitmap was already loaded then it just retrieves
// its handle (in that case it is exactly like STATE_bitmap_get_handle() )
// transparent_index should be -1 for no transparent and 0
// for removing the most frequent color in the bitmap (usually
// the most used color is the background)
// transparent_index==1 means remove the second most used color etc ...
// Note the difference between this command and STATE_utilities_load_bitmap_from_file()
// This command loads a bitmap into the engine, while STATE_utilities_load_bitmap_from_file()
// is just an extension to the Win32 API making it easy to load a bitmap from
// the disk and to get its HBITMAP handle (a Win32 type)
//
// Important:
// Bitmaps that are not it the power of two dimensions will be automatically resampled (this is because 3D cards can only handle dimensions that are of the power of two !).
// This is why it is best to have all your bitmaps in the power of two dimensions.
// Numbers of the power of two are: 1,2,4,8,16,32,64,128,256,512,1024
// A bitmaps in the size of 128x256 is OK
// A bitmap in the size of 100x200 is not OK and there for will be automatically resampled by the engine (consuming more time )
// Though the engine does a good job in resampling the bitmaps, Corel PhotoPaint or Adobe PhotoShop are probably better ...
// Meaning that it is better if you resample you bitmaps your self and let the engine handle only bitmaps that are in the power of two
//
// Examples:
// A-
// note that we dont have to give the bitmap extension
// if we do it is simply ignored
// STATE_bitmap_load("c:\bitmaps\my_bitmap",-1);
// B-
// Load a bitmap and set the most used color as transparent
// STATE_bitmap_load("c:\bitmaps\my_bitmap",0);
// C-
// Load a bitmap and set the second most used color as transparent
// STATE_bitmap_load("c:\bitmaps\my_bitmap",1);
//
// NOTE this case !
// D-
// This example has some good news and some bad news.
// The good news is that if c:\bitmaps\grass27
// is exactly the same as c:\NEW_bitmaps\grass27
// Then we shouldnt worry about wasting memory by loading two identical bitmaps
// When we try to load the second bitmap the engine
// will see that it already has a bitmap with that name and
// it will return the handle to the first loaded bitmap without doing anything.
// The bad news is that if the bitmaps are different, the engine
// wont overwrite the old one. It will just return the handle to the already
// loaded bitmap without doing anything else.
// handle1=STATE_bitmap_load("c:\bitmaps\grass27",-1);
// handle2=STATE_bitmap_load("c:\NEW_bitmaps\grass27",-1);
// if(handle1!=handle2) error_message(); //Never happens
//
// A solution for this in case we want to overwrite the old bitmap
// is to first delete the old bitmaps and then to load the new one.
//
// E-
// If we have two bitmaps in the same directory one is called
// my_bitmap.jpg and the other is called my_bitmap.bmp
// handle=STATE_bitmap_load(my_bitmap.jpg,-1);
// Note that the engine will load my_bitmap.bmp and not
// my_bitmap.jpg. Thats because loading bitmaps in jpg format is much slower
// And also because the jpg version of a bitmap is usually not as good as the original
// (depending how much compression we used)
//
// see also STATE_bitmap_rgb_color_to_index()
STATE_IMPORT DWORD STATE_WINAPI STATE_bitmap_load(char *file_name, int transparent_index);
// Returns the an index to a color in the palette that is the closest color
// to the given rgb.
//This function can be used together with STATE_bitmap_load() so the transparency color
//is calculated according to the rgb ...
STATE_IMPORT int STATE_WINAPI STATE_bitmap_rgb_color_to_index(DWORD bitmap_handle,BYTE red, BYTE green, BYTE blue);
//Receive an index to a color in the palette and returns its RGB.
//returns OK or VR_ERROR (returns VR_ERROR if the index is bigger (or equal) than the number of colors in the palette)
//See also STATE_bitmap_get_memory()
// Example: //Get the rgb of the most used color in the bitmap (palette index 0)
// BYTE red,green,blue;
// STATE_bitmap_index_to_rgb(my_bitmap, 0, &red, &green, &blue);
STATE_IMPORT int STATE_WINAPI STATE_bitmap_index_to_rgb(DWORD bitmap_handle, BYTE index ,BYTE *red, BYTE *green, BYTE *blue);
// returns OK or VR_ERROR. VR_ERROR if there is no transparent color for this bitmap.
STATE_IMPORT int STATE_WINAPI STATE_bitmap_get_transparent_rgb(DWORD bitmap_handle, int *red, int *green, int *blue) ;
// returns -1 if we transparent is not used for the given bitmap
// 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_bitmap_get_transparent_index(DWORD bitmap_handle) ;
//Create a new bitmap which is a resampled version of
//the given bitmap. If new_width and new_height are
// equal to the width and the height of the given
// bitmap, it will just duplicate the bitmap ...
STATE_IMPORT DWORD STATE_WINAPI STATE_bitmap_resample(DWORD source_bitmap_handle, int new_width, int new_height);
// dont ever use the handle after the bitmap was unloaded
STATE_IMPORT void STATE_WINAPI STATE_bitmap_unload(DWORD bitmap_handle);
//Returns the name according to the bitmap file name (without the extension)
// 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_bitmap_get_name(DWORD bitmap_handle);
STATE_IMPORT int STATE_WINAPI STATE_bitmap_get_number_of_polygons_using_bitmap(DWORD bitmap_handle);
STATE_IMPORT int STATE_WINAPI STATE_bitmap_get_width(DWORD bitmap_handle);
STATE_IMPORT int STATE_WINAPI STATE_bitmap_get_height(DWORD bitmap_handle);
//Using this function one can check and modify the actual pixels of the bitmap
//Returns an array of pixel indexes in the size of width*height
//see STATE_bitmap_get_height() and STATE_bitmap_get_width() to get the width and the height
//An index 255 means that it is a transparent color. an index of 0 means that this is the most
//frequently used color in the bitmap etc ...
// Here are few examples:
// BYTE *bmp_ptr=STATE_bitmap_get_memory(STATE_bitmap_handle);
// int width=STATE_bitmap_get_width(STATE_bitmap_handle);
// for(int i=0; i<width; i++) bmp_ptr[0]=0; //setting the first line in the texture to have the rgb of index 0 in the palette
// bmp_ptr[width]=255; //Setting the first pixel in the second line to be transparent
// //Note that this bitmap must be a transparent bitmap for this to work.
// BYTE last_pixel_index=bmp_ptr[width*height-1]; //examining the last pixel (bottom-down)
// BYTE red,green,blue;
// // Lets get the color of that pixel
// STATE_bitmap_index_to_rgb(STATE_bitmap_handle, last_pixel_index, &red,&green, &blue);
STATE_IMPORT BYTE * STATE_WINAPI STATE_bitmap_get_memory(DWORD bitmap_handle);
// the palette is an array of WORDs; each 16 bits represents a pixel
// the most significant bits are red; the least significant are for blue (green in the middle)
// the RGB bit count for each color is 5-5-5 (the most significant bit not used)
// or 5-6-5. which one of them depends on the current graphics card you are using
// Use STATE_utilities_rgb16_to_rgb24() to get the colors
// Example:
// WORD *pal=STATE_bitmap_get_palette(bm_handle);
// BYTE red,green,blue;
// STATE_utilities_rgb16_to_rgb24(pal[0],&red,&green,&blue); //Return the rgb of the first color in the palette
// //Note that this color is the most frequent used color.
// See also STATE_bitmap_index_to_rgb() that can be used to get specific color from the palette
STATE_IMPORT WORD * STATE_WINAPI STATE_bitmap_get_palette(DWORD bitmap_handle);
//With this function you can change the colors of a bitmap.
//For example:
// The next line will set the most used color in my_bitmap (index 0 == the most used )to the color of red (red==255,0,0)
// STATE_bitmap_set_palette_color(my_bitmap,0, 255,0,0 );
//Note that the bitmap memory is not modified. Only the palette is modified.
//For changing the bitmap itself see STATE_bitmap_get_memory()
// Returns OK or VR_ERROR (returns VR_ERROR if the index is bigger (or equal) than the number of colors in the palette)
STATE_IMPORT int STATE_WINAPI STATE_bitmap_set_palette_color(DWORD bitmap_handle, BYTE index_of_color_to_be_changed, BYTE red, BYTE green, BYTE blue);
// returns the number of colors in the palette
STATE_IMPORT int STATE_WINAPI STATE_bitmap_get_palette_size(DWORD bitmap_handle);
// saves a bitmap on the disk.
// The file format is according to the extension
// ( Supported types by STATE.dll version 1.0 are windows bitmap (bmp) and jpeg (jpg) )
// If full_path_name==NULL than the bitmap will be save in the current directory
// in a windows bitmap file format.
// Examples:
// A- STATE_bitmap_save( my_bitmap_handle, "c:\John\bitmaps\grass.bmp");
// B- STATE_bitmap_save( my_bitmap_handle, "grass.jpg");
// C- STATE_bitmap_save( my_bitmap_handle, NULL);
// D- STATE_bitmap_save( my_bitmap_handle, "..\grass.jbm");
STATE_IMPORT void STATE_WINAPI STATE_bitmap_save(DWORD bitmap_handle, char *full_path_name);
//Create a merged bitmap in max_width,max_height dimensions
// i.e if one bitmap is 32x128 and the second is 64x64 then the
// created bitmap will have the size 64x128.
// The created bitmap is not transparent.
// In the areas where bitmap1 is transparent the merged bitmap
// will have the transparent color of bitmap1.
// bitmap1 handle can be the same as bitmap2 (for merging a bitmap with itself).
//See also STATE_bitmap_resample(), STATE_polygon_merge_bitmaps()
//
// merge_function_type should be one of the following
#define MERGE_FUNCTION_ADD 1 // new_pixel= f1*pixel + f2*pixel + C
#define MERGE_FUNCTION_MUL 2 // new_pixel= f1*pixel*pixel/256 + C . Note that f2 is not used here !
// C is a constant that depends on the bitmaps and on the max_brightness value.
// The purpose of this constant is to make sure that (R+G+B)/3 <= max_brightness
// will always be true and that there will always be at least one pixel that
// (R+G+B)/3 == max_brightness. R,G,B are the RGB values of the new bitmap.
// This method is used to control the brightness level of the merged bitmap.
// When using MERGE_FUNCTION_MUL the result bitmap will always be darker than the
// two source bitmaps. If you didnt get any of it just give MERGE_IGNORE_MAX_BRIGHTNESS.
// This will make C equal 0 ( C from the functions' formulas above).
#define MERGE_IGNORE_MAX_BRIGHTNESS 0
#define MERGE_AUTO_MAX_BRIGHTNESS -1 //Automatically controls the merge to achieve two goals:
// 1) The merged bitmap wont be saturated with light.
// 2) The level of brightness of the merged bitmap will be similar to the source bitmaps
//Return value: Returns a handle to a new bitmap which is the outcome of meging the two given bitmaps.
//Examples:
//
// A)
// DWORD bmp1=STATE_bitmap_load("d:\floor_bitmap", -1);
// DWORD bmp2=STATE_bitmap_load("d:\light_spot_bitmap", -1);
// DWORD merge=STATE_bitmap_merge(bmp1, bmp1, MERGE_FUNCTION_MUL, 2,0,MERGE_IGNORE_MAX_BRIGHTNESS);
// STATE_bitmap_save(merge, "d:\garbage3\bitmaps\merged_mul.bmp");
//
// B)
// DWORD merge=STATE_bitmap_merge(bmp1, bmp1, MERGE_FUNCTION_ADD, 0.5, 0.5, MERGE_IGNORE_MAX_BRIGHTNESS);
// STATE_bitmap_save(merge, "d:\garbage3\bitmaps\merged_add.bmp");
//
// Try both examples and see what happens.
//
STATE_IMPORT DWORD STATE_WINAPI STATE_bitmap_merge(DWORD bitmap1, DWORD bitmap2, int merge_function_type, double f1, double f2, int max_brightness);
//-------------------------------------------------------//
//======== T H E S O U N D A P I ===================//
//-------------------------------------------------------//
/*
STATE sound engine is built using parts of FMod library. If This API is used for commercial
purposes then you must get a propre license from FMod. A ccording to FMod web-site
as long as you dont genrate any revenues from their model you dont have to purchase a license.
For updated information regarding the terms of use of the FMod library please contact www.fmod.org
In the future we will replace the FMod library with our own library.
In order to be able to use the sound API you must do the following:
1) Add the fmod lib to your project. (For example users of Visual C should add the fmodvc.lib)
2) Make sure to put the fmod.dll in the same directory as your executable.
*/
#define SOUND_NO_LOOP 0
#define SOUND_LOOP_NORMAL 1
#define SOUND_PAUSED 1
#define SOUND_RESUME_PLAYING 0
//const double SOUND_DISTANCE_DEFAULT=1;
#define SOUND_DISTANCE_DEFAULT 1.0
//Load a sound file into the engine.
//Parameters:
// file_name:
// file to load
//
// entity:
// A handle to a polygon or a group or an object
// The entity parameter makes it very easy to create 3D sound that its volume is sensative
// to the distance form the entity and the balance is automatically computed for each speaker according to the
// location of the entity.
// If entity handle is NULL then the sound is not attached
// to any entity (polygon,object or group) and is treated as a background sound,
// otherwise it is a 3D-sound positioned at the entity's location , volume and
// balance are constantly changed according to the listener location.
// Important: Make sure that if the sound is attached to an entity and the entity is deleted then
// this could cause a fatal error. Make sure to stop a sound or dettach it before deleteing
// the object it is associated with.
//
// distance_reach
// The third argument is the maximum distance reach of the sound, which can be SOUND_DISTANCE_DEFAULT,
// or a distance reach that the user decides on. This argument will effect only if the entity handle
// given is not NULL, meaning that the sound has a defined position.
// Try giving different numbers and see the effect. for example: 300, 1000, 10000 etc ...
//
// Examples:
//
// A)
// This will set the mp3 song as a background sound
// DWORD madona STATE_sound_load("madona\like_a_virgin.mp3", NULL,SOUND_DISTANCE_DEFAULT);
// STATE_sound_play(madona, SOUND_LOOP_NORMAL);
//B)
// When we will get closer or further away from the bird the engine will
// automatically update the volume and the balance according to the camera relative
// position towards the bird object.
//
// DWORD bird_sound=STATE_sound_load("voices\bird_sound.mp3", bird_object_handle,SOUND_DISTANCE_DEFAULT);
// STATE_sound_play(bird_sound, SOUND_LOOP_NORMAL);
///With Wave files it is exactly the same, only with a wav sound file.
//
//
// C)
// This will set the Wave song as a background sound
// Note that it is much better to use mp3 as a background sound since the files
// are a lot smaller.
//
// DWORD madona=STATE_sound_load("madona\like_a_virgin.wav", NULL, SOUND_DISTANCE_DEFAULT);
// STATE_sound_play(madona, SOUND_LOOP_NORMAL);
STATE_IMPORT DWORD STATE_WINAPI STATE_sound_load(char *file_name, DWORD entity_handle,double distance_reach);
// Will start playing the sound.
// Note that to get a handle to the sound you must first call
// STATE_sound_load()
// Note that you can call this function again with the same sound file while the sound of the first
// call is still playing (Canonically ). In this case you will hear both sounds played together.
// The engine will treat the second call as if it is a new sound.
//loop is SOUND_LOOP_NORMAL or SOUND_NO_LOOP
// SOUND_LOOP_NORMAL will make the sound to be played from the beginning each time it ends.
// Example:
// DWORD madona STATE_sound_load("madona\like_a_virgin.mp3", NULL,SOUND_DISTANCE_DEFAULT);
// STATE_sound_play(madona, SOUND_LOOP_NORMAL);
//
// Returns OK or VR_ERROR
STATE_IMPORT int STATE_WINAPI STATE_sound_play(DWORD sound_handle,const int loop);
//This function will attach in run-time an entity handle to the sound, thus changing the location
//of the sound and accordingly the volume and balance.
//If the sound is playing already, the change will take effect only after stopping and replaying the sound.
//entity_handle can be a handle to one of the three: polygon handle, object handle or group handle.
//if entity handle is NULL then the engine actually performs Detach meaning that the sound is treated
//as a background sound that is not attached to any entity.
//Important: Make sure that if the sound is attached to an entity and the entity is deleted then
// this could cause a fatal error. Make sure to stop a sound or dettach it before deleteing
// the object it is associated with.
//Example:
// DWORD sound_handle=STATE_sound_load("my_song",chair);
//when playing this sound, it will be heard as coming from the chair.
// STATE_sound_attach(sound_handle,table);
//now, when playing the sound, it will be heard as coming from the table.
// STATE_sound_attach(sound_handle,NULL);
//now, the sound is a background sound.
STATE_IMPORT int STATE_WINAPI STATE_sound_attach(DWORD sound_handle, DWORD entity_handle);
//This function will start playing all the sounds that have been already loaded.
//The volume and balance of each sound will be calculated automatically by the engine.
//!!! this function plays all sounds without checking if a sound is already being played.
STATE_IMPORT void STATE_WINAPI STATE_sound_play_all_sounds();
//This will stop playing the given sound
//Returns OK or VR_ERROR
STATE_IMPORT int STATE_WINAPI STATE_sound_stop(DWORD sound_handle);
//This will stop playing all the sounds.
STATE_IMPORT void STATE_WINAPI STATE_sound_stop_all_sounds();
//Using this function togwether with STATE_sound_get_next()
//makes it possible to go all over the sounds that were loaded into the engine.
// Example:
// for(DWORD sound=STATE_sound_get_first() ; sound!=NULL; sound=STATE_sound_get_next(sound) ) {
// //do something for each sound
// }
STATE_IMPORT DWORD STATE_WINAPI STATE_sound_get_first();
//use this function to change the distance reach of a sound that is attached to some entity.
//the engine measures the distance between the entity that is attached to the sound and the
//camera and updates the volume and balance accordingly.You can increase the volume of a sound
//by increasing the distance reach of the sound, or decreasing the objects' sound respectively.
STATE_IMPORT int STATE_WINAPI STATE_sound_set_distance_reach(DWORD sound_handle,double distance_reach);
//Using this function togwether with STATE_sound_get_next()
//makes it possible to go all over the sounds that were loaded into the engine.
// Example:
// for(DWORD sound=STATE_sound_get_first() ; sound!=NULL; sound=STATE_sound_get_next(sound) ) {
// //do something for each sound
// }
STATE_IMPORT DWORD STATE_WINAPI STATE_sound_get_next(DWORD sound_handle);
//This function will set the volume of the given sound.
//volume should be in the range of [0-1000] . 1000 is the maximum valume possible.
//100 is the default volume.
//See also STATE_sound_set_volume()
//volume should be in the range of [0-1000] . 1000 is the maximum valume possible.
//The difference between this function and STATE_sound_set_volume_realtime()
//Is that this function works even if the sound is not being played.
//If you intend to use a specific sound in a constant volume then
//it is better to use STATE_sound_set_volume() then STATE_sound_set_volume_realtime().
//Note that if the sound is attached to an entity (object, polygon or group)
//then actual volume will be effected by the distance of the viewerlistener from the
//sound source. Note also that you can use
//STATE_sound_set_distance_reach() to effect the result calculated volume.
//This is important because if the listener is located outside the distance reach
//zone then no sound will be heard.
STATE_IMPORT void STATE_WINAPI STATE_sound_set_volume(DWORD sound_handle,int volume);
//This function will set the volume of the given sound.
//See also STATE_sound_set_volume()
//volume should be in the range of [0-1000] . 1000 is the maximum valume possible.
//The difference between this function and STATE_sound_set_volume()
//Is that this function works only while the sound is being played.
//If you intend to use a specific sound in a constant volume then
//it is better to use STATE_sound_set_volume().
//Note that if the sound is attached to an entity (object, polygon or group)
//then actual volume will be effected by the distance of the viewerlistener from the
//sound source. Note also that you can use
//STATE_sound_set_distance_reach() to effect the result calculated volume.
//This is important because if the listener is located outside the distance reach
//zone then no sound will be heard.
STATE_IMPORT void STATE_WINAPI STATE_sound_set_volume_realtime(DWORD sound_handle,int volume);
//You can call this function only if a sound is being played.
//The return number will be in the range [0-1000].
//500 is the default.
//1000 is the volume defined by the sound file itself.
// The function will return -1 if the sound is not being played or some error has happened.
// See also STATE_sound_set_volume(), STATE_sound_set_distance_reach()
STATE_IMPORT int STATE_WINAPI STATE_sound_get_volume(DWORD sound_handle );
//Will set the frequency of the sound. The range is [0-100000]
//Default is 44100.
//You can use this function for special effect. For example simulating
//a racing car engine sound. Try adding 100 to the frequency each time that the speed
//of the car increases.
//See also STATE_sound_get_frequency()
STATE_IMPORT void STATE_WINAPI STATE_sound_set_frequency(DWORD sound_handle, int frequency);
//You can call this function only if the sound is playing.
// See STATE_sound_set_frequency()
STATE_IMPORT int STATE_WINAPI STATE_sound_get_frequency(DWORD sound_handle);
//Returns YES or NO.
STATE_IMPORT int STATE_WINAPI STATE_sound_is_sound_playing(DWORD sound_handle);
//Set the name of the sound. The default is the name of the sound file that was
//loaded without the path and the extension..
//See also STATE_sound_get_handle_using_name(), STATE_sound_get_sound_name()
STATE_IMPORT int STATE_WINAPI STATE_sound_set_sound_name(DWORD sound_handle, char *name);
// Returns the name of the sound
// 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_sound_set_sound_name()
STATE_IMPORT char * STATE_WINAPI STATE_sound_get_sound_name(DWORD sound_handle);
//Returns a handle to the sound according to the given name.
STATE_IMPORT DWORD STATE_WINAPI STATE_sound_get_handle_using_name(char *name);
//Returns the sound that is attached to the given entity. entity_handle
//can be a handle to one of the three: polygon handle, object handle or group handle.
//If no sound is attached to the given entity it will return NULL.
// Example:
// sound_handle=STATE_sound_get_handle_using_entity(my_object);
STATE_IMPORT DWORD STATE_WINAPI STATE_sound_get_handle_using_entity(DWORD entity_handle);
//pause can be one of the two: SOUND_PAUSED or SOUND_RESUME_PLAYING
//To pause a specific sound call this function with the SOUND_PAUSED constant.
//To start playing it again call with the SOUND_RESUME_PLAYING constant
//Example:
// STATE_sound_set_pause_mode(my_sound, SOUND_PAUSED); //this will pause the sound
// //your code here ....
// STATE_sound_set_pause_mode(my_sound, SOUND_RESUME_PLAYING); //this will resume playing.
STATE_IMPORT void STATE_WINAPI STATE_sound_set_pause_mode(DWORD sound_handle,BOOL pause);
//Will start playing the CD ROM. The first track is 1
//the last track is of course varied from one CD to another.
//To get the number of tracks use STATE_sound_CD_get_num_of_tracks()
STATE_IMPORT void STATE_WINAPI STATE_sound_CD_play(int track);
//This will stop playing the CD ROM.
STATE_IMPORT void STATE_WINAPI STATE_sound_CD_stop();
//Returns the current played track.
STATE_IMPORT int STATE_WINAPI STATE_sound_CD_get_track();
//Returns the number of tracks on the CD.
STATE_IMPORT int STATE_WINAPI STATE_sound_CD_get_num_of_tracks();
//pause can be one of the two: PAUSED or RESUME_PLAYING
//To pause a specific sound call this function with the PAUSED constant.
//To start playing it again call with the RESUME_PLAYING constant
//Example:
// STATE_sound_CD_set_pause_mode(PAUSED); //this will pause the sound
// //your code here ....
// STATE_sound_CD_set_pause_mode(RESUME_PLAYING); //this will resume playing.
STATE_IMPORT void STATE_WINAPI STATE_sound_CD_set_pause_mode(BOOL pause);
//This will eject the CD.
STATE_IMPORT void STATE_WINAPI STATE_sound_CD_eject();
//--------------------------------------------------------//
//======= T H E M U L T I P L A Y E R A P I ========//
//--------------------------------------------------------//
/*
This API allows multiple users to run the same application using
the Internet or their local network (LAN) as a mean of communication.
The API is focused on making it as simple as possible to write a multiplayer application.
In the next version we will also
provide servers that game and other application developers
can use as a lobby for potential users.
Before reading the various functions of this API
one should take a look at this "hello multiplayer" example.
Please also note the samples in the SDK.
Example:
void main()
{
STATE_engine_load_world(....)
//Usually one should ask the user wheter he wants to host the game application
//or to join an existing session.
int am_i_the_host=ask_user_if_he_wants_to_host_or_join();
if(am_i_the_host==YES) {
if(STATE_multiplayer_connect("game name", "Player name", NULL, TRUE)!=OK)
exit(-1);
}
else {
if(STATE_multiplayer_connect("game name","Player name", "domain_name_or_IP_of_hosting_computer", FALSE)!=OK)
exit(-1);
}
while (escape key not pressed)
{
STATE_engine_render(NULL,NULL);
//Sending a message
//Initialize a new message
STATE_multiplayer_message_create();
double location[3];
STATE_camera_get_location(NULL,&location[0],&location[1], &location[2]);
//Write the location to the internal message buffer.
STATE_multiplayer_message_write_buffer(location,sizeof(double)*3);
STATE_multiplayer_message_send();
//receiving a message
char sender_name[256];
double *opponent_location;
int result=STATE_multiplayer_message_get(sender_name);
if(result==STATE_MULTIPLAYER_USER_MESSAGE) {
opponent_location=STATE_multiplayer_message_read_buffer();
//process his location here...
double x=opponent_location[0];
double y=opponent_location[1];
double z=opponent_location[2];
...
}
}
STATE_engine_close();
}
*/
//This function initialize a multiplayer session.
//This function must be called before any multiplayer communication can take place.
//
// Aruments:
//----------
// host:
// If TRUE then this computer will become the host of the game.
// Usually the application should ask the user whether he wants to join an existing session or
// to start a new session on his computer.
//
// ip_address:
// Should be null if host==TRUE.
// If host==FALSE then this should be the IP or the domain name of the game application we want to join.
//
// player_name:
// The name of the player.
//
// Game_name:
// The name of the game. If there are several sessions running on the given host then
// only the session that matches this name will be chosen.
//
//
// Please also note that STATE_multiplayer_connect() can only connect to sessions that are based on STATE Engine.
//
// Return value:
// OK or VR_ERROR.
STATE_IMPORT int STATE_WINAPI STATE_multiplayer_connect(char *game_name,char *player_name, char *ip_address,BOOL host);
// Call this function to terminate the session.
// If your computer is hosting the session (See STATE_multiplayer_connect() )
// then calling this function will end the session completely.
// If you have joined a session running on a remote computer then calling this function
// will disconnect your computer from the session. All the other users computers
// can continue their session. When closing the engine, this function is automatically called,
// so you don't need to call it unless you need to manually disconnect before closing the engine.
STATE_IMPORT void STATE_WINAPI STATE_multiplayer_close();
//Calling this function tells the engine that you want now to start
//creating a new message and the previous message can be deleted.
//The engine has an internal buffer that is used to store the message.
//Calling STATE_multiplayer_message_create() simply reset this buffer.
// Example:
// STATE_multiplayer_message_create();
STATE_IMPORT void STATE_WINAPI STATE_multiplayer_message_create();
//The engine has an internal buffer that is used to store the message.
//Calling STATE_multiplayer_message_create() simply reset this buffer.
// Calling this function will add the given buffer to the internal message buffer.
// Returns: OK or VR_ERROR.
//
// Examples
// A)
// STATE_multiplayer_message_create();
// double location[3]={100,200,300};
// STATE_multiplayer_message_write_buffer(location, sizeof(double)*3);
// STATE_multiplayer_message_send(); // three double numbers will be sent 100,200,300
//
// B)
// double location[3]={100,200,300};
// STATE_multiplayer_message_write_buffer(location, sizeof(double)*3);
// location[0]=400;
// //Note that the second buffer is concatenated to the first one.
// STATE_multiplayer_message_write_buffer(location, sizeof(double)*3);
// STATE_multiplayer_message_send();// six double numbers will be sent 100,200,300, 400, 200, 300
STATE_IMPORT int STATE_WINAPI STATE_multiplayer_message_write_buffer(void *buffer, DWORD buffer_size_in_bytes);
//Sends a message to all the users who are connected to the current session.
//The engine has an internal buffer that is used to store the message.
//Calling STATE_multiplayer_message_create() simply reset this buffer.
//To compose a message use STATE_multiplayer_message_write_buffer()
STATE_IMPORT int STATE_WINAPI STATE_multiplayer_message_send();
#define STATE_MULTIPLAYER_SYSTEM_MESSAGE 6
#define STATE_MULTIPLAYER_USER_MESSAGE 7
//When the other playersusers in this session send messages these messages are accumulated in
//an internal queue inside the engine. This function removes the oldest message waiting
// from the queue and copy it to an internal buffer used for reading messages.
// In order to read the message content, use STATE_multiplayer_message_read_buffer()
//Returns one of this four options:
//1) STATE_MULTIPLAYER_USER_MESSAGE
// This means that this is a message from another user computer.
//
//2) STATE_MULTIPLAYER_SYSTEM_MESSAGE
// This means that this is a system message.
// A system message could be for example a notification that
// a new user has joined the session. See STATE_multiplayer_message_system_read()
// to learn how to process system messages.
//
//3) THERE_ARE_NO_MESSAGES
// This means that the message queue is empty and that there are no messages waiting
// for you to read.
//
//4) VR_ERROR
// An error occurred.
//
// Example:
//
// char sender_name[256];
// double *opponent_location;
// int result=STATE_multiplayer_message_get(sender_name);
// if(result==STATE_MULTIPLAYER_USER_MESSAGE) {
// opponent_location=STATE_multiplayer_message_read_buffer();
// //process his location here...
// }
//
STATE_IMPORT int STATE_WINAPI STATE_multiplayer_message_get(char *name_of_sender);
//Returns a pointer into the internal buffer that stores the message.
//This function can not be used to process system messages. To read system messages
// use STATE_multiplayer_message_system_read() instead.
//
// Example:
// char sender_name[256];
// double *opponent_location;
// int result=STATE_multiplayer_message_get(sender_name);
// if(result==STATE_MULTIPLAYER_USER_MESSAGE) {
// opponent_location=STATE_multiplayer_message_read_buffer();
// //process his location here...
// }
STATE_IMPORT void *STATE_WINAPI STATE_multiplayer_message_read_buffer();
// A new player has been created in the session
#define STATE_CREATEPLAYER 0x0003
//A player has been deleted from the session
#define STATE_DESTROYPLAYER 0x0005
// The player has lost its connection with all the
//other players in the session.
#define STATE_SESSIONLOST 0x0031
#define THERE_ARE_NO_MESSAGES NO
//When receiving a system message (i.e. STATE_multiplayer_message_get() returns
//STATE_MULTIPLAYER_SYSTEM_MESSAGE ) use this function to
//understand the type of the system message received.
//This function returns a constant that can be one of the following:
//
// STATE_CREATEPLAYER
// A new player has joined the session
//
// STATE_DESTROYPLAYER
// A player has left the session
//
//STATE_SESSIONLOST
// Our computer has lost its connection with all the
// other players in the session.
//
STATE_IMPORT unsigned int STATE_WINAPI STATE_multiplayer_message_system_read();
//Returns whether this computer serve as the host.
//The answer is according the the host argument given in STATE_multiplayer_connect().
STATE_IMPORT int STATE_WINAPI STATE_multiplayer_is_host();
//Returns the IP address of the computer which is running the application.
//Please note that this function should be called after the user computer is
//connected to the Internet.
//When using a dial-up connection (telephone modem) then the IP number will change
//on each connection.
// Q: Why do I need this function ?
// A: In case that the user computer is hosting the game then all the other player
// should have his IP number so they can connect to the host.
STATE_IMPORT char * STATE_WINAPI STATE_multiplayer_get_computer_ip();
/*
Writing and reading messages to/from the messages buffer is easily done using the functions:
STATE_multiplayer_message_read_buffer()
STATE_multiplayer_message_write_buffer()
However, in some languages such as Visual Basic,
one cannot pass a buffer as an argument to a function.
Therefor, the functions below were written mainly for the Visual Basic programmers.
(Although if a C programmer feels more comfortable with them he can use them as well)
As you can see, for each type of entry we use a different function, if it is textual entry we use :
STATE3dWorld1.Multiplayer_message_write_string("hello guys");
If we want to send our location, which is a floating point variable we use
STATE3dWorld1.Multiplayer_message_write_double (my_location.x);
If it抯 some integer, we use
STATE3dWorld1.Multiplayer_message_write_long (123456789);
And if we just need to send a byte (short) variable, we use
STATE3dWorld1.Multiplayer_message_write_byte('A');
*************************************************************************
IMPORTANT!!!
The entries are appended to the message buffer in the same order in which
they were inserted, so when a user receives that message he should extract
the entries from the message in the same order in which they were written.
***************************************************************************
For example :
Writing ...
STATE_multiplayer_write_string("John Smith");
STATE_multiplayer_write_double(location[0]);
STATE_multiplayer_write_double(location[1]);
STATE_multiplayer_write_double(location[2]);
Reading...
char playerName[100];
double location[3]={0,0,0};
STATE_multiplayer_read_string(playerName);
STATE_multiplayer_read_double(&location[0]);
STATE_multiplayer_read_double(&location[1]);
STATE_multiplayer_read_double(&location[2]);
*/
STATE_IMPORT int STATE_WINAPI STATE_multiplayer_message_write_double(double value);
//See function STATE_multiplayer_message_write_double()
STATE_IMPORT int STATE_WINAPI STATE_multiplayer_message_read_double(double *value);
//See function STATE_multiplayer_message_write_double()
STATE_IMPORT int STATE_WINAPI STATE_multiplayer_message_read_long(long *value);
//See function STATE_multiplayer_message_write_double()
STATE_IMPORT int STATE_WINAPI STATE_multiplayer_message_write_long(long value);
//See function STATE_multiplayer_message_write_double()
STATE_IMPORT int STATE_WINAPI STATE_multiplayer_message_read_string(char *string);
//See function STATE_multiplayer_message_write_double()
STATE_IMPORT int STATE_WINAPI STATE_multiplayer_message_write_string(char *string);
//See function STATE_multiplayer_message_write_double()
STATE_IMPORT int STATE_WINAPI STATE_multiplayer_message_write_byte(BYTE value);
//See function STATE_multiplayer_message_write_double()
STATE_IMPORT int STATE_WINAPI STATE_multiplayer_message_read_byte(BYTE *value);
//-------------------------------------------------------//
//======== T H E T R A C K A P I ===================//
//-------------------------------------------------------//
// Track is merely a sequence of points.
// cameras and objects can move on tracks in various ways
// Returns YES or NO.
// YES , if the given handle is a track handle. NO if not.
// If it is not a track 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_TRACK()
STATE_IMPORT int STATE_WINAPI STATE_track_is_track(DWORD track_handle, char *function_asking);
STATE_IMPORT DWORD STATE_WINAPI STATE_track_get_using_name(char *name);
// returns 1 if cyclic else returns 0
STATE_IMPORT int STATE_WINAPI STATE_track_is_cyclic(DWORD track_handle);
// Returns the name of the track.
// 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_track_get_name(DWORD track_handle);
STATE_IMPORT void STATE_WINAPI STATE_track_set_name(DWORD track_handle, char *name);
STATE_IMPORT int STATE_WINAPI STATE_track_get_number_of_points(DWORD track_handle);
STATE_IMPORT DWORD STATE_WINAPI STATE_track_get_first_track(void);
STATE_IMPORT DWORD STATE_WINAPI STATE_track_get_next(DWORD track_handle);
//returns the point in pt[]
// returns VR_ERROR if the index is too big or negative
// else returns OK
STATE_IMPORT int STATE_WINAPI STATE_track_get_point(DWORD track_handle, int point_index, double pt[3]);
//Use this function to change the location of a specific point on the track.
//Parameters:
// track_handle: The track handle
//
// point_index: A value between 0 to (STATE_track_get_number_of_points() -1 )
//
// pt: The X,Y,Z values to set for the given point index.
//
// Return value:
// VR_ERROR if the failed (our of range index)
// OK otherwise.
//
STATE_IMPORT int STATE_WINAPI STATE_track_set_point(DWORD track_handle, int point_index, double pt[3]);
// point element can be 0 or 1 or 2
// 0 means get the x element. 1 ==> y. 2 ==>z
// note that if the point_index or the element number
// are out of range the function returns 0. there is no way
// to know if the 0 is because of error or no.
STATE_IMPORT double STATE_WINAPI STATE_track_get_point_element(DWORD track_handle, int point_index, int point_element);
// Returns the array of points
// You can then access the array your self for getting and setting points
// Be careful not access the array with an out-of-range index
// This could cause your program to crash
// indexes should be in the range 0,1,2 ... ,(number_of_points-1)*3+2
// Access example:
// points_array=STATE_track_get_points(track_handle);
// x=points_array[point_index*3+0];
// y=points_array[point_index*3+1];
// z=points_array[point_index*3+2];
//
// The last index possible is
// array[(number_of_points-1)*3 +2] we have (number_of_points-1) because we start with 0
// to get the number of points do:
// number_of_points=STATE_track_get_number_of_points(track_handle);
// The function will always return the same address (array) for a given track.
STATE_IMPORT double * STATE_WINAPI STATE_track_get_points(DWORD track_handle);
// P is a point anywhere in space
// returns the index to the point on the track that
// is the closest.
// NOTE that if an object or a camera has a track and the track_offset is
// not (0,0,0) then you must do the following to get a correct result
//
// P[0]=P[0]-track_offset[0];
// P[1]=P[1]-track_offset[1];
// P[2]=P[2]-track_offset[2];
// index=STATE_track_find_closest_point_on_track(track, P);
// STATE_track_get_point(track, index, pt);
// pt[0]=pt[0]+track_offset[0];
// pt[1]=pt[1]+track_offset[1];
// pt[2]=pt[2]+track_offset[2];
//
STATE_IMPORT int STATE_WINAPI STATE_track_find_closest_point_on_track(DWORD track_handle, double P[3]);
// Creates a new track.
//
// Parameters:
// points_buffer:
// contains the x,y,z of the points (example: x1,y1,z1, x2,y2,z2, x3,y3,z3 ....)
// note that if number_of_points==3 , we need array with 9 doubles (double points[9] )
//
// track_name:
// The name of the track. Note that if track_name is not unique (there is already another track with the same name),
// the name will be modified so it will be unique. If you use the track name
// then it is a good practice to check the name after the track was created.
// or to make sure in advance that the name is unique.
//
// Example:
//
// double points[9]={ 0,0,0, 100,0,0, 0,0,100};
// DWORD trk=STATE_track_create("trk1", YES, points, 3);
// int num=STATE_track_get_number_of_points(trk); //num should get the value 3
// double pt[3];
// for(int i=0; i<num; i++) {
// STATE_track_get_point(trk, i, pt);
//
// //Do something with the point ...
// }
//
STATE_IMPORT DWORD STATE_WINAPI STATE_track_create(char *track_name, int is_cyclic, double *points_buffer, int number_of_points);
// It is the responsibility of the user that the points buffer is big enough for the number of points.
// The given buffer will be copied inside the engine
// points_buffer contains the x,y,z of the points (example: x1,y1,z1, x2,y2,z2, x3,y3,z3 ....)
// note for example that if the number_of_points==3 then we will need an array with 9 doubles (double points[9] )
STATE_IMPORT void STATE_WINAPI STATE_track_set_points_buffer(DWORD track_handle, double *points, int number_of_points);
//It is the responsibility of the user that the points buffer is big enough.
// if the set number of points is bigger than the room in the points buffer, the
// program might crash.
STATE_IMPORT void STATE_WINAPI STATE_track_set_number_of_points(DWORD track_handle, int number_of_points);
// deletes a track
// be carful not to use this handle after it was deleted
// a good practice is to do like that:
// STATE_track_delete(my_track);
// my_track=NULL;
//
STATE_IMPORT void STATE_WINAPI STATE_track_delete(DWORD track_handle);
STATE_IMPORT void STATE_WINAPI STATE_track_delete_all(void);
// sending YES will write the given track to file after call to STATE_engine_save() with SAVE_ONLY_WHATS_NEEDED
// Note that it if STATE_engine_save() is called without SAVE_ONLY_WHATS_NEEDED, all the tracks will be saved
// sending NO will cause STATE_engine_save() not to save this track (only if SAVE_ONLY_WHATS_NEEDED is used)
// The default value is NO
// see also STATE_animation_set_save_flag()
STATE_IMPORT void STATE_WINAPI STATE_track_set_save_flag(DWORD track_handle, int yes_no_flag);
// returns YES or NO
// The default value is NO
// see STATE_track_set_save_flag() for more details
STATE_IMPORT int STATE_WINAPI STATE_track_get_save_flag(DWORD track_handle);
//-------------------------------------------------------//
//======== T H E B A C K G R O U N D A P I =============//
//-------------------------------------------------------//
// Background is the background on which the world is rendered.
// The idea is that you give a bitmap and the engine automatically
// deals with it. For example when you turn around the engine shift the background
// image so it is not noticeable that it isnt part of the world.
// The engine also sees to it that you can turn 360 degrees without
// seeing the background edges ...
// Returns YES or NO.
// YES , if the given handle is a background handle. NO if not.
// If it is not a background 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_BACKGROUND()
STATE_IMPORT int STATE_WINAPI STATE_background_is_background(DWORD background_handle, char *function_asking);
// The given name should be in capital letters
// If the return value is 0 it means
// that there is no background with the given name.
STATE_IMPORT DWORD STATE_WINAPI STATE_background_get_handle(char *background_name);
STATE_IMPORT DWORD STATE_WINAPI STATE_background_get_first_background(void);
STATE_IMPORT DWORD STATE_WINAPI STATE_background_get_next(DWORD background_handle);
//creates a new background
//Returns a handle to the new background
//arguments:
// name: any string will do , example "my_sky"
// bitmap_handle: see STATE_bitmap_load() for getting the handle
// Note that you have to call STATE_background_use() so that the background will be shown
STATE_IMPORT DWORD STATE_WINAPI STATE_background_create(char *name, DWORD bitmap_handle);
STATE_IMPORT void STATE_WINAPI STATE_background_set_name(DWORD background_handle, char *name);
// Returns the name of the background.
// 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_background_get_name(DWORD background_handle);
//The purpose of the distance value is to make the background act more realistic
//by moving up and down according to the camera movement
//The distance value:
//The bigger this number is, the more apparent are the
//changes in the height of the background,
//when the height of the camera changes. The background moves
//up and down according to the height of the camera, to make it
//look real (example: If you have a car going up or down a hill, the sky's
//height must change(the sky is the background).)
// example: STATE_background_set_distance(bg_handle, 30000);
STATE_IMPORT void STATE_WINAPI STATE_background_set_distance(DWORD background_handle, double value);
//The purpose of the distance value is to make the background act more realistic
//by moving up and down according to the camera movement
//The distance value:
//The bigger this number is, the more apparent are the
//changes in the height of the background,
//when the height of the camera changes. The background moves
//up and down according to the height of the camera, to make it
//look real (example: If you have a car going up or down a hill, the sky's
//height must change(the sky is the background).)
STATE_IMPORT double STATE_WINAPI STATE_background_get_distance(DWORD background_handle);
//The bigger this number is, the background image will start from a higher
//place. The default is 0
STATE_IMPORT void STATE_WINAPI STATE_background_set_bottom(DWORD background_handle, double value);
STATE_IMPORT double STATE_WINAPI STATE_background_get_bottom(DWORD background_handle);
//return OK on success else VR_ERROR
// a value of 100 means normal brightness at the bottom of the background
// a value of 50 means a color that is the average between the background
// and the atmosphere color.
// a value of 200 means twice as bright than the original hue.
// feel free to test with different values.
STATE_IMPORT int STATE_WINAPI STATE_background_set_bottom_intensity(DWORD background_handle, double value);
STATE_IMPORT double STATE_WINAPI STATE_background_get_bottom_intensity(DWORD background_handle);
//return OK on success else VR_ERROR
// the changes in the intensity for each scan line
// going from the bottom of the background up.
// 0 means no changes.
STATE_IMPORT int STATE_WINAPI STATE_background_set_intensity_step(DWORD background_handle, double value);
STATE_IMPORT double STATE_WINAPI STATE_background_get_intensity_step(DWORD background_handle);
STATE_IMPORT void STATE_WINAPI STATE_background_delete(DWORD background_handle);
STATE_IMPORT void STATE_WINAPI STATE_background_delete_all(void);
// Tell the engine to use the given background.
// A NULL handle means that we dont want to use any background
STATE_IMPORT void STATE_WINAPI STATE_background_use(DWORD background_handle);
//Returns the background handle that is currently in use
STATE_IMPORT DWORD STATE_WINAPI STATE_background_get_current_background(void);
// sending YES will write the given background to file after call to STATE_engine_save() with SAVE_ONLY_WHATS_NEEDED
// Note that it if STATE_engine_save() is called without SAVE_ONLY_WHATS_NEEDED, all the backgrounds will be saved
// sending NO will cause STATE_engine_save() not to save this background
// The default value is NO
// Note that if it is used it will be saved no matter what the flag is
// see also STATE_animation_set_save_flag()
STATE_IMPORT void STATE_WINAPI STATE_background_set_save_flag(DWORD background_handle, int yes_no_flag);
// returns YES or NO
// The default value is NO
// see STATE_background_set_save_flag() for more details
STATE_IMPORT int STATE_WINAPI STATE_background_get_save_flag(DWORD background_handle);
//Replace the bitmap of the background with the given bitmap.
//See also STATE_bitmap_load()
STATE_IMPORT void STATE_WINAPI STATE_background_set_bitmap(DWORD background_handle, DWORD bitmap_handle);
// Returns a handle to the bitmap that is in use by the given background.
STATE_IMPORT DWORD STATE_WINAPI STATE_background_get_bitmap(DWORD background_handle);
// Returns the name of the bitmap. Note the difference between calling STATE_background_get_bitmap()
//and then getting the bitmap name using STATE_bitmap_get_name()
// The difference is that here we will get the name even if the bitmap was not loaded yet.
// For example when our world is on the Internet then we first download the world and only then
// the bitmaps are downloaded. If we call this function we would still get the name even though the bitmap wasn't
// loaded to the engine yet. If you didnt understand this explanation then relax, it is not so important.
STATE_IMPORT char * STATE_WINAPI STATE_background_get_bitmap_name(DWORD background_handle);
//-------------------------------------------------------//
//======== T H E E N T I T Y A P I =============//
//-------------------------------------------------------//
//This API contains functions that already exist in other STATE APIs.
//The idea is that one function can serve all API. For example the STATE_entity_get_name()
//can get the name of a camera, an object a group etc ... Some people use this API a lot and
//other dont use it at all. Both ways are fine.
//Gets the name of the entity.
//entity could be a handle to one of the following camera,group,object,track,background,bitmap
//The requested name is copied to the given buffer.
//buffer_size is the buffer size in bytes. If this value is shorter than the requested name
//then the name will be truncated.
//The return value is the length of the name
STATE_IMPORT int STATE_WINAPI STATE_entity_get_name(DWORD entity, char *buffer, int buffer_size);
//Entity could be a handle to a polygon an object or a group.
//Returns the number of bitmaps that were created and assigned to a polygon.
//For more details see STATE_polygon_create_lightmap(), STATE_group_create_light_map()
STATE_IMPORT int STATE_WINAPI STATE_entity_create_lightmap(DWORD entity, int max_bm_side, int min_lightmap_size, double sample_rate, int force_ray_tracing, int bitmap_number);
//-------------------------------------------------------//
//======== T H E 3 D C A R D A P I =============//
//-------------------------------------------------------//
// This API include specific functions for working with the 3D accelerator.
// We tried to make the existence of the card transparent to the programmer
// so that things should work exactly the same with card or without.
//Note that some of the function exist also in the engine API
//those function do exactly the same. It is preferred if you use just the function from this
//API.
// return YES or NO
STATE_IMPORT int STATE_WINAPI STATE_3D_card_check_hardware_support(void);
// Get YES or NO. Returns OK or VR_ERROR
// If gets YES, the function will look for a 3D card installed on the computer
// if it wont find, the function will return VR_ERROR.
// It is a good practice to call STATE_3D_card_use(NO);
// before you exit your application.
// The default is NO.
//
// Remarks:
// The software rendering works much faster at 16bit color depth.
// If your end users might not have a 3D Card you should consider
// to call STATE_engine_set_color_depth() at the beginning of the program to set 16bit mode color depth.
// When the program exits the engine will switch back to what ever mode was before
//
STATE_IMPORT int STATE_WINAPI STATE_3D_card_use(int YES_or_NO);
#define CARD3D_SOFTWARE_EMULATION 1 //Use it to set DirectX software emulation.
//This is usually a lot slower than STATE Software rendering.
//The advantage is that it will look exactly like DirectX hardware rendering.
#define CARD3D_NORMAL 2
#define CARD3D_OFF 4//in this case it will use STATE software rendering
//which is equivalent to STATE_3D_card_use(NO)
//This function gives more possibilities to the way the 3d card will operate.
//render_mode can be anyone of the options above (CARD3D_SOFTWARE_EMULATION, CARD3D_NORMAL, CARD3D_OFF)
//set_full_screen can be YES or NO.
//resolution_x, resolution_y, color_depth are only relevant if set_full_screen==YES
// color_depth could be 16 or 32 the default is 16.
//use_secondary_card can be YES or NO. In many computers there are more than one 3D card
// for example computers with VoodooII card have also another card. Usually the other
// card has some inferior 3D capabilities though. In those cases it is important to let the user choose
// if he wants to use his secondary or his primary card. Note that the primary card isn't necessarily the better 3D card.
//
// Examples:
// A) STATE_3D_card_use_detailed(CARD3D_NORMAL, NO, 0, 0, 0, NO);
// B) STATE_3D_card_use_detailed(CARD3D_NORMAL, YES, 800, 600, 16, NO);
//
// Remarks:
// The software rendering works much faster at 16bit color depth.
// If your end users might not have a 3D Card you should consider
// to call STATE_engine_set_color_depth() at the beginning of the program to set 16bit mode color depth.
// When the program exits the engine will switch back to what ever mode was before
//
STATE_IMPORT int STATE_WINAPI STATE_3D_card_use_detailed(int render_mode, int set_fullscreen, int resolution_x, int resolution_y, int color_depth, int use_secondary_card);
//Returns YES if a 3D accelerator card is in use.
//Returns NO if software rendering is used.
STATE_IMPORT int STATE_WINAPI STATE_3D_card_is_used(void);
//Set full screen mode and the desktop resolution
// Returns OK or VR_ERROR
// here are four Examples:
// STATE_3D_card_set_full_screen_mode(1024,768);
// STATE_3D_card_set_full_screen_mode(800,600);
// STATE_3D_card_set_full_screen_mode(640,480);
// STATE_3D_card_set_full_screen_mode(320,200);
STATE_IMPORT int STATE_WINAPI STATE_3D_card_set_full_screen_mode(int resolution_x, int resolution_y);
//Returns YES if the 3D card is programed to use fullscreen.
STATE_IMPORT int STATE_WINAPI STATE_3D_card_is_full_screen_mode(void);
//This is the default. Can be called instead, before or after STATE_3D_card_use(YES);
//returns OK or VR_ERROR
STATE_IMPORT int STATE_WINAPI STATE_3D_card_set_window_mode(void);
//Hides the driver selection popup
//The default is that this popup is visible.
// Example:
// STATE_3D_card_hide_driver_selection_window(YES);
STATE_IMPORT void STATE_WINAPI STATE_3D_card_hide_driver_selection_window(int YES_or_NO);
//Controls whether the driver selection popup will pop
//when the 3D card is put to work.
//Returns YES or NO.
// See also STATE_3D_card_hide_driver_selection_window()
STATE_IMPORT int STATE_WINAPI STATE_3D_card_is_driver_selection_window_visible(void);
//Calling this function with a YES allow the engine to use DirectX
//software emulation when there is no 3D accellerator card.
//Use this function if you want to ensure a homogenous look to your
//application with or without a 3D card. The disadvantage of DirectX
//software emulation is that is is a lot slower then STATE software rendering (The default).
//In the case that your application uses a big 3D world then the DirectX
//emulation will probably be too slow. If it is just an object that
//is shown then using this function will probably give a good result.
//
//The default is NO.
//Example STATE_3D_card_allow_software_emulation(YES);
STATE_IMPORT void STATE_WINAPI STATE_3D_card_allow_software_emulation(int YES_or_NO);
#define BILINEAR_FOR_PRIMARY_TEXTURE_ONLY 8
#define BILINEAR_FOR_SECONDARY_TEXTURE_ONLY 16
#define BILINEAR_USE_3D_CARD_DEFAULTS 32
// Function level of importance = High.
//
// The function turns OFF or ON the bilinear filtering.
// The effect is visible only when the 3D card is on.
// Bilinear filtering is a technique for getting better looking textures. When bilinear
// filtering is ON, it removes the pixelization effect from close textures.
// The default is ON. If preformance are very important you should consider
// shutting bilinear filltering off.
// Bilinear filtering could also be set separatelly for each polygon using
// STATE_polygon_set_bilinear_filtering() (this will overide any setting made by STATE_3D_card_set_bilinear_filtering() )
// parameters:
// bilinear_mode:
// ON - The default. Turns on bilinear filtering.
// OFF - Turns off bilinear filtering
// BILINEAR_FOR_PRIMARY_TEXTURE_ONLY - Turns bilinear only for the primary texture (each polygon could have two textures, the primary and the secondary)
// BILINEAR_FOR_PRIMARY_SECONDARY_ONLY - Turns bilinear only for the secondary texture (each polygon could have two textures, the primary and the secondary)
//Example:
// STATE_3D_card_set_bilinear_filtering(OFF);
//
// See also STATE_polygon_set_bilinear_filtering()
STATE_IMPORT void STATE_WINAPI STATE_3D_card_set_bilinear_filtering(int bilinear_mode);
//The following function gives direct access to the Direct3D DirectDraw surfaces
//Advanced users who are familiar with DirectDraw and Direct3D can
//use this function to speed up 2D sprite drawing and other effects.
//or to add code that was written with DirectX to a STATE application.
//If you are not familiar with Direct3D then you better skip this function.
//Note that this function is very fast so there it is OK to call it several times for each render iteration.
//
// parameters:
//
// IDirectDraw4 *IDirectDraw4_object
// THis is the DirectDraw object (of type pointer to IDirectDraw4)
// Through this parameters the Direct Draw interface could be accessed.
//
// IDirect3D3 *IDirect3D3_object
// This is the Direct3D object (of type pointer to IDirect3D3)
// Through this parameters the Direct3D interface could be accessed.
//
// IDirect3DDevice3 *D3D_device
// The Direct3D devices interface
//
//
// IDirectDrawSurface4 *IDirectDrawSurface4_primary_surface
// The primary surface
//
// IDirectDrawSurface4 *IDirectDrawSurface4_back_surface
// The secondary surface
//
// IDirectDrawSurface4 *IDirectDrawSurface4_zbuffer
// The surface used to store the ZBuffer
//
// IDirect3DViewport3 *IDirect3DViewport3_viewport
// The view port to which the rendering is done.
//
//
//Example A:
//
// void *DD_void;
// void *D3D_void;
// void *D3D_device_void;
// void *primary_void;
// void *secondary_void;
// void *zbuffer_void;
// void *viewport_void;
//
// STATE_3D_card_get_directx_internals(&DD, &D3D, &D3D_device,&primary, &secondary, &zbuffer, &viewport);
//
// //Do some custing so we can use the varibles
// IDirectDraw4 *DD=(IDirectDraw4 *)DD_void;
// IDirect3D3 *D3D=(IDirect3D3 *)D3d_void;
// IDirect3DDevice3 *D3D_device=(IDirect3DDevice3 *)D3D_device_void;
// IDirectDrawSurface4 *primary=(IDirectDrawSurface4 *)primary_void;
// IDirectDrawSurface4 *secondary=(IDirectDrawSurface4 *)secondary_void;
// IDirectDrawSurface4 *zbuffer=(IDirectDrawSurface4 *)zbuffer_void;
// IDirect3DViewport3 *viewport=(IDirect3DViewport3 *)viewport_void;
//
//Example B
// Here is a small example for doing bitblt assuming the the arguments were already casted
//
// if( is_in_full_screen_mode )
// return (m_pddsFrontBuffer->Flip( NULL, DDFLIP_WAIT );
//
//
// // Else, we are in windowed mode, so perform a blit.
// return m_pddsFrontBuffer->Blt( &m_rcScreenRect, m_pddsBackBuffer, &m_rcViewportRect, DDBLT_WAIT, NULL );
//
STATE_IMPORT void STATE_WINAPI STATE_3D_card_get_directx_internals(void **IDirectDraw4_object, void **IDirect3D3_object, void **IDirect3DDevice3_device, void **IDirectDrawSurface4_primary_surface, void **IDirectDrawSurface4_back_surface, void **IDirectDrawSurface4_zbuffer, void **IDirect3DViewport3_viewport);
//Returns YES or NO. YES is returned if multiple texture blending is supported by the 3D card
STATE_IMPORT int STATE_WINAPI STATE_3D_card_is_multiple_texture_blending_supported(void);
// General
// --------
// Set the antialiasing mode ON or OFF.
// This is an important function that can enhance graphic quality.
// Usually turning antialiasing ON will slow down rendering though modern
// 3D cards such as GeForce 4 (Ti or MX) and newer cards have good support
// for antialiasing.
//
// What is antialiasing ?
// ----------------------
// Reduction of jagged edges by the use of intermediate shades, smoothing of aliasing.
//
//
// Usage:
// ------
// Could be call before using the 3D card or afterwords.
// Has no effect when using software rendering.
// The default is OFF.
//
// Example:
// STATE_3D_card_set_antialiasing(ON);
//
STATE_IMPORT void STATE_WINAPI STATE_3D_card_set_antialiasing(int ON_or_OFF);
//Returns whether the 3D card supports antialiasing (SORTINDEPENDENT).
STATE_IMPORT int STATE_WINAPI STATE_3D_card_is_antialiasing_supported(void);
//-------------------------------------------------------//
//======== T H E U T I L T I E S A P I =============//
//-------------------------------------------------------//
// The function in this API have nothing to do with the
// STATE VR_Engine ! You can think of them as an extension to the
// WIN32 API.
// They are here because they are useful in many applications especially
// applications that use lots of graphics.
//Loads a file into memory.
//returns a pointer to the allocated memory and the size of the file
//If the file could not be loaded a NULL is returned
//This file can be also treated as a string (there will always be a terminating NULL ).
//Example:
// int file_size;
// char *buff=(char *)STATE_utilities_file_to_memory("help.txt", &file_size);
// MessageBox(NULL,buff,"Help", MB_OK);
// STATE_utilities_free_file_memory(buff);
STATE_IMPORT BYTE *STATE_WINAPI STATE_utilities_file_to_memory(char *file_name, int *file_size);
//Used together with STATE_utilities_file_to_memory() to free memory
//that we don't need any more.
//note that "void *mem_ptr" is a pointer to void which means
//that it will accept any type of pointer.
STATE_IMPORT void STATE_WINAPI STATE_utilities_free_file_memory(void *mem_ptr);
// stretch a bitmap on the given window
// border_to_leave is usually 0. We can give a
// different value if we want to keep the window
// frame lines visible.
// if border_to_leave==0 then all the window
// will be covered by the bitmap. if border_to_leave
// is equal to 2 (for example) then there will be
// a border of two pixels left from each side.
STATE_IMPORT void STATE_WINAPI STATE_utilities_paste_resource_bitmap(HWND hwnd, UINT bitmap_resource_id, int border);
// You can use STATE_utilities_load_bitmap_from_file() to get a handle to the bitmap and then to use this function
STATE_IMPORT void STATE_WINAPI STATE_utilities_paste_bitmap(HWND hwnd, HBITMAP bitmap_handle, int border);
// This is a very useful function.
// It can be used for pasting 2D bitmaps on the rendered image
// For example an image denoting the health condition of the player
// or the existence of ammunition
// The function copies a bitmap on the given device context.
// Use STATE_utilities_load_bitmap_from_file() to get a handle to the bitmap (HBITMAP)
// Use STATE_engine_render_on_dc() to get the device context handle (HDC hdc)
//
// Parameters:
//
// hdc: a handle to the device context. usually you would obtain this
// handle from calling hdc=STATE_engine_render_on_dc()
//
// hbm: a HBITMAP handle of the bitmap. you can use
// STATE_utilities_load_bitmap_from_file() to get
// the handle.
//
// x,y: the coordinate where the bitmap should be placed
//
// bm_stretch_width,
// bm_stretch_height: Using these params you can stretch the bitmap
// If you dont want to stretch the bitmap give -1
//
//
// Examples:
//
// A)
// //Copy the bitmap to the top left corner of the window
// STATE_utilities_copy_bitmap_on_dc(hdc, hbm, 0,0, -1,-1);
//
// B)
// //Copy the bitmap to the top left corner of the window
// //The bitmap will be stretched to a 100x100 square size (size in pixels)
// STATE_utilities_copy_bitmap_on_dc(hdc, hbm, 0,0, 100, 100);
//
STATE_IMPORT void STATE_WINAPI STATE_utilities_copy_bitmap_on_dc(HDC hdc, HBITMAP hbm, int x, int y, int bm_stretch_width, int bm_stretch_height);
// This function has nothing to do with STATE graphics engine
// Think of it as an extension to the Win32 API.
//
//It is also possible to load a jpeg file (*.jpg).
// If bitmap_file_name ends with ".jpg" and there is no file with the same name only with a .bmp extension
// in the same directory then the function will load the jpg file
//
// Note the difference between this command and STATE_bitmap_load()
// STATE_bitmap_load() command loads a bitmap into the engine, while STATE_utilities_load_bitmap_from_file()
// is just an extension to the Win32 API making it easy to load a bitmap from
// the disk and to get its HBITMAP handle (a Win32 type)
//
STATE_IMPORT HBITMAP STATE_WINAPI STATE_utilities_load_bitmap_from_file(char *bitmap_file_name);
// This function has nothing to do with STATE graphics engine
// Think of it as an extension to the Win32 API.
//
// bitmap_file_name should have a bmp extension.
// The file is always saved in 8 bit color depth.
// To save in 24 bit color use STATE_utilities_save_bitmap24()
//returns OK or VR_ERROR
STATE_IMPORT int STATE_WINAPI STATE_utilities_save_bitmap(HBITMAP hbm, char *bitmap_file_name);
//Exactly like STATE_utilities_save_bitmap(), only that it saves in 24 bit per pixel color depth (rather than 8)
STATE_IMPORT int STATE_WINAPI STATE_utilities_save_bitmap24(HBITMAP hbm, char *bitmap_file_name);
//Creates a new bitmap file
//The new bitmap file is a resampled version of the source bitmap file
//The given bitmap file should be in 8 bit per pixel or 24 bit per pixel file format.
// The return value is OK or VR_ERROR
// Example:
// STATE_utilities_resample_bitmap("C:\STATE\logos\biglogo.bmp", "..\small_logo.bmp", 32,32);
// This would create a 32x32 bitmap file in the name small_logo.
STATE_IMPORT int STATE_WINAPI STATE_utilities_resample_bitmap(char *source_bitmap_file, char *new_bitmap_file_name, int new_width, int new_height);
//convert a jpg files into 256 colors bitmap
// returns OK or VR_ERROR;
//example:
// rc=STATE_utilities_jpg2bmp("bitmapsjpeghorse.jpg");
// This will create a 256 colors bitmap with the name horse.bmp
// the bitmap will be created in the same directory of horse.jpg
STATE_IMPORT int STATE_WINAPI STATE_utilities_jpg2bmp(char *jpg_file_name);
//Like STATE_utilities_jpg2bmp() only the other way around.
// Note that the bitmap should be 256 colors
STATE_IMPORT int STATE_WINAPI STATE_utilities_bmp2jpg(char *bmp_file_name);
// The output format is determined according to the extension of the output file
// The same with the input file format.
// example STATE_utilities_convert_3d_formats("test.x", "test.mft", "", SAVE_BITMP_AS_JPG);
// Note that this function just do STATE_engine_load_world() and STATE_engine_save()
// and that means that any world that is currently in the engine will be unloaded
// and the input_file_name world will be.
STATE_IMPORT int STATE_WINAPI STATE_utilities_convert_3d_formats(char *input_file_name, char *world_directory_path, char *bitmaps_directory_path, char *output_file_name, int save_flags);
//Convert a 16bit rgb color to 24bit rgb. The result is return through red,green and blue.
//See also STATE_bitmap_get_palette();
STATE_IMPORT void STATE_WINAPI STATE_utilities_rgb16_to_rgb24(WORD rgb16, BYTE *red, BYTE *green, BYTE *blue);
//Returns YES or NO.
//Returns YES if the operating system is Windows 98 or above (i.e Windows me , windows 2000 etc ...)
STATE_IMPORT int STATE_WINAPI STATE_utilities_is_windows98_or_later(void);
//Saves the content of the given window as a bitmap on the disk
// Returns OK or VR_ERROR
// One shouldn't use this function when using the 3D card to render.
// Instead use this combination.
// HBITMAP hbm=STATE_engine_render_on_bitmap(your_window_or_null, your_camera_or_null);
// STATE_utilities_save_bitmap(hbm, "d:\screenshots\shot.bmp");
//
// Example:
//
// HWND hwnd=STATE_engine_get_default_rendering_window_hwnd()
// STATE_utilities_save_screenshot(hwnd, "d:\my_screenshots\flight_sim1.bmp");
//
// Note that the above example is the same as writing STATE_utilities_save_screenshot(NULL, "d:\my_screenshots\flight_sim1.bmp");
//
STATE_IMPORT int STATE_WINAPI STATE_utilities_save_screenshot(HWND rend_win, char *file_name);
// gets an address and display its content
// size is the size of the given buffer in bytes.
// You can use this function for debugging if you have problems interfacing the dll.
STATE_IMPORT void STATE_WINAPI STATE_utilities_test_address(BYTE *mem_address, int size);
//Test receiving a string. the string that is received is "Testing string transfer"
//Returns "Testing string transfer"
STATE_IMPORT char *STATE_WINAPI STATE_utilities_test_string(void);
//popup a dialog with the given string
STATE_IMPORT void STATE_WINAPI STATE_utilities_test_LPSTR(LPSTR str);
//popup a dialog with the given string
STATE_IMPORT void STATE_WINAPI STATE_utilities_test_LPCSTR(LPCSTR str);
//popup a dialog box with the given pointer and the value it points at
STATE_IMPORT void STATE_WINAPI STATE_utilities_test_PDWORD(DWORD *ptr);
//popup a dialog box with the given pointers and the value they point at
STATE_IMPORT void STATE_WINAPI STATE_utilities_test_2PDWORD(DWORD *ptr1, DWORD *ptr2);
// Divides a bitmap into smaller pieces (image cutter)
//
// Parameters:
//
// bitmap_to_cut:
// a bmp file name
//
// fraction_width, fraction_width:
// The size of the each small fraction cut from the big bitmap
//
// name_to_save:
// The pathfilename where to save the fractions.
// example: "D:\my_folder\filename" this will create the bitmaps inside the folder "my_folder"
// and will name them filename1.bmp, filename2.bmp etc ...
//
// force_8bit_output
// The fractions are saved in 8bit format.
//
//
// Return value:
// Returns the number of bitmaps that were created.
//
//
// Example:
//
// //This will divide a big bitmap into 256x256 parts
// STATE_utilities_cut_image("big_bitmap.bmp", 256, 256, "part", NO);
//
// Remarks:
// Almost all 3d cards cant handle bitmaps larger than 1024x1024
// The Voodoo3 card can handle only 256x256 bitmaps (or smaller) !!!
//
// Many 3d cards achieves best performance when bitmaps are at the size of 256x256
// Though in some application 512x512 or 1024x1024 will get better results
// depending on the application developed (you should test it to get suitable size for your application)
//
STATE_IMPORT int STATE_WINAPI STATE_utilities_cut_image(char *bitmap_to_cut, int fraction_width, int fraction_length, char *name_to_save, int force_8bit_output);
//-----------------------------------------------------//
//==+++====== T H E M A T H A P I ===========+++==//
//-----------------------------------------------------//
// The function in this API have nothing to do with the
// STATE VR_Engine ! You can think of them as an extension to the
// WIN32 API.
// They are here because they are useful in many applications especially
// applications that use 3D graphics.
// Constants for the math API
#define ON_PLANE 1//on the same plane
#define IN_BACK_OF_PLANE 2
#define IN_FRONT_OF_PLANE 3
#define CUTS_PLANE 4
#ifndef M_PI
#define M_PI 3.14159265358979323846
#endif
// returns the distance between two points in the power of two
// example: p1=(0,0,0) p2=(10,0,0)
// the distance is 10 so the return value will be 100
// see also STATE_math_get_distance() which is the same only it
// calls sqrt() at the end.
STATE_IMPORT double STATE_WINAPI STATE_math_get_square_distance(double p1[3], double p2[3]);
// returns the distance between two points
// example: p1=(0,0,0) p2=(10,0,0)
// the distance is 10 so the return value will be 10
// If speed is important it is better to use STATE_math_get_square_distance()
// which is much faster because it doesn't do the sqrt()
STATE_IMPORT double STATE_WINAPI STATE_math_get_distance(double p1[3], double p2[3]);
// stores the result in "intersection_point" which is valid in all cases
// pt1 and pt2 are two points on a line
// return value:
// YES if pt1 and pt2 are in different sides of the plane
// in this case intersection_point will be the expected intersection point
// NO if pt1 and pt2 are on the same side of the plane
// in this case intersection_point will be the intersection point if the infinite line that contains p1 and p2
//
// NO if the line is on the plane.
// In this case the intersection point will be pt1
//
// YES, If one edge of the segment is on the plane (and the other one is not).
//
STATE_IMPORT int STATE_WINAPI STATE_math_does_segment_intersect_plane(double pln[4],double pt1[3], double pt2[3], double intersection_point[3]);
// Return the distance between point P and the line going through points A and B.
STATE_IMPORT double STATE_WINAPI STATE_math_get_distance_between_point_and_line(double P[3], double A[3], double B[3]);
// P is a point
// AB is a line
// The result is returned through closest_point_on_line
// closest_point_on_line is the a point on the line defined by A and B that is closest to P
// Returns OK or VR_ERROR (error if point A is equal to point B)
// Example:
// P[0]=1; P[1]=2; P[2]=30;
// A[0]=10; A[1]=20; A[2]=30;
// B[0]=100; B[1]=200; B[2]=300;
// double closest_point_on_line[3];
// STATE_math_get_closest_point_on_line(P,A,B,closest_point_on_line);
STATE_IMPORT int STATE_WINAPI STATE_math_get_closest_point_on_line(double P[3], double A[3], double B[3], double closest_point_on_line[3]);
// return YES or NO
// Returns YES if point pt is on the given line segment
STATE_IMPORT int STATE_WINAPI STATE_math_is_point_on_segment(double pt[3], double segment_start[3], double segment_end[3]);
// Get three points and calculate their plane equation (the plane equation: Ax+By+Cz+D=0 )
// Note that (pln[0],pln[1],pln[2]) are the normal of the plane.
// The direction of the normal (there are two possibilities) is determined according to
// the direction of the points. The Normal will point towards the side in which the points will be in clockwise order
// The return value is OK or VR_ERROR. note that we will get VR_ERROR if
// the points are on the same line or are all equal.
STATE_IMPORT int STATE_WINAPI STATE_math_points_to_plane(double pln[4], double p1[3], double p2[3], double p3[3]);
// Gets a plane equation (Ax+By+Cz+D=0 ) and a point
// and returns the following constants
// ON_PLANE (if the point is on the plane)
// IN_BACK_OF_PLANE
// IN_FRONT_OF_PLANE
// The side which is called front is the side that the normal of the plane points towards)
// (the normal is: N=(pln[0], pln[1], pln[2]);
// the argument thickness is the thickness of the plane (actually half of the width of the plane).
// If for example thickness==6 than all the points that their distance from the plane
// is 6 or less will result a return value of ON_PLANE.
// Usually you will call this function with thickness==0
// But if you want to check whether a point is on the plane you
// should call this function with thickness bigger than 0 (for example 0.0001)
// and thats to avoid floating point errors (if the plane was created using
// three points and you took only 6 decimal places after the decimal point then the
// plane equation wont be 100% accurate, there is also a limit to the accuracy
// of floating points numbers in a binary world)
// You can also call this function with a negative thickness though
// it is not so useful, in this case the half of the space which is considered in front of the plane
// will get bigger ... In this case you will never get ON_PLANE)
// Note also that this function is extremely fast.
STATE_IMPORT int STATE_WINAPI STATE_math_get_plane_point_relations(double pln[4], double pt[3], double thickness);
// Takes three points and returns whether they are in clockwise order or not
// when looking from above (looking in direction 0,0,-1). If all the points
// have the same x or y values then one cant tell (when looking from above) if it is clockwise
// so in this case we look from front (looking in direction 0,0,-1) and if
// that doesn't succeed we look from the right side (looking in direction 0,-1,0)
// Returns YES or NO
// Note that the three points create a plane and from each side of the plane
// what is clockwise is exactly the other way around.
//
// If you want to check if the points are clockwise from a given point
// use STATE_math_get_plane_point_relations() like that
// create a plane from the three points and call the function when the point
// in which you look from is the given point.
STATE_IMPORT int STATE_WINAPI STATE_math_is_clockwise(double p1[3], double p2[3], double p3[3]);
// return if points are in clockwise when
// looking on the three points from the given direction.
// The given direction doesn't have to be normalized.
// see also is_clockwise()
// Returns YES or NO.
STATE_IMPORT int STATE_WINAPI STATE_math_is_clockwise_from_direction(double view_direction[3], double p1[3], double p2[3], double p3[3]);
// Calculates the ray that reflects from a surface according to the
// physic law: the hitting angle is equal to the reflected angle.
// Arguments:
// normal is the normal of the plane that the ray hits.
// hitting_ray is the ray that hits the plane
// the result is given in reflected_ray (the result is normalized)
// return value: OK, or VR_ERROR (in case of an error).
STATE_IMPORT int STATE_WINAPI STATE_math_get_reflected_direction(double normal[3], double hitting_ray[3], double reflecting_ray[3]);
//Returns the scalar product between two vectors.
//The return value is the length of the first vector multiply by
//the length of the second multiplied by the cosine of the angle between the
//two vectors.
//In a formula way it looks like that:
// return value= scalar_product= |vec1|*|vec2|*cos(alpha) . Alpha is the angle between the vectors
//For more information about scalar products see your math book (look for Linear Algebra and vectors)
STATE_IMPORT double STATE_WINAPI STATE_math_product(double vec1[3], double vec2[3]);
//Returns the cross product between vec1 and vec2.
//The result is returned in the argument "result"
//The returned vector is a vector that is perpendicular both to vec1 and vec2
//The length of the returned vector is equal to
//The length of vec1 multiplied by the length of vec2 multiplied by
//the sinus of the angle between the two vectors.
//For more information about scalar products see your math book (look for Linear Algebra and vectors)
STATE_IMPORT void STATE_WINAPI STATE_math_cross(double vec1[3], double vec2[3], double result[3]);
//returns OK or VR_ERROR
//normalize the vector. This means make it a unit vector.
//In other words the direction of the vector will stay the same
//but its length will become one
//example:
// double vec[3]={6,8,0} //length==10
// STATE_math_normalize_vec(vec);
// //Now the vec will be equal to { 0.6, 0.8, 0} (length==1)
STATE_IMPORT int STATE_WINAPI STATE_math_normalize_vector(double vec[3]);
//Returns the length (magnitude) of the vector
STATE_IMPORT double STATE_WINAPI STATE_math_get_vector_length(double vec[3]);
//This is a very powerful function. Beginners will probably never use this function.
//It is used to interpolate values across a polygon. Please note that this function is used together with
// STATE_math_get_interpolated_value_using_equation()
// With STATE_math_calculate_triangle_interpolation_equation() we build an equation
// and with STATE_math_get_interpolated_value_using_equation() we query for values using the equation we
// have already constructed.
// Return values.
// If an error occurred it returns VR_ERROR. On success it will return the type of the equation that
// was created. We shouldn't care about this value though it is important that we keep it
// because later we will have to send it to STATE_math_get_interpolated_value_using_equation();
// This function also returns the resulted equation through the result_equation argument.
// Again we shouldnt care at all about what this means though we should save it for calling
// STATE_math_get_interpolated_value_using_equation()
//
// Arguments:
// double xyz_of_3_points[3][3] - Three points of the polygon that will be used for interpolating. For example:
// xyz_of_3_points[0][0] X value of the first point
// xyz_of_3_points[0][1] Y value of the first point
// xyz_of_3_points[1][2] Z value of the SECOND point
//
// double value_to_interpolate[3]
// The values to be interpolated.
// value_to_interpolate[0] - The value from the first point (for example the point bitmap_x coord)
// value_to_interpolate[1] - The value from the second point
//
// double polygon_plane[4] - the polygon plane. Use STATE_polygon_get_plane() to get it.
//
// double result_equation[4] - Through this argument the computed equation is returned.
//
//Example,
//Lets say that we have a polygon and a point x,y,z on the plane of the polygon. We want
//to know what should be the point bm_x,bm_y values.
//Using this function we can build an equation that given any x,y,z it will return the
//appropriate bm_x of that point. To build the equation we need to take three points of the polygon
//and their bm_x values.
// xyz_of_3_points[0][0]=1 ; //X value of first point
// xyz_of_3_points[0][1]=2; //Y value of first point
// xyz_of_3_points[0][2]=3; //Z value of first point
//
// xyz_of_3_points[1][0]=4 // X value of second point
// and so on for the three points....
//
// value_to_interpolate[0]=0 ; // bm_x value of the first point
// value_to_interpolate[1]=1 ; // bm_x value of the second point
// value_to_interpolate[2]=0 ; // bm_x value of the third point
//
// double polygon_plane[4];
// STATE_polygon_get_plane(my_polygon, polygon_plane); //getting the polygon plane
//
// double result_equation[4];
// int equation_type;
// equation_type=STATE_math_calculate_polygon_interpolation_equation(xyz_of_3_points, value_to_interpolate, polygon_plane, result_equation);
//
// //We have now created an equation for interpolating the bitmap_x coordinate over our polygon.
// //The equation_type and the result_equation are like a black box for us.
//
// Now lets use the equation and calculate the bitmap_x coordinate in the point x,y,z (that should be on the polygon plane)
// double xyz[3]= {1,2,3} //a point on the polygon's plane
// double bitmap_x=STATE_math_get_interpolated_value_using_equation(xyz, result_equation, equation_type);
//
// Note that for getting the bitmap_y coord of the same point we need to build another equation for the bitmap_y values.
STATE_IMPORT int STATE_WINAPI STATE_math_calculate_polygon_interpolation_equation(double xyz_of_3_points[3][3], double value_to_interpolate[3], double polygon_plane[4], double result_equation[4]);
//Returns the interpolated value according to the given equation.
//Before using this function one must construct an equation for the polygon using STATE_math_calculate_polygon_interpolation_equation
// double xyz[3]
// A point on the polygon plane that we want get the interpolated value.
// double equation[4]
// The equation as was calculated by STATE_math_calculate_polygon_interpolation_equation()
// The meaning of this equation should not concern the user.
// int equation_type
// The equation_type as was returned by STATE_math_calculate_polygon_interpolation_equation()
// This is also used for internal purposes and should have no meaning for the user.
STATE_IMPORT double STATE_WINAPI STATE_math_get_interpolated_value_using_equation(double xyz[3], double equation[4], int equation_type);
//-----------------------------------------------------//
//======== T H E P R O F I L E R A P I =============//
//-----------------------------------------------------//
// One of the most important issue in many applications that use 3D graphics
// is Performances.
// This API makes it extremely easy to time any function (not just STATE's functions)
// using two macros.
// Here is an example of how to do it.
//
// STATE_START_TAKING_TIME("2d point to 3D"); //The text that is given here will appear in the log file profiling summary // any_function_that_you_would_like_to_time(...); //calling the function that we want to time // STATE_STOP_TAKING_TIME(); // // Note that the result of the profiling will be written automatically // to the log file (look for the file log.log in your executable working directory) // Note also that these macros will only work in C++, when writing in C // do this instead: // // static int time_id=-1; // time_id=STATE_profiler_start_measuring(time_id,"some text"); // any_function_that_you_would_like_to_time(...); //calling the function that we want to time (you can any function not just functions of STATE) // STATE_profiler_end_measuring(time_id); STATE_IMPORT int STATE_WINAPI STATE_profiler_start_measuring(int time_id, char *name); STATE_IMPORT void STATE_WINAPI STATE_profiler_end_measuring(int time_id); #define STATE_START_TAKING_TIME(name) { static int time_id=-1; time_id=STATE_profiler_start_measuring(time_id, name); #define STATE_STOP_TAKING_TIME() STATE_profiler_end_measuring(time_id); } //-----------------------------------------------------// //======== H E L P A P P E N D I C E S ===========// //-----------------------------------------------------// // The *.flt file format // --------------------- /* example *.flt file: 255 255 0 4000 3 30000 3 20000 In the first line there is the RGB of the transparent color ( actually it is BGR the blue comes first then the green the the red). In the second line there is the scope/interval of the transparent color in other words if we do distance=(r1-r2)^2 + (g1-g2)^2 + (b1-b2)^2 when ^2 means the power two. r1,g1,b1 is the transparent color rgb (r2,g2,b2) is a color from the bitmap. we now define how close this color can be to the transparent color In the third line and till the end there are 2 integers in each line; lets call them n and d after this program converts all the colors that are near the transparent. We make another round where we take all the colors that have n transparent neighbors and convert them to transparent this time we allowed a the distance to be up to d if there is no third line it is also OK (it wont do a second path) the next lines are similar to the third line each additional line will cause another filtering pass); */ #ifdef __cplusplus } #endif #endif STATE_H