sparrowPrimitives

SparrowPrimitives is for drawing primitives like triangles or quads (with and without texture), blitting or rotozooming of surfaces, lines, ellipses, rectangles and for everything it provides a zBuffer test and set.  You have to understand the difference between your screen / window, which could be (but doesn’t have to!) provided by sparrowCore (spCreateWindow), and your target, which can be every surface.  Every call from this file, draws to the target.  This may be your screen - but have not to be!  Every SDL Surface* could be the target.

Some words to the z Buffer: First of all.  If you don’t want any z buffering or stuff like this, call spSetZSet (0); and spSetZTest (0); at beginning.  Z-Buffers will be created and cached, but not used.  Furthermore most calls will be faster, but you loose a lot of fun and possibilities and have to think harder about sorting and stuff.  :-P But if you use it, keep in mind, that the nearest z value is 0 and the farest away z value is set by spSetZFar-spSetZNear and positive.  In difference to sparrowRenderer, which operates in the 3D space, where the z value go from -spSetZNear to -spSetZFar and are automaticly set by the projection setup function!  So always think about the system you use:

If Z-Test is enabled, a pixel with a greater z-value than an already drawn pixel will not be drawn, because the new pixel would be “deeper in the screen”.

Some words to the order of definition of edges of triangles and quads: It matter!  You have to define the edges counterclockwise, if you activated culling with spSetCulling, which is nevertheless on at default!

C________B    E.g. the triangle A(150,150) B(200,100) C(100,100) is
 \      /     is definied counterclockwise (z doesn't matter here)
  \    /      and will be drawn. The triangle C B A would *not* be
   \  /       drawn. ;-)
    \/        The reason is to not draw not seeable triangles/quads
     A        of closed fields in the 3d space.

Some words to colors, too: Even if I use 32 Bit values, the engine works only with 16 Bit colors, with the 5 bit red, 6 bit green and 5 bit blue.  I just use 32 bit values, because it is faster as parameters.  Otherwise the compiler always would convert 16 bit to 32 bit and the other direction.  If the compiler “thinks”, that it is just 32 Bit, it is faster.

Summary
sparrowPrimitivesSparrowPrimitives is for drawing primitives like triangles or quads (with and without texture), blitting or rotozooming of surfaces, lines, ellipses, rectangles and for everything it provides a zBuffer test and set.
SP_MAX_SCANLINESThat much scanlines will be cached at most in the parallel drawing thread
Setup and getter functionsThese functions are for setting up all graphical stuff like the different per pixel tests (z, alpha, pattern), sets (z), other optional optimizations and also the Z-Buffer and it’s cache plus getting some pointers for faster direct access.
spInitPrimitivesInitializes some Look up tables and the zBufferCache.
spQuitPrimitivesReleases stuff and frees memory.
spGetOne_over_x_pointerReturns a pointer/array of SP_ONE (65536) values of 1/x
spSelectRenderTargetSelects the render surface.
spGetRenderTargetReturns the render target.
spGetTargetPixelReturns a pointer to the raw 16 bit pixel data.
spLockRenderTargetLocks the RenderTarget.
spUnlockRenderTargetUnlocks the RenderTarget.
spGetRenderTargetZBufferReturns a pointer to the zBuffer of the render target
spBindTextureThis texture will be used for all following draw operations with textures
spSetZTest(De)Activates the Z test (default on).
spSetZSet(De)Activates the Z set (default on).
spSetAlphaTest(De)Activates the alpha test (default on).
spSetBlending(De)Activates real blending.
spEmulateBlendingWithPatternDecides, whether real blending (maybe slow) is used or an emulation of blending using pattern in a dithering like way.
spSetAffineTextureHackThe texture rendering is fast, but a bit wrong.
spSetCulling(De)Activates culling.
spSetLineWidthSets the width of spLine calls.
spClearTargetClears the Rendertarget.
spSetZBufferCacheIf you use many Render Targets every time you switch it, the old ZBuffer will be destroyed and a new one created, which is slow.
spReAllocateZBufferReallocates the zBuffer.
spResetZBufferResets the zBuffer with the farest value.
spSetHorizontalOriginSets the horizontal origin of the Surface rectangle and ellipses functions.
spSetVerticalOriginSets the vertical origin of the Surface rectangle and ellipses functions.
spSetFixedOrignSets a fixed origin like (32,32).
spGetHorizontalOriginReturns the horizontal origin.
spGetVerticalOriginReturns the vertical origin.
spSetZFarSets the value, to which the zbuffer will be reseted.
spGetZFarGets the value, to which the zbuffer will be reseted.
spSetZNearSets the value, to which the zbuffer will be reseted.
spGetZNearGets the value, to which the zbuffer will be reseted.
spGetPixelPositionReturns where the pixel is in relation to the screen.
Drawing functionsAll these functions use (optional) z test, z set, alpha test and pattern test except spHorizentalLine, <spAddWhiteLayer> and <spAddBlackLayer>
spTriangleDraws a colored Triangle.
spTriangle_texDraws a colored Triangle with texture mapping.
spPerspectiveTriangle_texDraws a colored Triangle with perspectively correct texture mapping.
spQuadDraws a colored quad.
spQuad_texDraws a colored quad with texture mapping.
spPerspectiveQuad_texDraws a colored quad with perspectively correct texture mapping.
spBlitSurfaceDraws a Surface on the target.
spBlitSurfacePartDraws a part of a Surface on the target.
spRotozoomSurfaceDraws a surface with rotozoom (Free rotating and zooming of the surface).
spRotozoomSurfacePartDraws a part of a surface with rotozoom (Free rotating and zooming of the surface).
spLineDraws a colored line
spRectangleDraws a filled Rectangle.
spRectangleBorderDraws a filled Rectangle border.
spEllipseDraws a filled ellipse.
spEllipseBorderDraws a filled ellipse border.
spHorizentalLineDraws a fast horizental line with one color.
spAddColorToTargetAdds a colored layer to the target surface.
spInterpolateTargetToColorInterpolates the target to a color.
Pattern functionssparrow3d does provide alpha blending (see spSetBlending), but this is slow, so use it rarely or better never.
spSetPattern32Sets the pattern with two 32 bit ints, each defines 4 lines
spSetPattern64Sets the pattern with two 64 bit int, it defines all 8 lines
spSetPattern8Sets the pattern with eight 8 bit ints line by line
spDeactivatePatternDeactivates the pattern.
spSetAlphaPatternSets the pattern in dependence of an alpha value to “emulate” alpha blending.
spSetAlphaPattern4x4Works pretty like spSetAlphaPattern, but it uses 4x4 pattern internal.
spWaitForDrawingThreadIf parallel processing of sparrowPrimitive is activated, this function waits until everything is drawn.
spDrawInExtraThreadDetermines, whether an extra thread is used for drawing.
spUpdateTargetPixelsUpdates the internal pixels pointer used by sparrow3d.
spFloodFillFills the target at the given position with a color using flood fill.

