SparrowCore is for creating a SDL window, creating optimal surfaces for blitting on these window, for program main loops with feeedback functions for drawing, calculation and different kinds of event handling. Furthermore here are some helper functions like converting colors or checking, whether a file exists.
| sparrowCore | SparrowCore is for creating a SDL window, creating optimal surfaces for blitting on these window, for program main loops with feeedback functions for drawing, calculation and different kinds of event handling. |
| Macros | |
| Range of the analog axis | |
| Trigger limits for analog sticks | If a REAL input device (not the sparrow3d generic input device!) |
| Generic button and axis count | |
| Keyboard waiting | If a key is pressed after a given time it will be pressed again. |
| Values for spSetVirtualKeyboard. | With spSetVirtualKeyboard you setup, when the virtual keyboard is used. |
| Return types for spGetLastAxisType | Return types for spGetLastAxisType. |
| SP_CACHE_SIZE | The size of the surface cache |
| Types | |
| spInput | This struct contains information about the generic input device sparrowCore provides, which is same on every device |
| Functions | |
| spSetDefaultWindowSize | Sets defaults values for the window. |
| spInitCore | spInitCore initializes SDL, SDL_TTF and other stuff. |
| spPrintDebug | spPrintDebug prints debug stuff with timestamp |
| spCreateWindow | Creates the Window in the plattform depended resolution. |
| spCreateDefaultWindow | Creates a default window with no fullscreen for PC, but resizeable for PC. |
| spGetWindowSurface | Returns the window Surface. |
| spLoop | Starts a main loop |
| spFlip | Draws the changes in the window Surface on the screen. |
| spGetInput | Returns a pointer of the spInput struct, where the input values will be set. |
| spResetButtonsState | Resets the state of any button in the generic device to 0 (=unpressed) |
| spResetAxisState | Resets the state of any axis (digital and analog) in the generic device to 0 (=unpressed) |
| spGetLastAxisType | Gives you the last used axis type (digital or analog). |
| spPollKeyboardInput | Prints all following keyboard input (that is numbers, letters and symbols) into the passed buffer. |
| spStopKeyboardInput: | Stops keyboard input. |
| spSetReturnBehavior | Changes the behaviour, what happens, if Return is pressed while keyboard input is pulled. |
| spIsKeyboardPolled | Says, whether input from the keyboard is polled. |
| spSetVirtualKeyboard | Sets up a virtual keyboard especially for systems without a keyboard like the gp2x, caanoo, etc. |
| spGetVirtualKeyboardState | Gives the virtual keyboard state set by spSetVirtualKeyboard. |
| spGetVirtualKeyboard | This functions returns the precalculated and prescaled keyboard design. |
| spSetVirtualKeyboardShiftState | Sets the state of the Shift mode of the virtual keyboard. |
| spGetVirtualKeyboardShiftState | Returns the state of the Shift mode of the virtual keyboard. |
| spSetVirtualKeyboardSpaceButton | Sets a button, which is used as space if text is entered via virtual keyboard. |
| spSetVirtualKeyboardBackspaceButton | Sets a button, which is used as backspace if text is entered via virtual keyboard. |
| spSetTouchscreenEmulationButtons | Sets, whether on systems without touchscreen or mouse (like the GP2X F100) a touchscreen is emulated. |
| spSleep | Waits the given microseconds (!) |
| spQuitCore | Just quits the Core. |
| spGetFPS | Returns the FPS of the Loop Function |
| spGetSizeFactor | Returns a fixed point factor for the screen size. |
| spLoadSurface | Loads a 16 Surface needed by the engine. |
| spLoadSurfaceZoom | Loads and zoomes a 16 Surface needed by the engine. |
| spCopySurface | This creates a “copy” of a surface. |
| spUniqueCopySurface | |
| spEnableCaching | Enables caching surfaces. |
| spDisableCaching | Disables chaching of surfaces. |
| spIsCachingEnabled | Says, whether caching of surfaces is enabled or not. |
| spCreateSurface | Creates a 16 Surface 100% compatible to the engine. |
| spDeleteSurface | Deletes a surface, if it is not cached or the reference counter reaches 0. |
| spClearCache | Deletes ALL cached surfaces! |
| spGetRGB | Returns a 16 bit RGB color |
| spGetFastRGB | Returns like spGetRGB a 16 bit color out of RGB values, but it is faster and a little bit inaccurate - if you don’t mind, don’t see it or need it VERY often ingame, use this! |
| spGetRFromColor | Gives you the red value of a color. |
| spGetGFromColor | Gives you the green value of a color. |
| spGetBFromColor | Gives you the blue value of a color. |
| spGetRawRFromColor | Gives you the red value of a color. |
| spGetRawGFromColor | Gives you the greeen value of a color. |
| spGetRawBFromColor | Gives you the blue value of a color. |
| spGetHSV | Returns a 16 bit color defined by the HSV values. |
| spGetHFromColor | Gives you the hue of a color. |
| spGetSFromColor | Gives you the saturation of a color. |
| spGetSFromColor | Gives you the value of a color. |
| spScale2XFast | Copies and scales source to destination very fast. |
| spScale2XSmooth | Like spScale2XFast, but with the MAME2x scale up algo. |
| spScaleDownFast | Copies and scales down source to destination very fast. |
| spScaleDownSmooth | Copies and scales down source to destination with anti aliasing. |
| spAddBorder | Adds a border to the surface with the background color backgroundcolor. |
| spStereoMergeSurfaces | This functions merges two same sized (!) |
If a REAL input device (not the sparrow3d generic input device!) has analog sticks, these are the limits, from which the generic axes are uneven 0 or reseted to 0 again.
If a key is pressed after a given time it will be pressed again. Since then the time between two key pressing is shorter. You know this effect from terminals like in the bash, cmd.exe (Windows) or under MS-DOS.
With spSetVirtualKeyboard you setup, when the virtual keyboard is used.
Return types for spGetLastAxisType.
| SP_DIGITAL_AXIS | digital input was used |
| SP_ANALOG_AXIS | analog input was used |
This struct contains information about the generic input device sparrowCore provides, which is same on every device
| axis (char*) | the two axis of the input device. Every axis can be -1 (left/up), 0 (no direction) or 1 (right/down) |
| button (char*) | the generic input device has 20 buttons, but many buttons are just for compatibility reason to the gp2x-family. You should only use button 8 to 18 (11 buttons) or better: the #defines for the buttons like SP_BUTTON_START or SP_BUTTON_A (see sparrowDefines.h). |
| supports_keyboard (char) | this variable says, whether the target supports a hardware keyboard. However: at least a software onscreen keyboard is always provided |
| touchscreen (struct of 3 ints) | because of the principle of the least common factor, there is no support for mouses, but for touchscreens. The different is, that you CAN’T use the position provided here if the touchscreen is not pressed! Please keep that in mind. For devices without touchscreen an emulation is provided. keyboard (internal struct)- internal struct for keyboard input. Do not change. |
| analog_axis (Sint16*) | a value between SP_ANALOG_AXIS_MIN and SP_ANALOG_AXIS_MAX. For digital input (D-Pad) this will be always be the MIN or MAX value, but for analog input (such as the Pandora’s nubs or another analog stick) you will get a value on the range of MIN..MAX as accurate as SDL can poll the hardware. axis and analog_axis are not independant. If both methods of input are present you will NOT be able to access both, instead the one polled last by SDL will superseed the former. |
PREFIX SDL_Surface* spCreateWindow( int width, int height, int fullscreen, int allowresize )
Creates the Window in the plattform depended resolution. You will get the created SDL_Surface to render to, whoever you want.
| width | width of the window. Ignored for most handhelds because of fullscreen |
| height | height of the window. Ignored for most handhelds because of fullscreen |
| fullscreen | 1 means fullscreen, 0 means no fullscreen. Ignored for most handhelds, because always fullscreen |
| allowresize | determines, whether the window is resizeable. Ignored for most handhelds |
| SDL_Surface* | Window surface. If you want to draw to it with sparrow3d, dont’t forget to call spSelectRenderTarget. |
PREFIX int spLoop( void ( *spDraw )( void ), int ( *spCalc )( Uint32 steps ), Uint32 minwait, void ( *spResize )( Uint16 w, Uint16 h ), void ( *spEvent )( SDL_Event *e ) )
Starts a main loop
| spDraw | the drawing function |
| spCalc | the calculation function. If it returns a value unequal 0 it loop stops. The given steps are the ms since the last frame. Always > 0! |
| minwait | minimal time between two drawing steps. Usefull for setting maximal frames per seconds, e.g. use 10 for 100 fps or 16 for ~62 fps. |
| spResize | Feedback function if the window is resized. The size of the window is passed in w and h. Use it e.g. for reloading resources in a higher or lower resolution. |
| spEvent | if this feedback function is given, it gets every SDL event, that has passed the mainloop to react to it (,too). |
| int | the value spCalc returned |
PREFIX PspInput spGetInput( void )
Returns a pointer of the spInput struct, where the input values will be set. Dont’t free it on your own!
| PspInput | A pointer to a spInput struct |
PREFIX int spGetLastAxisType( void )
Gives you the last used axis type (digital or analog). In fact sparrow3d “merges” these types, but sometimes it may be usefull to know, which fart made the smell. ;)
| int | SP_DIGITAL_AXIS (0) if the last axis was digital or SP_ANALOG_AXIS (1) if the last axis was analog. Most devices return either analog or digital because of missing digital or analog input. Pandora is a counterexample |
PREFIX void spPollKeyboardInput( char * buffer, int bufferSize, Sint32 enter_key_mask )
Prints all following keyboard input (that is numbers, letters and symbols) into the passed buffer. This function does not halt execution, rather the buffer is filled over the next frames until it is full or polling is stopped. Only backspace is allowed for editing. On devices without a physical keyboard you have to make sure to show some kind of on-screen keyboard allowing for input.
| buffer | the buffer for the input |
| buffersize | the maximum size of the passed buffer |
| enter_key_mask | determines which generic buttons are used for entering keys on the virtual keyboards. E.g. SP_BUTTON_A | SP_BUTTON_B says, that A or B can be used the enter stuff. |
PREFIX void spSetReturnBehavior( int ignore, int stops )
Changes the behaviour, what happens, if Return is pressed while keyboard input is pulled. Note: Every combination of “ignore” and “stops” is possible
| ignore | Return should be ignored and not appear in the keyboard buffer |
| stops | Return should stop the keyboard polling. |
PREFIX void spSetVirtualKeyboard( int state, int x, int y, int width, int height, SDL_Surface * design, SDL_Surface * shiftDesign )
Sets up a virtual keyboard especially for systems without a keyboard like the gp2x, caanoo, etc. The keyboard uses the input devices for input. Only if Keyboard input is pulled, the keyboard is useable!
| state | Can be SP_VIRTUAL_KEYBOARD_NEVER, SP_VIRTUAL_KEYBOARD_IF_NEEDED, SP_VIRTUAL_KEYBOARD_ALWAYS. See definitions for the function. |
| x, y | determines where you will draw the onscreen keyboard (later). |
| width | width of the onscreen keyboard |
| height | height of the onscreen keyboard Necessary for interpretating the touchscreen input (offset!) |
| design | You have to add a design, if you want to show something! The keyboard reacts to input, nevertheless, if you don’t pass something, but if you don’t draw anything nothing will be seeable... A reference design with the exact position of the buttons is in the sparrow3d folder in data named “keyboard.xcf”. This file is public domain. Use it how ever you want. Internal a copy of the design with this size (x,y) will be saved, so you can free the surface afterwards. However don’t forget to recall this function on resize. After that you can use spGetVirtualKeyboard to get a SDL_Surface with the size (width,height), which can (and have to!) be drawn by you. |
| shiftDesign | like design, but it is shown, if Shift is enabled. |
PREFIX int spGetVirtualKeyboardState( void )
Gives the virtual keyboard state set by spSetVirtualKeyboard.
| int | the state. The value can be SP_VIRTUAL_KEYBOARD_NEVER or SP_VIRTUAL_KEYBOARD_ALWAYS. SP_VIRTUAL_KEYBOARD_IF_NEEDED is translated to one of those above at setup |
PREFIX SDL_Surface* spGetVirtualKeyboard( void )
This functions returns the precalculated and prescaled keyboard design.
| SDL_Surface* | NULL, if the virtual keyboard is deactivated or no surface was passed, otherwise the keyboard surface with key-marking and shift specific changes. Don’t save the result, call it every frame. |
PREFIX void spSetTouchscreenEmulationButtons( int switch_button, int ok_button )
Sets, whether on systems without touchscreen or mouse (like the GP2X F100) a touchscreen is emulated.
| switch_button | if it shall be emulated you have to set a button (e.g. SP_BUTTON_SELECT), which will switch between the “normal mode” (where you get all buttons) and “touchscreen mode”, where D-Pad and ok_button (e.g. SP_PRACTICE_OK) will be blocked and used for moving and using a cursor on the screen. Set switch_button to SP_NO_TOUCHSCREEN_EMULATION (or -1) to deactivate emulation. |
| ok_button | the button for clicking the “mouse” |
PREFIX SDL_Surface* spLoadSurfaceZoom( const char * name, Sint32 zoom )
Loads and zoomes a 16 Surface needed by the engine. If enabled it will be cached. Every zoom level is cached particular.
| char* | filename of the image to load |
| zoom | fixed point zoom value. SP_ONE will not zoom, greater values will increase, smaller values decrease the surface. |
| SDL_Surface* | the loaded and zoomed surface |
PREFIX SDL_Surface* spCopySurface( SDL_Surface * surface )
This creates a “copy” of a surface. If caching is enabled, it just returns the cached surface pointer (which should be the same as the parameter) and increases the reference counter. If caching is disabled, a real copy is made. If you need a REAL copy every time, use spUniqueCopySurface.
| surface | the surface to be copied |
| SDL_Surface* | the “copy” |
PREFIX void spEnableCaching( void )
Enables caching surfaces. That means, that, if you load an image twice, internal it is only loaded once to save RAM. If you WANT one image in two different surfaces, disable caching (spriteCollection may wont work then anymore) or create an unique copy with spUniqueCopySurface. At default caching is enabled. A reference counter counts, how often a surface is loaded for spDeleteSurface
PREFIX SDL_Surface* spCreateSurface( int width, int height )
Creates a 16 Surface 100% compatible to the engine. This surface is not cached (because it has no filename to remember ;-) )
| width | the width of the surface |
| height | the height of the surace |
| SDL_Surface* | the created surface |
PREFIX void spDeleteSurface( SDL_Surface * surface )
Deletes a surface, if it is not cached or the reference counter reaches 0. If the reference counter is greater 0, it is just decreased. Don’t call it more often than spCreateSurface for the same image!
| surface | the surface to be deleted |
PREFIX void spScale2XFast( SDL_Surface * source, SDL_Surface * destination )
Copies and scales source to destination very fast. Attention! Destination HAVE TO HAVE the size source->w*2*source->h*2! Furthermore the pixel depth must be 2 (16 bit graphics).
| source | source surface |
| destination | destination surface. Have to have the double width and double height of the source surface. |
PREFIX void spScale2XSmooth( SDL_Surface * source, SDL_Surface * destination )
Like spScale2XFast, but with the MAME2x scale up algo. A bit slower and may look not good. However most of the time it will.
| source | source surface |
| destination | destination surface. Have to have the double width and double height of the source surface. |
PREFIX void spScaleDownFast( SDL_Surface * source, SDL_Surface * destination )
Copies and scales down source to destination very fast. Attention! Destination HAVE TO HAVE the size source->w/2*source->h/2! Furthermore the pixel depth must be 2 (16 bit graphics).
| source | source surface |
| destination | destination surface. Have to have the double width and double height of the source surface. |
PREFIX void spScaleDownSmooth( SDL_Surface * source, SDL_Surface * destination )
Copies and scales down source to destination with anti aliasing. Attention! Destination HAVE TO HAVE the size source->w/2*source->h/2! Furthermore the pixel depth must be 2 (16 bit graphics).
| source | source surface |
| destination | destination surface. Have to have the double width and double height of the source surface. |
PREFIX void spAddBorder( SDL_Surface * surface, Uint16 borderColor, Uint16 backgroundcolor )
Adds a border to the surface with the background color backgroundcolor.
Parameters surface - the surface in which the border will be drawn borderColor - the color of the border backgroundcolor - the color of the background to determine where to draw a border
PREFIX void spStereoMergeSurfaces( SDL_Surface * left, SDL_Surface * right, int crossed )
This functions merges two same sized (!) surfaces to one. The left one will be overwritten by a or-merge, if “crossed” is 0. That means every pixel of the left surface will be: left[p] = left[p] | right[p]. If “crossed” is 1 every second line of every surface will be taken, that you get two clinched pictures in one surface. Use the first one for coloured glasses stereo and the second for crossing eye stereoscopy.
| left | the left surface in which will be drawn, too |
| right | the right surface, it will only be read |
| crossed | determines, whether the merge is or-based or two-images-based (See above) |
Sets up a virtual keyboard especially for systems without a keyboard like the gp2x, caanoo, etc.
PREFIX void spSetVirtualKeyboard( int state, int x, int y, int width, int height, SDL_Surface * design, SDL_Surface * shiftDesign )
Gives you the last used axis type (digital or analog).
PREFIX int spGetLastAxisType( void )
Sets defaults values for the window.
PREFIX void spSetDefaultWindowSize( int w, int h )
spInitCore initializes SDL, SDL_TTF and other stuff.
PREFIX void spInitCore( void )
spPrintDebug prints debug stuff with timestamp
PREFIX void spPrintDebug( char * text )
Creates the Window in the plattform depended resolution.
PREFIX SDL_Surface* spCreateWindow( int width, int height, int fullscreen, int allowresize )
Creates a default window with no fullscreen for PC, but resizeable for PC.
PREFIX SDL_Surface* spCreateDefaultWindow( void )
Returns the window Surface.
PREFIX SDL_Surface* spGetWindowSurface( void )
Starts a main loop
PREFIX int spLoop( void ( *spDraw )( void ), int ( *spCalc )( Uint32 steps ), Uint32 minwait, void ( *spResize )( Uint16 w, Uint16 h ), void ( *spEvent )( SDL_Event *e ) )
Draws the changes in the window Surface on the screen.
PREFIX void spFlip( void )
Returns a pointer of the spInput struct, where the input values will be set.
PREFIX PspInput spGetInput( void )
Resets the state of any button in the generic device to 0 (=unpressed)
PREFIX void spResetButtonsState( void )
Resets the state of any axis (digital and analog) in the generic device to 0 (=unpressed)
PREFIX void spResetAxisState( void )
Prints all following keyboard input (that is numbers, letters and symbols) into the passed buffer.
PREFIX void spPollKeyboardInput( char * buffer, int bufferSize, Sint32 enter_key_mask )
Changes the behaviour, what happens, if Return is pressed while keyboard input is pulled.
PREFIX void spSetReturnBehavior( int ignore, int stops )
Says, whether input from the keyboard is polled.
PREFIX int spIsKeyboardPolled( void )
Gives the virtual keyboard state set by spSetVirtualKeyboard.
PREFIX int spGetVirtualKeyboardState( void )
This functions returns the precalculated and prescaled keyboard design.
PREFIX SDL_Surface* spGetVirtualKeyboard( void )
Sets the state of the Shift mode of the virtual keyboard.
PREFIX void spSetVirtualKeyboardShiftState( int state )
Returns the state of the Shift mode of the virtual keyboard.
PREFIX int spGetVirtualKeyboardShiftState( void )
Sets a button, which is used as space if text is entered via virtual keyboard.
PREFIX void spSetVirtualKeyboardSpaceButton( int button )
Sets a button, which is used as backspace if text is entered via virtual keyboard.
PREFIX void spSetVirtualKeyboardBackspaceButton( int button )
Sets, whether on systems without touchscreen or mouse (like the GP2X F100) a touchscreen is emulated.
PREFIX void spSetTouchscreenEmulationButtons( int switch_button, int ok_button )
Waits the given microseconds (!)
PREFIX void spSleep( Uint32 microSeconds )
Just quits the Core.
PREFIX void spQuitCore( void )
Returns the FPS of the Loop Function
PREFIX int spGetFPS( void )
Returns a fixed point factor for the screen size.
PREFIX Sint32 spGetSizeFactor( void )
Loads a 16 Surface needed by the engine.
PREFIX SDL_Surface* spLoadSurface( const char * name )
Loads and zoomes a 16 Surface needed by the engine.
PREFIX SDL_Surface* spLoadSurfaceZoom( const char * name, Sint32 zoom )
This creates a “copy” of a surface.
PREFIX SDL_Surface* spCopySurface( SDL_Surface * surface )
PREFIX SDL_Surface* spUniqueCopySurface( SDL_Surface * surface )
Enables caching surfaces.
PREFIX void spEnableCaching( void )
Disables chaching of surfaces.
PREFIX void spDisableCaching( void )
Says, whether caching of surfaces is enabled or not.
PREFIX int spIsCachingEnabled( void )
Creates a 16 Surface 100% compatible to the engine.
PREFIX SDL_Surface* spCreateSurface( int width, int height )
Deletes a surface, if it is not cached or the reference counter reaches 0.
PREFIX void spDeleteSurface( SDL_Surface * surface )
Deletes ALL cached surfaces!
PREFIX void spClearCache( void )
Returns a 16 bit RGB color
PREFIX Uint16 spGetRGB( int r, int g, int b )
Returns a 16 bit color defined by the HSV values.
PREFIX Uint16 spGetHSV( Sint32 h, Uint8 s, Uint8 v )
Gives you the hue of a color.
PREFIX Sint32 spGetHFromColor( Uint16 color )
Gives you the saturation of a color.
PREFIX Uint8 spGetSFromColor( Uint16 color )
Copies and scales source to destination very fast.
PREFIX void spScale2XFast( SDL_Surface * source, SDL_Surface * destination )
Like spScale2XFast, but with the MAME2x scale up algo.
PREFIX void spScale2XSmooth( SDL_Surface * source, SDL_Surface * destination )
Copies and scales down source to destination very fast.
PREFIX void spScaleDownFast( SDL_Surface * source, SDL_Surface * destination )
Copies and scales down source to destination with anti aliasing.
PREFIX void spScaleDownSmooth( SDL_Surface * source, SDL_Surface * destination )
Adds a border to the surface with the background color backgroundcolor.
PREFIX void spAddBorder( SDL_Surface * surface, Uint16 borderColor, Uint16 backgroundcolor )
This functions merges two same sized (!)
PREFIX void spStereoMergeSurfaces( SDL_Surface * left, SDL_Surface * right, int crossed )
Selects the render surface.
PREFIX void spSelectRenderTarget( SDL_Surface * target )