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.  Furthermore here are some helper functions like converting colors or checking, whether a file exists.

Summary
sparrowCoreSparrowCore 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 sticksIf a REAL input device (not the sparrow3d generic input device!)
Generic button and axis count
Keyboard waitingIf 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.
SP_CACHE_SIZEThe size of the surface cache
Types
spInputThis struct contains information about the generic input device sparrowCore provides, which is same on every device
Functions
spSetDefaultWindowSizeSets defaults values for the window.
spInitCorespInitCore initializes SDL, SDL_TTF and other stuff.
spPrintDebugspPrintDebug prints debug stuff with timestamp
spCreateWindowCreates the Window in the plattform depended resolution.
spCreateDefaultWindowCreates a default window with no fullscreen for PC, but resizeable for PC.
spGetWindowSurfaceReturns the window Surface.
spLoopStarts a main loop
spFlipDraws the changes in the window Surface on the screen.
spGetInputReturns a pointer of the spInput struct, where the input values will be set.
spResetButtonsStateResets the state of any button in the generic device to 0 (=unpressed)
spResetAxisStateResets the state of any axis (digital and analog) in the generic device to 0 (=unpressed)
spPollKeyboardInputPrints all following keyboard input (that is numbers, letters and symbols) into the passed buffer.
spStopKeyboardInput:Stops keyboard input.
spIsKeyboardPolledSays, whether input from the keyboard is polled.
spSetVirtualKeyboardSets up a virtual keyboard especially for systems without a keyboard like the gp2x, caanoo, etc.
spGetVirtualKeyboardThis functions returns the precalculated and prescaled keyboard design.
spSetTouchscreenEmulationButtonsSets, whether on systems without touchscreen or mouse (like the GP2X F100) a touchscreen is emulated.
spQuitCoreJust quits the Core.
spGetFPSReturns the FPS of the Loop Function
spGetSizeFactorReturns a fixed point factor for the screen size.
spLoadSurfaceLoads a 16 Surface needed by the engine.
spCopySurfaceThis creates a “copy” of a surface.
spUniqueCopySurface
spEnableCachingEnables caching surfaces.
spDisableCachingDisables chaching of surfaces.
spIsCachingEnabledSays, whether caching of surfaces is enabled or not.
spCreateSurfaceCreates a 16 Surface 100% compatible to the engine.
spDeleteSurfaceDeletes a surface, if it is not cached or the reference counter reaches 0.
spClearCacheDeletes ALL cached surfaces! 
spGetRGBReturns a 16 bit RGB color
spGetFastRGBReturns 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!
spGetHSVReturns a 16 bit color defined by the HSV values.
spScale2XFastCopies and scales source to destination very fast.
spScale2XSmoothLike spScale2XFast, but with the MAME2x scale up algo.
spAddBorderAdds a border to the surface with the background color backgroundcolor.
spStereoMergeSurfacesThis functions merges two same sized (!)

Macros

Range of the analog axis

SP_ANALOG_AXIS_MINThe minimal value of the analog axis.
SP_ANALOG_AXIS_MAXThe maximal value of the analog axis.

Trigger limits for analog sticks

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.

SP_JOYSTICK_MIN_TRIGGER_ONmaximal value for activating the negative axis.
SP_JOYSTICK_MIN_TRIGGER_OFFmaximal value for not setting the axis to zero.
SP_JOYSTICK_MAX_TRIGGER_ONminimal value for activating the positive axis.
SP_JOYSTICK_MAX_TRIGGER_OFFmaximal value for not setting the axis to zero.

Generic button and axis count

SP_INPUT_BUTTON_COUNTnumber of useable generic buttons.
SP_INPUT_AXIS_COUNTnumber of useable generic axes.

Keyboard waiting

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.