SP_MAX_SCANLINES

That much scanlines will be cached at most in the parallel drawing thread

Setup and getter functions

These functions are for setting up all graphical stuff like the different per pixel tests (z, alpha, pattern), sets (z), other optional optimizations and also the Z-Buffer and it’s cache plus getting some pointers for faster direct access.

spInitPrimitives

PREFIX void spInitPrimitives(void)

Initializes some Look up tables and the zBufferCache.  Is called by spInitCore.

spQuitPrimitives

PREFIX void spQuitPrimitives(void)

Releases stuff and frees memory.  Is called by spQuitCore.

spGetOne_over_x_pointer

PREFIX Sint32* spGetOne_over_x_pointer(void)

Returns a pointer/array of SP_ONE (65536) values of 1/x

Returns

Sint32*the pointer/array

spSelectRenderTarget

PREFIX void spSelectRenderTarget(SDL_Surface *target)

Selects the render surface.  Attention: With every change of the target a new z Buffer is created or a cached is used.  However, you can’t be sure of the content of the zbuffer after this call!

Parameters

targetthe new target every draw call will render to.  If NULL the target is set to Null, but the old target is unlocked.

spGetRenderTarget

PREFIX SDL_Surface* spGetRenderTarget(void)

Returns the render target.

Returns

SDL_Surface*the render target

spGetTargetPixel

PREFIX Uint16* spGetTargetPixel(void)

Returns a pointer to the raw 16 bit pixel data.  Keep in mind to change the zBuffer too, if you need it!

Returns

Uint16*16 bit int pointer / array for free access.  Keep the dimension of the array in mind, which is renderTarget->pitch/renderTarget->format->BytesPerPixel * renderTarget->h.

See Also

spGetRenderTargetZBuffer

spLockRenderTarget

PREFIX void spLockRenderTarget(void)

Locks the RenderTarget.  Per default the target surface is locked all the time, so only call this function, if you called spUnlockRenderTarget before.

See Also

spUnlockRenderTarget

spUnlockRenderTarget

PREFIX void spUnlockRenderTarget(void)

Unlocks the RenderTarget.  At default the sparrow3d targets are locked, so if you lock it e.g. for SDL calls, don’t forget to lock it afterwards with spLockRenderTarget.

See Also

spLockRenderTarget

spGetRenderTargetZBuffer

PREFIX Sint32* spGetRenderTargetZBuffer(void)

Returns a pointer to the zBuffer of the render target

Returns

Sint32*the z-buffer pointer.  Keep the dimension of the array in mind, which is renderTarget->pitch/renderTarget->format->BytesPerPixel * renderTarget->h

spBindTexture

PREFIX void spBindTexture(SDL_Surface *texture)

This texture will be used for all following draw operations with textures

Parameters

texturethe texture to be used

spSetZTest

PREFIX void spSetZTest(Uint32 test)

(De)Activates the Z test (default on).

Parameters

test1 means on, 0 means off

See Also

spSetZSet, spSetAlphaTest

spSetZSet

PREFIX void spSetZSet(Uint32 test)

(De)Activates the Z set (default on).

Parameters

test1 means on, 0 means off

See Also

spSetZTest, spSetAlphaTest

spSetAlphaTest

PREFIX void spSetAlphaTest(Uint32 test)

(De)Activates the alpha test (default on).  It tests against SP_ALPHA_COLOR.

Parameters

test1 means on, 0 means off

See Also

spSetZSet, spSetZTest

spSetBlending

PREFIX void spSetBlending(Sint32 value)

(De)Activates real blending.  Every primitive, rectangle, ellipse, blitted or rotozoomed surface is blended.  But keep in mind, that this is sloooow.  Especially with rotozoom!  Use it rarely or think about spSetAlphaPattern.  On slower targets (e.g. the gp2x) at default blending is done via pattern emulation, see spEmulateBlendingWithPattern.

Paramaters

value0 is total transparent, SP_ONE is total opaque.  Everything in between will be blended.  If value is SP_ONE internal no blending is done

spEmulateBlendingWithPattern

PREFIX void spEmulateBlendingWithPattern(Sint32 value)

Decides, whether real blending (maybe slow) is used or an emulation of blending using pattern in a dithering like way.

Paramaters

value0 means no emulation is done, 1 (default) means, that emulation is done on slow systems like the gp2x and 2 means, that emulation is done all the time even on quite fast targets like the gcw zero.

