diff options
Diffstat (limited to 'doc/documentation.md')
| -rw-r--r-- | doc/documentation.md | 961 |
1 files changed, 961 insertions, 0 deletions
diff --git a/doc/documentation.md b/doc/documentation.md new file mode 100644 index 0000000..1361005 --- /dev/null +++ b/doc/documentation.md @@ -0,0 +1,961 @@ +# SMELT API documentation +(API Level 3) + +## Table of contents +1. [Overview](#overview) +2. [History](#history) +5. [Macros](#macros) +3. [Data Types](#types) +4. [Core Functions](#core) +5. [Extensions](#extensions) +7. [Implementation details](#implementation) +6. [General considerations](#considerations) + +## Overview <a name="overview"></a> +SMELT is a wrapper class for hardware-accelerated graphics rendering, +input handling and optionally, audio outputting. It works on X11, +wayland and Windows. (Not tested on macOS because I don't use Mac.) + +Currently, two implementations of SMELT exist. One uses SDL and the +other uses GLFW. The implementation using GLFW is further divided into +a OpenGL 1.2/2.1 version and a OpenGL 3.2 version. + +## History <a name="history"></a> +SMELT is emerged from [hge-unix](https://icculus.org/hge-unix/), which +in turn was a port of HGE (Haaf's Game Engine) to MacOS X and UNIX. +Initially, I use hge-unix for my BLR series games. However starting from +an early testbed version of the still unreleased BLR 3, some 3D +rendering is required. So I added simple 3D scene rendering to hge-unix +and the original Windows version. I also wrote a TTF rendering module +for HGE and hge-unix. Finally, I decided to fork it. + +After that, SMELT got new functionalities, new ports, and most +importantly, the code looks less messed up _to me_. However if you have +ever used HGE, you may still find the API of SMELT familiar. + +## Macros <a name="macro"></a> +- `ARGB(a,r,g,b)`: Generates a hardware color with the specificed values. +- `RGBA(r,g,b,a)`: Same as ARGB, with different parameter order. +- `GET<A|R|G|B>(col)`: Extract alpha/red/green/blue value from a hardware color. +- `SET<A|R|G|B>(col,a|r|g|b)`: Set alpha/red/green/blue value of a hardware color. + +- `PI`: `3.14159265358979323846f` + +- `BLEND_ALPHAADD/BLEND_ALPHABLEND`: Alpha blending methods. +- `BLEND_COLORADD/BLEND_COLORMUL/BLEND_COLORINV`: Color blending methods. +- `BLEND_ZWRITE/BLEND_NOZWRITE`: Depth test options. + +The `BLEND_*` macros of the different types can be or'd together. + +- `FPS_FREE/FPS_VSYNC`: Special fps values. +- `INPUT_*`: Input event types. +- `PRIM_*`: Primitive types. +- `SMINP_*`: Key modifiers. These can be or'd together. +- `SMK_*`: Key scan codes. +- `SMKST_*`: Key states. +- `TPOT_*, TFLT_*`: Texture Options. + +- `SMELT_APILEVEL`: SMELT api version. + +## Data Types <a name="types"></a> +- `DWORD`: equivalent to `uint32_t` +- `WORD`: equivalent to `uint16_t` +- `BYTE`: equivalent to `uint8_t` +- `smHook`: (*bool)() function pointers used as callbacks. +- `SMCHN`: Represent a channel of sound playback. +- `SMSFX`: Represent a sound effect. +- `SMTEX`: Opaque texture type. +- `SMTRG`: Opaque render target type. + +`smInpEvent`: Input event structure. + +- `chcode`: Char code. +- `sccode`: Key scan code. +- `type`: Input event type. The macros `INPUT_*` are used. +- `flag`: Modifiers. Use bitwise and (`&`) with a `SMINP_*` value to +test for a modifier. +- `wheel`: Wheel motion. +- `x,y`: Mouse position. + +`smVertex`: Vertex structure. + +- `x,y,z`: Position. `z` can be used for depth testing in 2D mode. +- `col`: Vertex color. +- `tx,ty`: Texture coordinates. + +`smTriangle`: Triangle primitive structure. + +- `v[3]`: Vertices of the triangle. +- `tex`: Texture of the triangle. +- `blend`: Blend mode of the triangle. The macros `BLEND_*` are used. + +`smQuad`: Quadrilateral primitive structure. + +- `v[4]`: Vertices of the quadrilateral. +- `tex`: Texture of the quadrilateral. +- `blend`: Blend mode of the quadrilateral. The macros `BLEND_*` are used. + +WARNING: Quadrilaterals are treated as two triangles internally. +You may get unwanted results if the quadrilateral is not a parallelogram. + +`smTexRect`: Texture rectangle sturcture. + +- `x,y`: Top left coordinate of the texture used. +- `w,h`: Width & height of the texture used. + +`smHandler`: Alternative handler class. + +- `virtual bool handlerFunc()=0` + +Implement the `handlerFunc()` and instances of this class can be used as +an alternative to `smHook` callbacks. + +## Core Functions <a name="core"></a> +### External function + +`SMELT* smGetInterface(int apilevel)` + +Returns an interface to the SMELT core functions if the apilevel matches the +internal one, otherwise it returns NULL. + +The internal facilities of SMELT are strectly singletons and this function +provides reference counting. Currently there is no way to use two or more +instances of SMELT at the same time in one application (unless you rename +the entire library). + +### Functions inside the `SMELT` class + +- `void smRelease()` +Release one reference to the SMELT core. Once all references are released, +the internal SMELT instance will free all the resources associated with it. +**ALL pointers to the SMELT core generated before are invalidated!** + +- `bool smInit()` +Initialize the SMELT core. +Creates application window, initializes video, audio and input handling. +No functions in these categories can be called before initialzing the +core. +You might want to do some setup works before calling this. +If the core is initialized successfully, this function returns true, +otherwise it returns false. The errors are written to stderr and the log +file if set. + +- `void smFinale()` +Deinitialize the SMELT core. This function closes the application window +and frees all resources managed by SMELT. +Unlike the behavior of `smRelease()` after the reference count reaching +zero, calling `smFinale()` retains the validity of all SMELT core pointers. +The core returns to the state prior to calling `smInit()`. + +- `void smMainLoop()` +Enters the main loop. +The main loop handles window events (key press, close request, movement +and resize etc) and calls your update function regularly. +This function requires the UpdateFunc set and initialization of the +core. + +- `void smUpdateFunc(smHook func)` +- `void smUpdateFunc(smHandler* h)` +Sets the update function. +If the update function returns true, the main loop will break, otherwise +the main loop goes on. +The update function is called every frame. +If both the handler and the hook are set, the hook will be executed first. + +- `void smUnFocFunc(smHook func)` +- `void smUnFocFunc(smHandler* h)` +Sets the unfocus event handler. +The unfocus function is called when the application window loses focus. +If both the handler and the hook are set, the hook will be executed first. + +- `void smFocFunc(smHook func)` +- `void smFocFunc(smHandler* h)` +Sets the focus event handler. +The focus functions is called when the application window gains focus. +If both the handler and the hook are set, the hook will be executed first. + +- `void smQuitFunc(smHook func)` +- `void smQuitFunc(smHandler* h)` +Sets the quit event handler. +Called when the user send a quit request to the application (e.g. by +pressing the close button). +If the handler/hook returns true, the quit request will be rejected and the +application will keep running. +If both the handler and the hook are set, the hook will be executed first. + +- `void smWinTitle(const char* title)` +Sets the application window title. +The default title is "untitled". + +- `bool smIsActive()` +Returns true if the application window has focus. Otherwise returns false. + +- `void smNoSuspend(bool para)` +By default, the update function won't be called when the application +window doesn't have focus (`para=false`). +Call this with `para=true` to make SMELT keep running when the window is +not focused. + +- `void smVidMode(int resX,int resY,bool _windowed)` +Sets the application video mode. +The default mode is 800 x 600 fullscreen. +Inappropriate values may cause the failure of smInit(). +In addition, only the `_windowed` parameter can be changed after the +creation of the window. + +- `void smLogFile(const char* path)` +Sets the log file path. + +- `void smLog(const char* format,...)` +Write something to the log file. C-style formatting can be used. +The log will be written to stderr and the log file if set. + +- `void smScreenShot(const char* path)` +Takes a shot of the application window content and saves it to the +given path. +Unimplemented in GLFW versions. + +- `void smSetFPS(int fps)` +Sets the desired FPS value. +The macros FPS_* can be used. Other values greater than 0 limits the +maximum FPS. + +- `float smGetFPS()` +Gets the current FPS value. +This value is updated once a second. + +- `float smGetDelta()` +Gets the delta time between the current frame and the last frame. + +- `float smGetTime()` +Gets the time in milliseconds since the call to `smInit()`. + +- `SMSFX smSFXLoad(const char *path)` +Loads a sound file from the given path. Currently only ogg vorbis and wav +files are supported. +~~Further more, due to the restrictions of openal-soft, only 8/16bit +mono/stereo formats are supported.~~ Seems not true anymore. +**This function loads the entire decompressed sample into main memory, +and may take some time.** Fortunately for you, this function can be called +from another thread. + +- `SMSFX smSFXLoadFromMemory(const char *ptr,DWORD size)` +Loads a sound file from the given memory block. +Limitations of `smSFXLoad()` also applies. + +- `SMCHN smSFXPlay(SMSFX fx,int vol=100,int pan=0,float pitch=1.,bool loop=0)` +Plays the given SFX. All parameters except the FX name is optional. +A channel is generated and can be used to control the playing of the SFX. +The channel is valid until it stops. +Volume should be 0~100. +Panning should be -100~100. +These values will be clamped to the range given above. +Note: There's a limit of the total available channels. This is defined in +the header `smelt\_config.hpp` with the macro `SRC_MAX`. If you are playing +too many channels simultaneously or have too many channels paused, you +may exhaust all channels and cause this function to fail. If it fails, +the channel name equals to 0. + +- `float smSFXGetLengthf(SMSFX fx)` +Gets the sound length in seconds. + +- `DWORD smSFXGetLengthd(SMSFX fx)` +Gets the sound length in number of samples. + +- `void smSFXSetLoopPoint(SMSFX fx,DWORD l,DWORD r)` +Sets the loop point of a sound. The loop points will be used when the fx is +played with `loop=true`. +The unit of the parameters is #samples. +By default, the whole sample is looped. +This function uses `AL_SOFT_loop_points` and may not work if SMELT isn't +built against OpenAl Soft. + +- `void smSFXFree(SMSFX fx)` +Releases the sound file from memory. +The handle will be invalid thereafter. + +- `void smChannelVol(SMCHN chn,int vol)` +Sets channel volume (0~100). + +- `void smChannelPan(SMCHN chn,int pan)` +Sets channel panning (-100~100). + +- `void smChannelPitch(SMCHN chn,float pitch)` +Sets channel pitch. + +- `void smChannelPause(SMCHN chn)` +Pauses the channel. + +- `void smChannelResume(SMCHN chn)` +Resumes a paused channel. + +- `void smChannelStop(SMCHN chn)` +Stops the channel. The channel handle will be invalid thereafter. + +- `void smChannelPauseAll()` +Pauses all playing channels. + +- `void smChannelResumeAll()` +Resumes all channels. + +- `void smChannelStopAll()` +Stops all channels. + +- `bool smChannelIsPlaying(SMCHN chn)` +Tests if a channel is playing. + +- `float smChannelGetPosf(SMCHN chn)` +- `void smChannelSetPosf(SMCHN chn,float pos)` +Gets/sets current position in second. + +- `int smChannelGetPosd(SMCHN chn)` +- `void smChannelSetPosd(SMCHN chn,int pos)` +Gets/sets current position in #sample. + +- `void smGetMouse2f(float *x,float *y)` +Gets mouse position (within the window). + +- `void smSetMouse2f(float x,float y)` +Sets mouse position (within the window). + +- `void smSetMouseGrab(bool enabled)` +Enables or disables mouse grabbing. +Useful for 3D camera control handling. + +- `int smGetWheel()` +Gets mouse wheel motion since the last frame. + +- `bool smIsMouseOver()` +Tests if the cursor is inside the application window. + +- `int smGetKeyState(int key)` +Gets the state of the given key. The `SMK_*` macros can be used. +Mouse buttons are treated as keys. +The return values are one of the `SMKST_*` macros: + * `SMKST_NONE`: the key is not pressed and is not just released either. + * `SMKST_RELEASE`: the key is not pressed but is just released. + * `SMKST_HIT`: the key is pressed but it was not pressed in the + last frame. + * `SMKST_KEEP`: the key is pressed and held since the last frame or + earlier. + +- `int smGetKey()` +Gets the key pressed last frame. +If multiple keys are pressed, the last pressed one (the last one in the +event queue) counts. + +- `bool smGetInpEvent(smInpEvent *e)` +Gets a event from the input queue. +The input parameter will be set to point the event. +If the input queue is empty, this function will return false. + +- `bool smRenderBegin2D(bool ztest=0,SMTRG trg=0)` +Starts rendering a 2D scene. +Set `ztest` to true if you want to use the z coordinate to control +the layout. +Set trg to the desired rendering target to render everything to the +target. +The function resets the camera. You have to setup the camera with +`sm2DCamera5f3v`. +NOTE: Any rendering function is not functional outside the +`smRenderBegin*D` function and its corresponding `smRenderEnd` function. + +- `bool smRenderBegin3D(float fov,SMTRG trg=0)` +Starts rendering a 3D scene. +Depth test is always enabled in this mode. +Set trg to the desired rendering target to render everything to the +target. +The distances to clipping planes are hard-coded (0.1 and 1000). This may +change in a future revision. +The function resets the camera. You have to setup the camera with +`sm3DCamera6f2v`. +NOTE: Any rendering function is not functional outside the +`smRenderBegin*D` function and its corresponding `smRenderEnd` function. + +- `bool smRenderEnd()` +Ends rendering the scene. +NOTE: Any rendering function is not functional outside the smRenderBegin*D +function and its corresponding smRenderEnd function. + +- `void sm3DCamera6f2v(float *pos,float *rot)` +Sets the 3D camera position and panning. +Each float vector should countain three elements. +The panning is euler rotation (all in degrees). +If any of the vectors is `NULL`, the function will reset the camera +instead. +The behaviour of the function is undefined in a 2D rendering session. + +- `void sm2DCamera5f3v(float *pos,float *dpos,float *rot)` +Sets the 2D camera transformation. +`pos` should contain two elements for the camera's position. +`dpos` should countain two elements for the rotation centre. +`rot` is the pointer to a single float denoting the rotation (in degrees). +If any of the vectors is `NULL`, the function will reset the camera +instead. +The behaviour of the function is undefined in a 3D rendering session. + +- `void smMultViewMatrix(float *mat)` +Provides direct manipulation on the model view matrix. +You can use "look at" matrix here, for example. +The matrix the same as the matrix defined in smMatrix (column-major), +but stored in float (That's fairly stupid...). + +- `void smClrscr(DWORD color,bool clearcol=true,bool cleardep=true)` +Clears the screen/rendering target with color. +Alpha channel is not applicable to the screen buffer. +Depth buffer will only be cleared if cleardep is set to true. +The same applies to the color buffer. + +- `void smRenderLinefd(float x1,float y1,float z1,float x2,float y2,float z2,DWORD color)` +Renders a line from (x1,y1,z1) to (x2,y2,z2) in the given color. +Lines never have textures. + +- `void smRenderLinefvd(float *p1,float *p2,DWORD color)` +Renders a line from (p1[0],p1[1],p1[2]) to (p2[0],p2[1],p2[2]) in the +given color. + +- `void smRenderTriangle(smTriangle *t)` +Renders a triangle. + +- `void smRenderQuad(smQuad *q)` +Renders a quadrilateral. + +- `smVertex* smGetVertArray()` +Return a pointer to the internal vertex array for advanced drawing. +The vertex array is rendered and cleared before returning it to you. +So you will always get the whole vertex array. +After filling the vertex array, call `smDrawVertArray()` to draw them. +By default, the size of the vertex array is 4000. This is defined in the +header `smelt_config.hpp` with the macro `VERTEX_BUFFER_SIZE`. + +- `void smDrawVertArray(int prim,SMTEX texture,int blend,int _primcnt)` +Draws the vertex array modified by `smGetVertArray()`. +The first parameter represents the type of primitive to be drawn. You can +use the macros `PRIM_*` here. + +- `void smDrawCustomIndexedVertices(smVertex* vb,WORD* ib,int vbc,int ibc,int blend,SMTEX texture)` +Draw indexed vertices. The primitive type is always triangle. +This function basically allows you to pass custom indices to +`glDrawElements()` instead the built in ones. +If you are not quite sure about what this function does, just ignore it. + - `vb`: pointer to vertices to be drawn. + - `ib`: pointer to indices of the vertices. + - `vbc`: number of vertices. + - `ibc`: number of indices. + - `blend`: blending mode. + - `texture`: texture used for the drawing. + +SMTRG smTargetCreate(int w,int h,int ms=0) [core/GFX] +Creates a rendering target (sized w*h) with multisampling level ms. +Modern OpenGL supports non-power-of-two targets, however some of the D3D9 +hardwares doesn't. +The target will be automatically resized, larger than the requested size, if +the given size is not supported. +Multisampling is disabled if ms=0. If multisampling is not supported, it +will be disabled automatically. + +SMTEX smTargetTexture(SMTRG targ) [core/GFX] +Gets the texture of the rendering target. + +void smTargetFree(SMTRG targ) [core/GFX] +Frees the rendering target. + +SMTEX smTextureCreate(int w,int h) [core/GFX] +Creates a blank texture (sized w*h). +OpenGL version supports non-power-of-two textures, however some of the D3D9 +hardwares doesn't. +The texture will be automatically resized, larger than the requested size, if +it is not supported. + +SMTEX smTextureLoad(const char *path,bool mipmap=false) [core/GFX] +Loads texture from the given file. +OpenGL version supports non-power-of-two textures, however some of the D3D9 +hardwares doesn't. +The texture will be automatically resized, larger than the requested size, if +it is not supported. +mipmapping doesn't work in OpenGL versions. + +SMTEX smTextureLoadFromMemory(const char *ptr,DWORD size,bool mipmap=false) +[core/GFX] +Loads texture from the given memory block. +OpenGL version supports non-power-of-two textures, however some of the D3D9 +hardwares doesn't. +The texture will be automatically resized, larger than the requested size, if +it is not supported. +mipmapping doesn't work in OpenGL versions. + +void smTextureFree(SMTEX tex) [core/GFX] +Release the texture from memory. + +void smTextureOpt(int potopt=TPOT_NONPOT,int filter=TFLT_LINEAR) [core/GFX] +Sets texture options. +TPOT_POT: textures dimensions are resized to the minimal power of two value. +TPOT_NONPOT: use textures whose dimensions are not power of two directly. +Please note that only power-of-two textures supports texture repeating. +TFLT_LINEAR: use the linear filter for texture scaling. +TFLT_NEAREST: use the nearest filter for texture scaling. + +int smTextureGetWidth(SMTEX tex,bool original=false) [core/GFX] +Gets the width of the texture. +If original==false and the texture is resized, the function will return the +resized p-o-t width of the texture. +Otherwise it returns the actual width of the texture file. + +int smTextureGetHeight(SMTEX tex,bool original=false) [core/GFX] +Gets the height of the texture. +If original==false and the texture is resized, the function will return the +resized p-o-t height of the texture. +Otherwise it returns the actual height of the texture file. + +DWORD* smTextureLock(SMTEX tex,int l,int t,int w,int h,bool ro=true) [core/GFX] +Locks the texture for reading/writing. +The locked area is defined as (l,t,w,h): left, top, width, height. +if ro==true, the changes won't be written back to the video memory. +Textures of rendering targets cannot be locked. + +void smTexutreUnlock(SMTEX tex) [core/GFX] +Unlocks the texture so that it can be used for rendering. +The changes will be commited to the video memory if ro==false when locking +the texture. + +SMELT extensions=============================================================== + +smAnimation==================================================================== +The extension provides texture management and animated entity support. + +Texture info class: smTexInfo +smTexRect rect; Texture rectangle +char *name,*path; name and internal path of the texture +SMTEX tex; Texture handle + +Animation info class: smAnmInfo +smTexInfo frames[256] Frames of the animation +int framedur[256] Frame durations +int mode loop mode: 0=noloop 1=loop 2=bidi loop +int fc Frame count +char* name Name of the animation + +Animation file class: smAnmFile +For the format of the .anm file, please refer to the file datapackFormat. +-bool loadAnmFromMemory(char* ptr,DWORD size) + Loads a .anm file from the given memory block. + .anm file is always packaged in dtp files in practice so only the load from + memory version is implemented. + All textures are loaded into the video memory during the process, so make sure + SMELT is initialized before calling this function. +-void close() + Close the anm file, free all textures and do the cleanup. +-smTexInfo* getTextureInfo(const char* name) + Gets the details of the texture with the given name. +-smAnmInfo* getAnimationInfo(const char* name) + Gets the details of the animation with the given name. + +2D animated entity class: smAnimation2D +smAnimation2D is derived from the smEntity2D class. +-Constructor from a smAnmInfo class +-void updateAnim(int f=1) + Updates the animation with frame step f. +-void resetAnim() + Resets the animation. + +3D animated entity class: smAnimation3D +smAnimation3D is derived from the smEntity3D class. +-Constructor from a smAnmInfo class +-void updateAnim(int f=1) + Updates the animation with frame step f. +-void resetAnim() + Resets the animation. +smBMFont======================================================================= +The extension provides support of bitmap font rendering. +Bitmap font used by SMELT is described in anm format, with a different meta +file. + +Two classes are provided: smBMFont and smBMFontw. smBMFont accepts char stings +and smBMFontw accepts wchar strings. Their interfaces are the same. + +smBMFontw uses std::map, so huge font files are discouraged. + +Public members of smBMFont(w): +-loadAnmFromMemory(char* ptr,DWORD size) + Loads an anm file describing the font from the given memory block. +-close() + Closes the anm file and frees any resources used by the class. +-render(float x,float y,float z,int align,float *rw,const char*/wchar_t* text) + Render the given text at (x,y,z) with the given align. + ailgns can be one of the macros ALIGN_LEFT/ALIGN_RIGHT/ALIGN_CENTER. + if rw is not NULL, the width of the string will be returned to the pointer. + '\n' is processed correctly. Other control characters are not processed and + may not render correctly. +-printf(float x,float y,float z,int align,float *rw,const wchar_t* format,...) + Render formated string at (x,y,z) with the given align. + The parameters are the same as the render function. +-setColor(DWORD col) + Sets the color for the next rendering. +-setBlend(int blend) + Sets blending mode for the next rendering. +-setScale(int scale) + Sets the font scaling. + +smColor======================================================================== +The extension implements two color classes: smColorRGBA and smColorHSVA. + +Public members of smColorRGBA: +-float r,g,b,a R/G/B/A components, ranged 0..1 +-Default construction op Sets all components to zero +-Construction op from a hardware color +-Construction op from components +-Default destuction op +-void clamp() clamps all components to their range +-operator + - * color operations +-operator * / scalar operations +-void setHWColor(DWORD col) Sets the color accroding to the given + hardware color +-DWORD getHWColor() Gets the hardware color. The color is + automatically clamped. + +Public members of smColorHSVA: +-float h,s,v,a R/G/B/A components, ranged 0..1 +-Default construction op Sets all components to zero +-Construction op from a hardware color +-Construction op from components +-Default destuction op +-void clamp() clamps all components to their range +-operator + - * color operations +-operator * / scalar operations +-void setHWColor(DWORD col) Sets the color accroding to the given + hardware color +-DWORD getHWColor() Gets the hardware color. The color is + automatically clamped. + +smDataPack===================================================================== +The extension implements a data packaging method for increased integrity. +smDtpFileR is used to read a dtp file, while smDtpFileW is used to create a +dtp file. +The format of the dtp file is described in the file datapackFormat. + +Public members of smDtpFileR: +-bool openDtp(const char* path) + Opens a compressed dtp from the given path. + Returns true on succeed, false on failure. +-bool openDtpFromMemory(char* ptr,DWORD size) + Opens a uncompressed dtp from the memory block. + Returns true on succeed, false on failure. +-void closeDtp() + Close the opened dtp file. Release any internal allocated resources. +-char* getFirstFile() + Returns the internal path of the first file in the dtp. +-char* getLastFile() + Returns the internal path of the last file in the dtp. +-char* getNextFile(const char* path) + Returns the internal path of the next file in the dtp. +-char* getPrevFile() + Returns the internal path of the previous file in the dtp. +-char* getFilePtr(const char* path) + Get the pointer to the file required. + The file is loaded into memory during the process. +-void releaseFilePtr(const char* path) + Release the file in the memory. + Always free the file with this function. +-DWORD getFileSize(const char* path) + Get the file size in bytes of the file required. + +Public members of smDtpFileW: +-bool addFile(const char* path,const char* realpath) + Adds a file to the temporary dtp. + path is used as the internal path, realpath is the path of the data + to be packed. +-bool writeDtp(const char* path) + Writes the temporary dtp to a file. + The dtp file is compressed. + The temporary dtp file is deleted after the process. + +A simple DaTaPack utility implementation is in the folder dtputil. +smEntity======================================================================= +The extension implements two entity classes for easy entity rendering. + +Public members of smEntity2D: +-Consturction op from texture and + texture rectangle(SMTEX,float,float,float,float) +-Construction op from texture and + texture rectangle(SMTEX,smTexRect) +-Construction op from another smEntity2D +-Destuction op +-void Render(float x,float y,float rot,float wsc,float hsc) + Renders the entity at (x,y) with rotation rot (optional, in radians). + wsc/hsc (optional) controls the scaling in width and height. + if hsc is omitted, wsc is used as hsc. By default, wsc=1. +-void setTexutre(SMTex tex) + Sets the texture of the entity. +-void setTextureRect4f(float _x,float _y,float _w,float _h) + void setTextureRectv(smTextRect rect) + Sets the area of texture used for rendering. +-void setColor(DWORD col,int v) + Sets the color of the entity or one of the vertexes of the entity. + If v is omitted or v is out of the range 0..3, all four vertexes are + re-colored. +-void setZ(float z,int v) + Sets the z value of the entity or one of the vertexes of the entity. + If v is omitted or v is out of the range 0..3, all four vertexes are + re-positioned. +-void setBlend(int blend) + Sets the blend mode of the entity. The macros BLEND_* are used. +-void setCentre(float x,float y) + Sets the centre of the entity. The centre is used as the rotation centre. + When rendered, the centre is used to position the entity. + +//There's a pending overhaul of smEntity3D. Please ignore the section below. +smEntity3D is almost the same as smEntity2D, except the lack of setZ function +and some difference in the rendering methods. Further more, smEntity3D always +writes to the Z buffer when rendered. +-void Render9f(float x,float y,float z,float ra,float rx,float ry,float rz, + float wsc,float hsc) + Renders the 3D entity at (x,y,z). + The entity is rotated by the parameters (ra,rx,ry,rz), in which ra specifies + the angle of rotation in radians and (rx,ry,rz) specify the rotation axis. + The rotation parameters are optional. The vector (rx,ry,rz) is automatically + normalized. + wsc/hsc (optional) controls the scaling in width and height. + if hsc is omitted, wsc is used as hsc. By default, wsc=1. +-void Renderfv(float* pos,float* rot,float* scale) + Equivalent to Render9f(pos[0],pos[1],pos[2],rot[0],rot[1],rot[2],rot[3] + scale[0],scale[1]). + +smGrid========================================================================= +The extension implements a grid used for rendering distorted entity. +Sample grid: +``` ++-----+-----+ +| | | +| | | +| | | ++-----+-----+ +| | | +| | | +| | | ++-----+-----+ +``` +This is a simple 3*3 grid, undistorted. If we fit a texture onto it we will +see a rectangle with that texture. +Now we can distort it like this: +``` ++-----+-----+ + \ \ \ + \ \ \ + \ \ \ + +-----+-----+ + \ \ \ + \ \ \ + \ \ \ + +-----+-----+ +``` +If we fit a texture onto this grid, we will see a parallelogram. +The grid looks better when the resolution is higher. +With this extension we can implement water/lens/wrapping effect and curved +lasers easily. +The indicatorCircular in the smIndicator extension is also implemented with +smGrid. + +Public members of smGrid: +-Default construction op (int,int) + This construction op requires the column&row count of the grid. +-Copy construction op(const smGrid ©) + Constructs a new smGrid copying the given one. +-Default destuction op. +-operator = +-void render(float x,float y) + Renders the grid at (x,y). (x,y) is the top left coordinate. +-void clear(DWORD color) + Resets the grid with the optional color. +-void setTexutre(SMTEX tex) + Sets the texture of the grid. +-void setTextureRect4f(float _x,float _y,float _w,float _h) + void setTextureRectv(smTexRect rect) + Sets the texture region used by the grid. +-void setBlend(int blend) + Sets the blend mode of the grid. +-void setColor(int c,int r,DWORD col) + Sets the color of the node at row r column c. + You can create interesting colorful effects with this. +-void setPos(int c,int r,float x,float y,float z,int ref) + Sets the positioning of the node at row r column c. + The z value is always directly set. + The x/y values are set according the reference setting. + Possible references are: + GRID_REFNODE: reference point is the node position of a regular grid + GRID_REFTOPLEFT: reference point is the top left corner of the grid + GRID_REFCENTER: reference point is the centre of the grid + GRID_REFCURRENT: reference point is the current position of the node + +smIndicator==================================================================== +The extension implements several value indicators. + +Public members of class indicatorCircular/indicatorLinear: +-void init(double r,double thkns,BYTE a,SMTEX tex,smTexRect tr) + Initialize the indicator with radius r, thickness thkns. + a is used as the initial alpha. +-void overrideColor(DWORD col) + Overrides the default dynamic color with the static color. +-void setAlpha(BYTE a) + Sets the indicator alpha +-void setValue(double v) + Sets the value indicated by the indicator. + The value should be within 0..1. + +smMath========================================================================= +The extension provides several math routines. + +Common math routines: +double smMath::deg2rad(double deg) converts degree to radian +double smMath::rad2deg(double deg) converts radian to degree +double smMath::clamprad(double a) clamps the given angle to [0,2*PI] +double smMath::clampdeg(double a) clamps the given angle to [0,360] + +2D Vector: smvec2d +double x,y coordinates +Constructor(double,double) constructs the vector with the given + coordinates +Default constructor +double l() returns the length of the vector +void normalize() normalizes the vector +smvec2d getNormalized() returns the normalized vector +void swap() swaps the x,y coordinates +void rotate(double rad) rotate the vector by rad radians +smvec2d getRotate(double rad) returns the rotated vector +smvec2d operator - + +smvec2d/double operator * scalar/(length of) cross product +double operator | point product +double operator ^ angle between the vectors + +3D Vector: smvec3d +double x,y,z coordinates +Constructor(double,double,double) constructs the vector with the given + coordinates +Constructor(smvec2d) constructs the vector from the 2d + vector with z=0 +Default constructor +double l() returns the length of the vector +void normalize() normalizes the vector +smvec3d getNormalized() returns the normalized vector +smvec3d operator - + +smvec3d operator * scalar/cross product +smvec3d operator | point product +double operator ^ angle between the vectors + +Transformation matrix: smMatrix +double m[16] +sf 0 1 2 3 +0 00 04 08 12 +1 01 05 09 13 +2 02 06 10 14 +3 03 07 11 15 +Default constructor +Copy constructor +operator [] with this you can access the matrix + like (smMatrix)a[col][row] +void clear() sets the whole matrix to 0 +void loadIdentity() sets the matrix to the identity matrix +void rotate(double,double,double,double) + rotates the vector by (a,x,y,z) where + a is the rotation angle in radians and + (x,y,z) is the rotation axis. +void lookat(double *eye,double *at,double *up) + all vectors have three elements. + This function produces a "look at" + matrix. + When the identity view matrix is + multiplied by the "look at" matrix, it + seems that you are at the "eye" + position, looking at the "at" opsition. + The up vector is used to determine the + pitch of the camera. +operator * Matrix-matrix multiplication. +operator * Matrix-vector multiplication. +smProgresser=================================================================== +The extension implements several progressers useful for making transitions. +All progressers work in the same way: it returns a value within [a,b] according +to the current progress. + +All progresser have these functions publicly accessible: +void init(double _a,double _b,double _lim,[additional parameters]) +Initializes the progresser with a=_a, b=_b and maximum progress _lim. +void launch() +Launch the progresser. This function actually resets the progresser. +void update(double delta) +Updates the progress with delta value delta. +bool isDone() +Check if the progresser has completed its progress. +double getValue() +Gets the current progresser value. +double getPercentage() +Gets the current progress percentage(always linear). +double getDelta() +Gets the current delta between progresser value and a. +double getElapsed() +Gets the current elapsed progress. + +Currently two types of progressers are implemented. +-smProgresserLinear +Normal linear progresser. +-smProgresserCurve +Curve progresser. This progresser requires an additional parameter to +Initialize, which is the radius of the curve. The bigger abs(curvepara) is, +the steeper the progressing curve will be. If curvepara=0, it will act +as the linear progresser. The sign of the parameter controls the bending +direction of the curve. + +smRandom======================================================================= +The extension implements a pseudo random number generator. +Pseudo random number generator always generates the same sequence of number +provided that the seed and the calling sequence is the same. + +Public members of smRandomEngine +void setSeed(unsigned int seed) +Sets the random seed. The seed affects the next number generated. +int nextInt(int min,int max) +Generate a random integer. The seed is updated too. +Please note that max is not necessarily greater than min. +double nextDouble(double min,double max) +Generate a random double. The seed is updated too. +Please note that max is not necessarily greater than min. +smTTFont======================================================================= +The extension implements a freetype interface for SMELT. +Two classes are implemented: smTTChar and smTTFont. smTTChar is implemented for +internal use and should not be used outside the smTTFont class. Class smTTFont +provides all interfaces for font rendering. + +smTTFont uses std::map to cache character glyphs. The cache is manually managed +by the application. A cache too large in size may cause lags. + +Public members of smTTFont: +-bool loadTTF(const char* path,int pt) + Loads a font from the given path. pt is used as the size of the font in + points. +-bool loadTTFFromMemory(char* ptr,DWORD size,int pt) + Loads a font from the given memory block. pt is used as the size of the font + in points. +-void releaseTTF() + Clear the cache and release the loaded font. +-float getWidth() +-float getHeight() + Gets the width/height of the buffered string. + The buffered string is modified by the updateString function. +-void updateString(const wchar_t *format,...) + Update the buffered string. + Update the buffer only when you need to do so because this function is + relatively slow. + '\n' is processed correctly. + If a char is in the internal cache, it will be reused. Otherwise it will be + added to the cache. +-void render(float x,float y,DWORD col,int align) + Renders the buffered string. + The align mode ALIGN_CENTER is not supported. + (x,y) defines the top-left coordinate of the rendered text when using + ALIGN_LEFT while it defines the bottom-right coordinate when using + ALIGN_RIGHT. + col defines the color of the rendered text. +-DWORD getCacheSize() + Gets the internal cache size. + It is advised to keep the cache size relatively low, generally below + 100 thousand. +-void clearCache() + Clear the internal cache. |