SP_KEYBOARD_FIRST_WAITTime to wait until the second key pressing.
SP_KEYBOARD_WAITTime to wait for longer key pressing.
SP_VIRTUAL_KEYBOARD_FIRST_WAITsame like SP_KEYBOARD_FIRST_WAIT, but for the virtual keyboard.
SP_VIRTUAL_KEYBOARD_WAITsame like SP_KEYBOARD_WAIT, but for the virtual keyboard.

Values for spSetVirtualKeyboard.

With spSetVirtualKeyboard you setup, when the virtual keyboard is used.

SP_VIRTUAL_KEYBOARD_NEVERThe virtual keyboard is never used.
SP_VIRTUAL_KEYBOARD_IF_NEEDEDThe virtual keyboard is used, if no hardware keyboard is avaible (GP2X, Dingoo, etc.).
SP_VIRTUAL_KEYBOARD_ALWAYSThe virtual keyboard is always used, even on devices with keyboard like a PC or the pandora.

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

Variables

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.

Functions

spSetDefaultWindowSize

PREFIX void spSetDefaultWindowSize(int w,
int h)

Sets defaults values for the window.  Only for PC (not handhelds!) and only useable before the spInitCore-function.

Parameters

wwidth of the window
hheight of the window

spInitCore

PREFIX void spInitCore(void)

spInitCore initializes SDL, SDL_TTF and other stuff.

spPrintDebug

PREFIX void spPrintDebug(char *text)

spPrintDebug prints debug stuff with timestamp

Parameters

textdebug information to print

spCreateWindow

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.

Parameters

widthwidth of the window.  Ignored for most handhelds because of fullscreen
heightheight of the window.  Ignored for most handhelds because of fullscreen
fullscreen1 means fullscreen, 0 means no fullscreen.  Ignored for most handhelds, because always fullscreen
allowresizedetermines, whether the window is resizeable.  Ignored for most handhelds

Returns

SDL_Surface*Window surface.  If you want to draw to it with sparrow3d, dont’t forget to call spSelectRenderTarget.

spCreateDefaultWindow

PREFIX SDL_Surface* spCreateDefaultWindow(void)

Creates a default window with no fullscreen for PC, but resizeable for PC.

Returns

SDL_Surface*the window surface

spGetWindowSurface

PREFIX SDL_Surface* spGetWindowSurface(void)

Returns the window Surface.

Returns

SDL_Surface*the window surface

spLoop

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

Parameters

spDrawthe drawing function
spCalcthe calculation function.  If it returns a value unequal 0 it loop stops.  The given steps are the ms since the last frame.  Always > 0!
minwaitminimal time between two drawing steps.  Usefull for setting maximal frames per seconds, e.g. use 10 for 100 fps or 16 for ~62 fps.
spResizeFeedback 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.
spEventif this feedback function is given, it gets every SDL event, that has passed the mainloop to react to it (,too).

Returns

intthe value spCalc returned

spFlip

PREFIX void spFlip(void)

Draws the changes in the window Surface on the screen.

spGetInput

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!

Returns

PspInputA pointer to a spInput struct

spResetButtonsState

PREFIX void spResetButtonsState(void)

Resets the state of any button in the generic device to 0 (=unpressed)

See Also

spResetAxisState

spResetAxisState

PREFIX void spResetAxisState(void)

Resets the state of any axis (digital and analog) in the generic device to 0 (=unpressed)

See Also

spResetButtonsState

spPollKeyboardInput

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.

Parameters

bufferthe buffer for the input
buffersizethe maximum size of the passed buffer
enter_key_maskdetermines 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.

spStopKeyboardInput:

Stops keyboard input.  Any input following this call will not be passed to a buffer, rather will be ignored.  This function will not be called automatically when the buffer passed to spPollKeyboardInput is full.

spIsKeyboardPolled

PREFIX int spIsKeyboardPolled()

Says, whether input from the keyboard is polled.  Usefull for that you don’t react to “ingame controls” if e.g. a highscore name is entered or to show the virtual keyboard.

Returns