spSetAffineTextureHack

PREFIX void spSetAffineTextureHack(Uint32 test)

The texture rendering is fast, but a bit wrong.  It is affine.  To reduce this effect, which is best seeable with big, quadratic faces, activate this dirty hack.  It could be a bit slower.  Only affects Quads

Parameters

test0 deactivates this hack (default), 1 makes look it better and 2 the best.  However most of the times you will not see any difference between 1 and 2

spSetCulling

PREFIX void spSetCulling(char value)

(De)Activates culling.  Culling means, that depending on the order of the edges, the primitive is drawn - or not.  Default is on.  That means: Every primitive defined counterclockwise will be drawn.  That’s very important for Rendering meshes, because you can’t see the backside of a triangle or quad of an object.  So why drawing it?

Parameters

value1 means on, 0 means off

spSetLineWidth

PREFIX void spSetLineWidth(Sint32 width)

Sets the width of spLine calls.

Parameter

widththe width of the line in pixel

spClearTarget

PREFIX void spClearTarget(Uint32 color)

Clears the Rendertarget.  The Z Buffer is not cleand!

Parameters

color16 bit color.  The target will be filled with this color.

See Also

spResetZBuffer

spSetZBufferCache

PREFIX void spSetZBufferCache(Uint32 value)

If you use many Render Targets every time you switch it, the old ZBuffer will be destroyed and a new one created, which is slow.  So I implemented this caching.  The engine will hold as much Z-Buffers as you say.  Default: 16

Parameters

valuecount of Z-Buffers to hold cached

spReAllocateZBuffer

PREFIX void spReAllocateZBuffer(void)

Reallocates the zBuffer.  If you switch to a new Render Target, this function is called.

spResetZBuffer

PREFIX void spResetZBuffer(void)

Resets the zBuffer with the farest value.  If you switch to a new Render Target, this function is NOT called.  You have to call it before you draw by yourself!

See Also

spClearTarget

spSetHorizontalOrigin

PREFIX void spSetHorizontalOrigin(Sint32 origin)

Sets the horizontal origin of the Surface rectangle and ellipses functions.

Parameters

originSP_LEFT for left origin, SP_RIGHT for right origin and SP_CENTER (default) for centered origin.  Use SP_FIXED and spSetFixedOrign for a fixed origin.

See Also

spSetVerticalOrigin

spSetVerticalOrigin

PREFIX void spSetVerticalOrigin(Sint32 origin)

Sets the vertical origin of the Surface rectangle and ellipses functions.

Parameters

originSP_TOP for top origin, SP_BOTTOM for bottom origin and SP_CENTER (default) for centered origin.  Use SP_FIXED and spSetFixedOrign for a fixed origin.

See Also

spSetHorizontalOrigin

spSetFixedOrign

PREFIX void spSetFixedOrign(int x,
int y)

Sets a fixed origin like (32,32).  You have to pass SP_FIXED to spSetVerticalOrigin and spSetHorizontalOrigin.

Parameters

x,yfixed pixel position of the origin.  Default is (0,0).

See also

spSetVerticalOrigin, spSetHorizontalOrigin

spGetHorizontalOrigin

PREFIX Sint32 spGetHorizontalOrigin(void)

Returns the horizontal origin.

Returns

Sint32SP_LEFT for left origin, SP_RIGHT for right origin and SP_CENTER (default) for centered origin

spGetVerticalOrigin

PREFIX Sint32 spGetVerticalOrigin(void)

Returns the vertical origin.

Returns

Sint32SP_TOP for top origin, SP_BOTTOM for bottom origin and SP_CENTER (default) for centered origin

spSetZFar

PREFIX void spSetZFar(Sint32 zfar)

Sets the value, to which the zbuffer will be reseted.  Mostly called by spSetPerspective

Parameters

zfarnew farest value.  Has to be positive

See Also

spGetZFar, spSetZNear

spGetZFar

PREFIX Sint32 spGetZFar(void)

Gets the value, to which the zbuffer will be reseted.

Returns

Sint32the farest z value

See Also

spSetZFar, spGetZNear

spSetZNear

PREFIX void spSetZNear(Sint32 znear)

Sets the value, to which the zbuffer will be reseted.  Mostly called by spSetPerspective

Parameters

znearnew nearest value.  Has to be positive

See Also

spSetZFar, spGetZNear

spGetZNear

PREFIX Sint32 spGetZNear(void)

Gets the value, to which the zbuffer will be reseted.

Returns

Sint32the nearest z value

See Also

spGetZFar, spSetZNear

spGetPixelPosition

PREFIX int spGetPixelPosition(Sint32 x,
Sint32 y)

Returns where the pixel is in relation to the screen.

Parameters

x,yposition of the pixel

Returns

int1 means on the screen, 2 left of the screen, 4 lefttop, 8 top, 16 righttop, 32 right, 64 rightbottom, 128 bottom, 256 leftbottom

Drawing functions

All these functions use (optional) z test, z set, alpha test and pattern test except spHorizentalLine, <spAddWhiteLayer> and <spAddBlackLayer>

spTriangle

PREFIX int spTriangle(Sint32 x1,
Sint32 y1,
Sint32 z1,
Sint32 x2,
Sint32 y2,
Sint32 z2,
Sint32 x3,
Sint32 y3,
Sint32 z3,
Uint32 color)

Draws a colored Triangle.  The z value is interpolated over the triangle.  Don’t forget to defines the edges counterclockwise if culling is enabled.

Parameters

x1,y1,z1position and z value of the first edge
x2,y2,z2position and z value of the second edge
x3,y3,z3position and z value of the third edge
color16 bit color of the whole triangle

