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.

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!) has analog sticks, these are the limits, from which the generic axes are uneven 0 or reseted to 0 again.

SP_JOYSTICK_MIN_TRIGGER_ON

maximal value for activating the negative axis.

SP_JOYSTICK_MIN_TRIGGER_OFF

maximal value for not setting the axis to zero.

SP_JOYSTICK_MAX_TRIGGER_ON

minimal value for activating the positive axis.

SP_JOYSTICK_MAX_TRIGGER_OFF

maximal value for not setting the axis to zero.

Generic button and axis count

SP_INPUT_BUTTON_COUNT

number of useable generic buttons.

SP_INPUT_AXIS_COUNT

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

Return types for spGetLastAxisType

SP_CACHE_SIZE

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

w

width of the window

h

height 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

text

debug 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

width

width of the window. Ignored for most handhelds because of fullscreen

height

height of the window. Ignored for most handhelds because of fullscreen

See Also

spGetLastAxisType

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

Returns

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

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

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.

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.

spSetReturnBehavior

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

Parameters

ignore

Return should be ignored and not appear in the keyboard buffer

stops

Return should stop the keyboard polling.

spIsKeyboardPolled

PREFIX int spIsKeyboardPolled(

void

)

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

int

1 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!

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.

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.

spSetVirtualKeyboardShiftState

PREFIX void spSetVirtualKeyboardShiftState(

int

state

)

Sets the state of the Shift mode of the virtual keyboard.

Parameters

state

1 shift shall be on, 0 shift shall be off

spGetVirtualKeyboardShiftState

PREFIX int spGetVirtualKeyboardShiftState(

void

)

Returns the state of the Shift mode of the virtual keyboard.

Returns

int

1 shift is on, 0 shift is off

spSetVirtualKeyboardSpaceButton

PREFIX void spSetVirtualKeyboardSpaceButton(

int

button

)

Sets a button, which is used as space if text is entered via virtual keyboard.

Parameters

button

button id to use, e.g. SP_BUTTON_X or SP_PRACTICE_3

spSetVirtualKeyboardBackspaceButton

PREFIX void spSetVirtualKeyboardBackspaceButton(

int

button

)

Sets a button, which is used as backspace if text is entered via virtual keyboard.

Parameters

button

button id to use, e.g. SP_BUTTON_X or SP_PRACTICE_3

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_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”

spSleep

PREFIX void spSleep(

Uint32

microSeconds

)

Waits the given microseconds (!). On some systems (e.g. linux) it gives the time to other threads and processes, which is quite usefull.

Parameters

microSeconds

the time to wait in microseconds

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

int

the frame per second

spGetSizeFactor

PREFIX Sint32 spGetSizeFactor(

void

)

Returns a fixed point factor for the screen size.

Returns

Sint32

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

spLoadSurface

PREFIX SDL_Surface* spLoadSurface(

const

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

spLoadSurfaceZoom

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.

Parameters

Returns

SDL_Surface*

the loaded and zoomed 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

surface

the 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 surface

doesn’t matter, whether caching is enabled or not.

Parameters

surface

the surface to be copied

Returns

SDL_Surface*

the copy

spEnableCaching

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

spDisableCaching

PREFIX void spDisableCaching(

void

)

Disables chaching of surfaces.

spIsCachingEnabled

PREFIX int spIsCachingEnabled(

void

)

Says, whether caching of surfaces is enabled or not.

Returns

int

1 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

width

the width of the surface

height

the 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

surface

the surface to be deleted

spClearCache

PREFIX void spClearCache(

void

)

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

r

red color parameter

g

green color parameter

b

blue color parameter

Returns

Uint16

16 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

r

red color parameter

g

green color parameter

b

blue color parameter

Returns

Uint16

16 bit color value

spGetRFromColor

Gives you the red value of a color. The result is an 8bit integer.

Parameters

color

the color

Returns

int

the red value

spGetGFromColor

Gives you the green value of a color. The result is an 8bit integer.

Parameters

color

the color

Returns

int

the green value

spGetBFromColor

Gives you the blue value of a color. The result is an 8bit integer.

Parameters

color

the color

Returns

int

the blue value

spGetRawRFromColor

Gives you the red value of a color. The result is a 5bit integer and can easily (and fast) be recalculated to a color via color = (r<<11) | (g<<5) | b;

Parameters

color

the color

Returns

int

the red value

spGetRawGFromColor

Gives you the greeen value of a color. The result is a 6bit integer and can easily (and fast) be recalculated to a color via color = (r<<11) | (g<<5) | b;

Parameters

color

the color

Returns

int

the green value

spGetRawBFromColor

Gives you the blue value of a color. The result is a 5bit integer and can easily (and fast) be recalculated to a color via color = (r<<11) | (g<<5) | b;

Parameters

color

the color

Returns

int

the blue value

spGetHSV

PREFIX Uint16 spGetHSV(

Sint32

h,

Uint8

s,

Uint8

v

)

Returns a 16 bit color defined by the HSV values.

Parameters

h

the h value of the HSV model

s

the s value of the HSV model

v

the v value of the HSV model

Returns

Uint16

16 bit color value

spGetHFromColor

PREFIX Sint32 spGetHFromColor(

Uint16

color

)

Gives you the hue of a color. The result is a fixed point number from 0 to 2*SP_PI.

Parameters

color

the color

Returns

Sint32

the hue as fixed point number from 0 to 2*SP_PI.

spGetSFromColor

PREFIX Uint8 spGetSFromColor(

Uint16

color

)

Gives you the saturation of a color. The result is a 8bit integer.

Parameters

color

the color

Returns

Uint8

the saturation

spGetSFromColor

Gives you the value of a color. The result is a 8bit integer.

Parameters

color

the color

Returns

Uint8

the 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

source

source surface

destination

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

See Also

spAddBorder

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

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)