int1 if polled, 0 if not polled

spSetVirtualKeyboard

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!

Parameters

stateCan be SP_VIRTUAL_KEYBOARD_NEVER, SP_VIRTUAL_KEYBOARD_IF_NEEDED, SP_VIRTUAL_KEYBOARD_ALWAYS.  See definitions for the function.
x, ydetermines where you will draw the onscreen keyboard (later).
widthwidth of the onscreen keyboard
heightheight of the onscreen keyboard Necessary for interpretating the touchscreen input (offset!)
designYou 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.
shiftDesignlike design, but it is shown, if Shift is enabled.

spGetVirtualKeyboard

PREFIX SDL_Surface* spGetVirtualKeyboard()

This functions returns the precalculated and prescaled keyboard design.

Returns

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.

spSetTouchscreenEmulationButtons

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.

Parameters

switch_buttonif 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_buttonthe button for clicking the “mouse”

spQuitCore

PREFIX void spQuitCore(void)

Just quits the Core.  If you don’t use it everytime you close your game the flying spaghetti monster will kill a kitten.

spGetFPS

PREFIX int spGetFPS(void)

Returns the FPS of the Loop Function

Returns

intthe frame per second

spGetSizeFactor

PREFIX Sint32 spGetSizeFactor(void)

Returns a fixed point factor for the screen size.

Returns

Sint32the size factor.  It is SP_ONE for the gp2x (320 x 240)

spLoadSurface

PREFIX SDL_Surface* spLoadSurface(char *name)

Loads a 16 Surface needed by the engine.  If enabled it will be cached.

Parameters

char*filename of the image to load

Returns

SDL_Surface*the loaded surface

spCopySurface

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.

Parameters

surfacethe surface to be copied

Returns

SDL_Surface*the “copy”

spUniqueCopySurface

PREFIX SDL_Surface* spUniqueCopySurface(SDL_Surface *surface)
This call creates a *real* copy of a surfacedoesn’t matter, whether caching is enabled or not.

Parameters

surfacethe surface to be copied

Returns

SDL_Surface*the copy

spEnableCaching

PREFIX void spEnableCaching()

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

spDisableCaching

PREFIX void spDisableCaching()

Disables chaching of surfaces.

spIsCachingEnabled

PREFIX int spIsCachingEnabled()

Says, whether caching of surfaces is enabled or not.

Returns

int1 means caching is enabled, 0 not enabled

spCreateSurface

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 ;-) )

Parameters

widththe width of the surface
heightthe height of the surace

Returns

SDL_Surface*the created surface

spDeleteSurface

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!

Parameters

surfacethe surface to be deleted

spClearCache

PREFIX void spClearCache()

Deletes ALL cached surfaces!  You can’t use them anymore and have to reload them!

spGetRGB

PREFIX Uint16 spGetRGB(int r,
int g,
int b)

Returns a 16 bit RGB color

Parameters

rred color parameter
ggreen color parameter
bblue color parameter

Returns

Uint1616 bit color value

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!

Parameters

rred color parameter
ggreen color parameter
bblue color parameter

Returns

Uint1616 bit color value

spGetHSV

PREFIX Uint16 spGetHSV(Sint32 h,
Uint8 s,
Uint8 v)

Returns a 16 bit color defined by the HSV values.

Parameters

hthe h value of the HSV model
sthe s value of the HSV model
vthe v value of the HSV model

Returns

Uint1616 bit color value

spScale2XFast

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).

Parameters

sourcesource surface
destinationdestination surface.  Have to have the double width and double height of the source surface.

See Also

spScale2XSmooth

spScale2XSmooth

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.

Parameters

sourcesource surface
destinationdestination surface.  Have to have the double width and double height of the source surface.

See Also

spScale2XFast

spAddBorder

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

spStereoMergeSurfaces

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.

Parameters