Returns

int0 if not drawn (culling) or different bits, which define, where the edges are: 1 on screen, 2 left of screen, 4 lefttop, 8 top, 16 righttop, 32 right, 64 rightbottom, 128 bottom, 256 leftbottom

spTriangle_tex

PREFIX int spTriangle_tex(Sint32 x1,
Sint32 y1,
Sint32 z1,
Sint32 u1,
Sint32 v1,
Sint32 x2,
Sint32 y2,
Sint32 z2,
Sint32 u2,
Sint32 v2,
Sint32 x3,
Sint32 y3,
Sint32 z3,
Sint32 u3,
Sint32 v3,
Uint32 color)

Draws a colored Triangle with texture mapping.  The z value is interpolated over the triangle.  Don’t forget to defines the edges counterclockwise if culling is enabled.  Furthermore a texture had to be defined with spBindTexture.

Parameters

x1,y1,z1position and z value of the first edge
u1,v1texture coordinates of the first edge
x2,y2,z2position and z value of the second edge
u2,v2texture coordinates of the second edge
x3,y3,z3position and z value of the third edge
u3,v3texture coordinates of the third edge
color16 bit color of the whole triangle

Returns

int0 if not drawn (culling) or different bits, which define, where the edges are: 1 on screen, 2 left of screen, 4 lefttop, 8 top, 16 righttop, 32 right, 64 rightbottom, 128 bottom, 256 leftbottom

spPerspectiveTriangle_tex

PREFIX int spPerspectiveTriangle_tex(Sint32 x1,
Sint32 y1,
Sint32 z1,
Sint32 u1,
Sint32 v1,
Sint32 w1,
Sint32 x2,
Sint32 y2,
Sint32 z2,
Sint32 u2,
Sint32 v2,
Sint32 w2,
Sint32 x3,
Sint32 y3,
Sint32 z3,
Sint32 u3,
Sint32 v3,
Sint32 w3,
Uint32 color)

Draws a colored Triangle with perspectively correct texture mapping.  The z value is interpolated over the triangle.  Don’t forget to defines the edges counterclockwise if culling is enabled.  Furthermore a texture had to be defined with spBindTexture.

Parameters

x1,y1,z1position and z value of the first edge
u1,v1texture coordinates of the first edge
w1w clipping ordinate of the first edge.  It is a result of the projection.
x2,y2,z2position and z value of the second edge
u2,v2texture coordinates of the second edge
w2w clipping ordinate of the second edge.  It is a result of the projection.
x3,y3,z3position and z value of the third edge
u3,v3texture coordinates of the third edge
w3w clipping ordinate of the third edge.  It is a result of the projection.
color16 bit color of the whole triangle

Returns

int0 if not drawn (culling) or different bits, which define, where the edges are: 1 on screen, 2 left of screen, 4 lefttop, 8 top, 16 righttop, 32 right, 64 rightbottom, 128 bottom, 256 leftbottom

spQuad

PREFIX int spQuad(Sint32 x1,
Sint32 y1,
Sint32 z1,
Sint32 x2,
Sint32 y2,
Sint32 z2,
Sint32 x3,
Sint32 y3,
Sint32 z3,
Sint32 x4,
Sint32 y4,
Sint32 z4,
Uint32 color)

Draws a colored quad.  The z value is interpolated over the quad.  Don’t forget to defines the edges counterclockwise if culling is enabled.

Parameters

x1,y1,z1position and z value of the first edge
x2,y2,z2position and z value of the second edge
x3,y3,z3position and z value of the third edge
x4,y4,z4position and z value of the fourth edge
color16 bit color of the whole quad

Returns

int0 if not drawn (culling) or different bits, which define, where the edges are: 1 on screen, 2 left of screen, 4 lefttop, 8 top, 16 righttop, 32 right, 64 rightbottom, 128 bottom, 256 leftbottom

spQuad_tex

PREFIX int spQuad_tex(Sint32 x1,
Sint32 y1,
Sint32 z1,
Sint32 u1,
Sint32 v1,
Sint32 x2,
Sint32 y2,
Sint32 z2,
Sint32 u2,
Sint32 v2,
Sint32 x3,
Sint32 y3,
Sint32 z3,
Sint32 u3,
Sint32 v3,
Sint32 x4,
Sint32 y4,
Sint32 z4,
Sint32 u4,
Sint32 v4,
Uint32 color)

Draws a colored quad with texture mapping.  The z value is interpolated over the quad.  Don’t forget to defines the edges counterclockwise if culling is enabled.  Furthermore a texture had to be defined with spBindTexture.

Parameters

x1,y1,z1position and z value of the first edge
u1,v1texture coordinates of the first edge
x2,y2,z2position and z value of the second edge
u2,v2texture coordinates of the second edge
x3,y3,z3position and z value of the third edge
u3,v3texture coordinates of the third edge
x4,y4,z4position and z value of the fourth edge
u4,v4texture coordinates of the fourth edge
color16 bit color of the whole quad

Returns

int0 if not drawn (culling) or different bits, which define, where the edges are: 1 on screen, 2 left of screen, 4 lefttop, 8 top, 16 righttop, 32 right, 64 rightbottom, 128 bottom, 256 leftbottom

spPerspectiveQuad_tex

PREFIX int spPerspectiveQuad_tex(Sint32 x1,
Sint32 y1,
Sint32 z1,
Sint32 u1,
Sint32 v1,
Sint32 w1,
Sint32 x2,
Sint32 y2,
Sint32 z2,
Sint32 u2,
Sint32 v2,
Sint32 w2,
Sint32 x3,
Sint32 y3,
Sint32 z3,
Sint32 u3,
Sint32 v3,
Sint32 w3,
Sint32 x4,
Sint32 y4,
Sint32 z4,
Sint32 u4,
Sint32 v4,
Sint32 w4,
Uint32 color)

Draws a colored quad with perspectively correct texture mapping.  The z value is interpolated over the quad.  Don’t forget to defines the edges counterclockwise if culling is enabled.  Furthermore a texture had to be defined with spBindTexture.

Parameters

x1,y1,z1position and z value of the first edge
u1,v1texture coordinates of the first edge
w1w clipping ordinate of the first edge.  It is a result of the projection.
x2,y2,z2position and z value of the second edge
u2,v2texture coordinates of the second edge
w2w clipping ordinate of the second edge.  It is a result of the projection.
x3,y3,z3position and z value of the third edge
u3,v3texture coordinates of the third edge
w3w clipping ordinate of the third edge.  It is a result of the projection.
x4,y4,z4position and z value of the fourth edge
u4,v4texture coordinates of the fourth edge
w4w clipping ordinate of the fourth edge.  It is a result of the projection.
color16 bit color of the whole quad

Returns

int0 if not drawn (culling) or different bits, which define, where the edges are: 1 on screen, 2 left of screen, 4 lefttop, 8 top, 16 righttop, 32 right, 64 rightbottom, 128 bottom, 256 leftbottom

spBlitSurface

PREFIX void spBlitSurface(Sint32 x,
Sint32 y,
Sint32 z,
SDL_Surface *surface)

Draws a Surface on the target.  The origin is at the center as default.  Use spSetHorizontalOrigin and spSetVerticalOrigin to change this behaviour.

Parameters

x,y,zposition and z value, where to draw.
surfacethe surface to draw

See Also

spBlitSurfacePart

spBlitSurfacePart

PREFIX void spBlitSurfacePart(Sint32 x,
Sint32 y,
Sint32 z,
SDL_Surface *surface,
Sint32 sx,
Sint32 sy,
Sint32 w,
Sint32 h)

Draws a part of a Surface on the target.  The origin is at the center as default.  Use spSetHorizontalOrigin and spSetVerticalOrigin to change this behaviour.

Parameters

x,y,zposition and z value, where to draw.
surfacethe surface to draw
sx,syposition of the left top corner of the part of the surface to be drawn
w,hsize of the part to be drawn

See Also

spBlitSurface

spRotozoomSurface

PREFIX void spRotozoomSurface(Sint32 x,
Sint32 y,
Sint32 z,
SDL_Surface *surface,
Sint32 zoomX,
Sint32 zoomY,
Sint32 angle)

Draws a surface with rotozoom (Free rotating and zooming of the surface).  Blitting with spBlitSurface is much faster ;-).

Parameters

x,y,zposition and z value of the surface on the target
surfacesurface, which shall be rotozoomed
zoomX,zoomYx and y zoom of the surface.  These are fixed point factors, which means, that SP_ONE does nothing, a smaller value decreases and a bigger one increases the size
anglefixed point radian value for rotating.  Goes from 0 to 2*SP_PI

See Also

spRotozoomSurfacePart

spRotozoomSurfacePart

PREFIX void spRotozoomSurfacePart(Sint32 x,
Sint32 y,
Sint32 z,
SDL_Surface *surface,
Sint32 sx,
Sint32 sy,
Sint32 w,
Sint32 h,
Sint32 zoomX,
Sint32 zoomY,
Sint32 angle)

Draws a part of a surface with rotozoom (Free rotating and zooming of the surface).  Blitting with spBlitSurfacePart is much faster ;-).

Parameters

x,y,zposition and z value of the surface on the target
surfacesurface, which shall be rotozoomed
sx,syposition of the left top corner of the part of the surface to be drawn
w,hsize of the part to be drawn
zoomX,zoomYx and y zoom of the surface.  These are fixed point factors, which means, that SP_ONE does nothing, a smaller value decreases and a bigger one increases the size
anglefixed point radian value for rotating.  Goes from 0 to 2*SP_PI

See Also

spRotozoomSurface

spLine

PREFIX void spLine(Sint32 x1,
Sint32 y1,
Sint32 z1,
Sint32 x2,
Sint32 y2,
Sint32 z2,
Uint32 color)

Draws a colored line

Parameters

x1,y1,z1position and z value of the first edge
x2,y2,z2position and z value of the second edge
color16 bit color of the whole line

spRectangle

PREFIX void spRectangle(Sint32 x,
Sint32 y,
Sint32 z,
Sint32 w,
Sint32 h,
Uint32 color)

Draws a filled Rectangle.  The origin is at the center as default.  Use spSetHorizontalOrigin and spSetVerticalOrigin to change this behaviour.

Parameters

x,y,zposition and z value, where to draw
w,hsize of the rectangle
color16 bit color of the whole rectangle

spRectangleBorder

PREFIX void spRectangleBorder(Sint32 x,
Sint32 y,
Sint32 z,
Sint32 w,
Sint32 h,
Sint32 bx,
Sint32 by,
Uint32 color)

Draws a filled Rectangle border.  The origin is at the center as default.  Use spSetHorizontalOrigin and spSetVerticalOrigin to change this behaviour.

Parameters

x,y,zposition and z value, where to draw
w,hsize of the rectangle
bx,bysize of the border
color16 bit color of the whole rectangle border

spEllipse

PREFIX void spEllipse(Sint32 x,
Sint32 y,
Sint32 z,
Sint32 rx,
Sint32 ry,
Uint32 color)

Draws a filled ellipse.  The origin is at the center all the time.

Parameters

x,y,zposition and z value, where to draw
rx,ryradii of the ellipse
color16 bit color of the whole ellipse