leftthe left surface in which will be drawn, too
rightthe right surface, it will only be read
crosseddetermines, whether the merge is or-based or two-images-based (See above)
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.
PREFIX void spSetDefaultWindowSize(int w,
int h)
Sets defaults values for the window.
PREFIX void spInitCore(void)
spInitCore initializes SDL, SDL_TTF and other stuff.
PREFIX void spPrintDebug(char *text)
spPrintDebug prints debug stuff with timestamp
PREFIX SDL_Surface* spCreateWindow(int width,
int height,
int fullscreen,
int allowresize)
Creates the Window in the plattform depended resolution.
PREFIX SDL_Surface* spCreateDefaultWindow(void)
Creates a default window with no fullscreen for PC, but resizeable for PC.
PREFIX SDL_Surface* spGetWindowSurface(void)
Returns the window Surface.
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
PREFIX void spFlip(void)
Draws the changes in the window Surface on the screen.
PREFIX PspInput spGetInput(void)
Returns a pointer of the spInput struct, where the input values will be set.
PREFIX void spResetButtonsState(void)
Resets the state of any button in the generic device to 0 (=unpressed)
PREFIX void spResetAxisState(void)
Resets the state of any axis (digital and analog) in the generic device to 0 (=unpressed)
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.
PREFIX int spIsKeyboardPolled()
Says, whether input from the keyboard is polled.
PREFIX SDL_Surface* spGetVirtualKeyboard()
This functions returns the precalculated and prescaled keyboard design.
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.
PREFIX void spQuitCore(void)
Just quits the Core.
PREFIX int spGetFPS(void)
Returns the FPS of the Loop Function
PREFIX Sint32 spGetSizeFactor(void)
Returns a fixed point factor for the screen size.
PREFIX SDL_Surface* spLoadSurface(char *name)
Loads a 16 Surface needed by the engine.
PREFIX SDL_Surface* spCopySurface(SDL_Surface *surface)
This creates a “copy” of a surface.
PREFIX SDL_Surface* spUniqueCopySurface(SDL_Surface *surface)
PREFIX void spEnableCaching()
Enables caching surfaces.
PREFIX void spDisableCaching()
Disables chaching of surfaces.
PREFIX int spIsCachingEnabled()
Says, whether caching of surfaces is enabled or not.
PREFIX SDL_Surface* spCreateSurface(int width,
int height)
Creates a 16 Surface 100% compatible to the engine.
PREFIX void spDeleteSurface(SDL_Surface *surface)
Deletes a surface, if it is not cached or the reference counter reaches 0.
PREFIX void spClearCache()
Deletes ALL cached surfaces! 
PREFIX Uint16 spGetRGB(int r,
int g,
int b)
Returns a 16 bit RGB color
PREFIX Uint16 spGetHSV(Sint32 h,
Uint8 s,
Uint8 v)
Returns a 16 bit color defined by the HSV values.
PREFIX void spScale2XFast(SDL_Surface *source,
SDL_Surface *destination)
Copies and scales source to destination very fast.
PREFIX void spScale2XSmooth(SDL_Surface *source,
SDL_Surface *destination)
Like spScale2XFast, but with the MAME2x scale up algo.
PREFIX void spAddBorder(SDL_Surface *surface,
Uint16 borderColor,
Uint16 backgroundcolor)
Adds a border to the surface with the background color backgroundcolor.
PREFIX void spStereoMergeSurfaces(SDL_Surface *left,
SDL_Surface *right,
int crossed)
This functions merges two same sized (!)
The minimal value of the analog axis.
The maximal value of the analog axis.
PREFIX void spSelectRenderTarget(SDL_Surface *target)
Selects the render surface.
This struct contains information about the generic input device sparrowCore provides, which is same on every device
The virtual keyboard is never used.
The virtual keyboard is used, if no hardware keyboard is avaible (GP2X, Dingoo, etc.)
The virtual keyboard is always used, even on devices with keyboard like a PC or the pandora.
Close