spEllipseBorder

PREFIX void spEllipseBorder(Sint32 x,
Sint32 y,
Sint32 z,
Sint32 rx,
Sint32 ry,
Sint32 bx,
Sint32 by,
Uint32 color)

Draws a filled ellipse border.  The origin is at the center all the time.

Parameters

x,y,zposition and z value, where to draw
rx,ryradii of the ellipse
bx,bysize of the border
color16 bit color of the whole ellipse

spHorizentalLine

PREFIX void spHorizentalLine(Uint16 *pixel,
Sint32 x,
Sint32 y,
Sint32 l_,
Uint32 color_,
Uint32 check,
Sint32 engineWindowX,
Sint32 engineWindowY)

Draws a fast horizental line with one color.  Don’t forget to lock your surface for this function!  Use it e.g with spLockRenderTarget to get the pixel array and lock it automaticly.  Because of some optimizations I can’t do this for you.  If you are not sure, use spLine instead.  No z test, z set, alpha test and pattern test!

Parameters

pixelpointer to an Uint16 array of pixels
x,yposition of the line
l_length of the line (to the right)
color_16 bit color value of the line
checkif 1 it will checked, whether the line reaches the end of the surface borders, with 0 no check happens
engineWindowX,engineWindowYsize of the pixel array

spAddColorToTarget

PREFIX void spAddColorToTarget(Uint16 destColor,
Sint32 interpolation)

Adds a colored layer to the target surface.  Slow, but usefull for menu fade in and out.  No z test, z set, alpha test and pattern test!  If the color is brighter than white, it is clamped.

Parameters

destColorcolor to add
interpolationhow many parts of destColor shall be added?  0 means nothing, SP_ONE all

See Also

spInterpolateTargetToColor

spInterpolateTargetToColor

PREFIX void spInterpolateTargetToColor(Uint16 destColor,
Sint32 interpolation)

Interpolates the target to a color.  Slow, but usefull for menu fade in and out.  No z test, z set, alpha test and pattern test!

Parameters

destColorcolor to interpolate to
interpolationhow many parts of destColor shall be added?  0 means the target isn’t changed, with SP_ONE only destColor is left

See Also

spAddColorToTarget

Pattern functions

sparrow3d does provide alpha blending (see spSetBlending), but this is slow, so use it rarely or better never.  However, with these three functions you can get some kind of much faster dithering alpha effect.  In movement and on screens with a high dpi value it looks pretty good and is quite fast (as said before).

You setup a 8x8 1-bit-pattern (=64 bit), which is tested for as for z or alpha values.  If the pattern-bit says 1, the pixel is drawn, if 0 it is not drawn.  E.g. the mask

10101010
01010101
10101010
01010101
10101010
01010101
10101010
01010101

would make some kind of 50% alpha effect, because only 50% of the pixels are drawn.

spSetPattern32

PREFIX void spSetPattern32(Uint32 first_32_bit,
Uint32 last_32_bit)

Sets the pattern with two 32 bit ints, each defines 4 lines

Parameters

first_32_bit,last_32_bitthe two 32 bit ints

spSetPattern64

PREFIX void spSetPattern64(Uint64 pattern)

Sets the pattern with two 64 bit int, it defines all 8 lines

Parameters

patternthe big 64 bit int

spSetPattern8

PREFIX void spSetPattern8(Uint8 line1,
Uint8 line2,
Uint8 line3,
Uint8 line4,
Uint8 line5,
Uint8 line6,
Uint8 line7,
Uint8 line8)

Sets the pattern with eight 8 bit ints line by line

Parameters

line(1..8)the 8 bit int for the 8 lines

spDeactivatePattern

PREFIX void spDeactivatePattern(void)

Deactivates the pattern.  They are reactivated again with a call of one of the 3 functions above.

spSetAlphaPattern

PREFIX void spSetAlphaPattern(int alpha,
int shift)

Sets the pattern in dependence of an alpha value to “emulate” alpha blending.

Parameters

alphathe faked alpha value from 0 to 255
shiftShifting of the pattern, goes from 0 to 63.  The problem is: Two primitives drawn with the same pattern (== same alpha and shift value) will cover each other, because exactly the same pixel will not be drawn.  The alpha blending fake effect is gone.  Solution: Using alpha simulation just a bit, using very different alpha values for covering primitives and using different shift values for every primitive, but for better look use for every single primitive in every frame the same shifting value, else it will look shitty.

See Also

spSetAlphaPattern4x4

spSetAlphaPattern4x4

PREFIX void spSetAlphaPattern4x4(int alpha,
int shift)

Works pretty like spSetAlphaPattern, but it uses 4x4 pattern internal.  So there are only 16 different “alpha values”, but it looks better most of the time.  (And I think it is faster, too.)

Parameters

alphastill goes from 0 to 255, nevertheless only 16 value are used internal, so e.g the alpha value 3 and 7 are handeld the same way.
shiftgoes only from 0 to 15, but works in the same way as in spSetAlphaPattern

See Also

spSetAlphaPattern

spWaitForDrawingThread

PREFIX void spWaitForDrawingThread(void)

If parallel processing of sparrowPrimitive is activated, this function waits until everything is drawn.  If you want to draw stuff on your own, call this to be sure, that every change is done indeed!  If no parallel processing is activated nothing happens.

spDrawInExtraThread

PREFIX void spDrawInExtraThread(int value)

Determines, whether an extra thread is used for drawing.  May be a bit slower (!) on systems with just one processor, but muuuuch faster on systems with at least two processors.

Parameters

value0 means no draw thread (default), 1 means an extra thread

spUpdateTargetPixels

PREFIX void spUpdateTargetPixels(void)

Updates the internal pixels pointer used by sparrow3d.  Used by spFlip for compatibility with Double- or even Triplebuffering.

spFloodFill

PREFIX void spFloodFill(int x,
int y,
Uint16 color)

Fills the target at the given position with a color using flood fill.

Parameters

x,yposition to start filling
colorcolor to fill
PREFIX void spInitPrimitives(void)
Initializes some Look up tables and the zBufferCache.
PREFIX void spQuitPrimitives(void)
Releases stuff and frees memory.
PREFIX Sint32* spGetOne_over_x_pointer(void)
Returns a pointer/array of SP_ONE (65536) values of 1/x
PREFIX void spSelectRenderTarget(SDL_Surface *target)
Selects the render surface.
PREFIX SDL_Surface* spGetRenderTarget(void)
Returns the render target.
PREFIX Uint16* spGetTargetPixel(void)
Returns a pointer to the raw 16 bit pixel data.
PREFIX void spLockRenderTarget(void)
Locks the RenderTarget.
PREFIX void spUnlockRenderTarget(void)
Unlocks the RenderTarget.
PREFIX Sint32* spGetRenderTargetZBuffer(void)
Returns a pointer to the zBuffer of the render target
PREFIX void spBindTexture(SDL_Surface *texture)
This texture will be used for all following draw operations with textures
PREFIX void spSetZTest(Uint32 test)
(De)Activates the Z test (default on).
PREFIX void spSetZSet(Uint32 test)
(De)Activates the Z set (default on).
PREFIX void spSetAlphaTest(Uint32 test)
(De)Activates the alpha test (default on).
PREFIX void spSetBlending(Sint32 value)
(De)Activates real blending.
PREFIX void spEmulateBlendingWithPattern(Sint32 value)
Decides, whether real blending (maybe slow) is used or an emulation of blending using pattern in a dithering like way.
PREFIX void spSetAffineTextureHack(Uint32 test)
The texture rendering is fast, but a bit wrong.
PREFIX void spSetCulling(char value)
(De)Activates culling.
PREFIX void spSetLineWidth(Sint32 width)
Sets the width of spLine calls.
PREFIX void spLine(Sint32 x1,
Sint32 y1,
Sint32 z1,
Sint32 x2,
Sint32 y2,
Sint32 z2,
Uint32 color)
Draws a colored line
PREFIX void spClearTarget(Uint32 color)
Clears the Rendertarget.
PREFIX void spSetZBufferCache(Uint32 value)
If you use many Render Targets every time you switch it, the old ZBuffer will be destroyed and a new one created, which is slow.
PREFIX void spReAllocateZBuffer(void)
Reallocates the zBuffer.
PREFIX void spResetZBuffer(void)
Resets the zBuffer with the farest value.
PREFIX void spSetHorizontalOrigin(Sint32 origin)
Sets the horizontal origin of the Surface rectangle and ellipses functions.
PREFIX void spSetVerticalOrigin(Sint32 origin)
Sets the vertical origin of the Surface rectangle and ellipses functions.
PREFIX void spSetFixedOrign(int x,
int y)
Sets a fixed origin like (32,32).
PREFIX Sint32 spGetHorizontalOrigin(void)
Returns the horizontal origin.
PREFIX Sint32 spGetVerticalOrigin(void)
Returns the vertical origin.
PREFIX void spSetZFar(Sint32 zfar)
Sets the value, to which the zbuffer will be reseted.
PREFIX Sint32 spGetZFar(void)
Gets the value, to which the zbuffer will be reseted.
PREFIX void spSetZNear(Sint32 znear)
Sets the value, to which the zbuffer will be reseted.
PREFIX Sint32 spGetZNear(void)
Gets the value, to which the zbuffer will be reseted.
PREFIX int spGetPixelPosition(Sint32 x,
Sint32 y)
Returns where the pixel is in relation to the screen.
PREFIX void spHorizentalLine(Uint16 *pixel,
Sint32 x,
Sint32 y,
Sint32 l_,
Uint32 color_,
Uint32 check,
Sint32 engineWindowX,
Sint32 engineWindowY)
Draws a fast horizental line with one color.
PREFIX int spTriangle(Sint32 x1,
Sint32 y1,
Sint32 z1,
Sint32 x2,
Sint32 y2,
Sint32 z2,
Sint32 x3,
Sint32 y3,
Sint32 z3,
Uint32 color)
Draws a colored Triangle.
PREFIX int spTriangle_tex(Sint32 x1,
Sint32 y1,
Sint32 z1,
Sint32 u1,
Sint32 v1,
Sint32 x2,
Sint32 y2,
Sint32 z2,
Sint32 u2,
Sint32 v2,
Sint32 x3,
Sint32 y3,
Sint32 z3,
Sint32 u3,
Sint32 v3,
Uint32 color)
Draws a colored Triangle with texture mapping.
PREFIX int spPerspectiveTriangle_tex(Sint32 x1,
Sint32 y1,
Sint32 z1,
Sint32 u1,
Sint32 v1,
Sint32 w1,
Sint32 x2,
Sint32 y2,
Sint32 z2,
Sint32 u2,
Sint32 v2,
Sint32 w2,
Sint32 x3,
Sint32 y3,
Sint32 z3,
Sint32 u3,
Sint32 v3,
Sint32 w3,
Uint32 color)
Draws a colored Triangle with perspectively correct texture mapping.
PREFIX int spQuad(Sint32 x1,
Sint32 y1,
Sint32 z1,
Sint32 x2,
Sint32 y2,
Sint32 z2,
Sint32 x3,
Sint32 y3,
Sint32 z3,
Sint32 x4,
Sint32 y4,
Sint32 z4,
Uint32 color)
Draws a colored quad.
PREFIX int spQuad_tex(Sint32 x1,
Sint32 y1,
Sint32 z1,
Sint32 u1,
Sint32 v1,
Sint32 x2,
Sint32 y2,
Sint32 z2,
Sint32 u2,
Sint32 v2,
Sint32 x3,
Sint32 y3,
Sint32 z3,
Sint32 u3,
Sint32 v3,
Sint32 x4,
Sint32 y4,
Sint32 z4,
Sint32 u4,
Sint32 v4,
Uint32 color)
Draws a colored quad with texture mapping.
PREFIX int spPerspectiveQuad_tex(Sint32 x1,
Sint32 y1,
Sint32 z1,
Sint32 u1,
Sint32 v1,
Sint32 w1,
Sint32 x2,
Sint32 y2,
Sint32 z2,
Sint32 u2,
Sint32 v2,
Sint32 w2,
Sint32 x3,
Sint32 y3,
Sint32 z3,
Sint32 u3,
Sint32 v3,
Sint32 w3,
Sint32 x4,
Sint32 y4,
Sint32 z4,
Sint32 u4,
Sint32 v4,
Sint32 w4,
Uint32 color)
Draws a colored quad with perspectively correct texture mapping.
PREFIX void spBlitSurface(Sint32 x,
Sint32 y,
Sint32 z,
SDL_Surface *surface)
Draws a Surface on the target.
PREFIX void spBlitSurfacePart(Sint32 x,
Sint32 y,
Sint32 z,
SDL_Surface *surface,
Sint32 sx,
Sint32 sy,
Sint32 w,
Sint32 h)
Draws a part of a Surface on the target.
PREFIX void spRotozoomSurface(Sint32 x,
Sint32 y,
Sint32 z,
SDL_Surface *surface,
Sint32 zoomX,
Sint32 zoomY,
Sint32 angle)
Draws a surface with rotozoom (Free rotating and zooming of the surface).
PREFIX void spRotozoomSurfacePart(Sint32 x,
Sint32 y,
Sint32 z,
SDL_Surface *surface,
Sint32 sx,
Sint32 sy,
Sint32 w,
Sint32 h,
Sint32 zoomX,
Sint32 zoomY,
Sint32 angle)
Draws a part of a surface with rotozoom (Free rotating and zooming of the surface).
PREFIX void spRectangle(Sint32 x,
Sint32 y,
Sint32 z,
Sint32 w,
Sint32 h,
Uint32 color)
Draws a filled Rectangle.
PREFIX void spRectangleBorder(Sint32 x,
Sint32 y,
Sint32 z,
Sint32 w,
Sint32 h,
Sint32 bx,
Sint32 by,
Uint32 color)
Draws a filled Rectangle border.
PREFIX void spEllipse(Sint32 x,
Sint32 y,
Sint32 z,
Sint32 rx,
Sint32 ry,
Uint32 color)
Draws a filled ellipse.
PREFIX void spEllipseBorder(Sint32 x,
Sint32 y,
Sint32 z,
Sint32 rx,
Sint32 ry,
Sint32 bx,
Sint32 by,
Uint32 color)
Draws a filled ellipse border.
PREFIX void spAddColorToTarget(Uint16 destColor,
Sint32 interpolation)
Adds a colored layer to the target surface.
PREFIX void spInterpolateTargetToColor(Uint16 destColor,
Sint32 interpolation)
Interpolates the target to a color.
PREFIX void spSetPattern32(Uint32 first_32_bit,
Uint32 last_32_bit)
Sets the pattern with two 32 bit ints, each defines 4 lines
PREFIX void spSetPattern64(Uint64 pattern)
Sets the pattern with two 64 bit int, it defines all 8 lines
PREFIX void spSetPattern8(Uint8 line1,
Uint8 line2,
Uint8 line3,
Uint8 line4,
Uint8 line5,
Uint8 line6,
Uint8 line7,
Uint8 line8)
Sets the pattern with eight 8 bit ints line by line
PREFIX void spDeactivatePattern(void)
Deactivates the pattern.
PREFIX void spSetAlphaPattern(int alpha,
int shift)
Sets the pattern in dependence of an alpha value to “emulate” alpha blending.
PREFIX void spSetAlphaPattern4x4(int alpha,
int shift)
Works pretty like spSetAlphaPattern, but it uses 4x4 pattern internal.
PREFIX void spWaitForDrawingThread(void)
If parallel processing of sparrowPrimitive is activated, this function waits until everything is drawn.
PREFIX void spDrawInExtraThread(int value)
Determines, whether an extra thread is used for drawing.
PREFIX void spUpdateTargetPixels(void)
Updates the internal pixels pointer used by sparrow3d.
PREFIX void spFloodFill(int x,
int y,
Uint16 color)
Fills the target at the given position with a color using flood fill.
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.
PREFIX SDL_Surface* spCreateWindow(int width,
int height,
int fullscreen,
int allowresize)
Creates the Window in the plattform depended resolution.
SparrowRenderer is for rendering 3D stuff to the target of sparrowPrimitives.
PREFIX void spSetPerspective(float fovyInDegrees,
float aspectRatio,
float znear,
float zfar)
Sets the projection matrix.
PREFIX void spInitCore(void)
spInitCore initializes SDL, SDL_TTF and other stuff.
PREFIX void spQuitCore(void)
Just quits the Core.
If alphatest is enabled, this (pink) color will not be drawn, it is “transparent”.
left
right
center
sets the base to a fixed position
top
bottom
PREFIX void spFlip(void)
Draws the changes in the window Surface on the screen.
Close