RBGLSpriteSurface
-------------
-------------
The RBGLSpriteSurface class replaces the REALbasic SpriteSurface control.
Unlike the original SpriteSurface, it is a subclass of Canvas, and so
inherits all of its methods.
RBGLSpriteSurface Properties
--------------------------
ClickToStop as Boolean
If this property is set to true, clicking the mouse while the
RBGLSpriteSurface is running will cause it to stop. True by default. Unlike
the original SpriteSurface, you cannot set this value in the IDE, you will
have to set it in code if you wish to change it's value.
FrameSpeed as Integer
This property is slightly misleadingly named - it should really be called
"FramePeriod". It represents the length of a frame in ticks (60ths of a
second). A value of 1 will yield a framespeed of 60fps, a value of 2 gives
30fps, and so on. A value of zero means that the surface will render each
frame as quickly as possible. This value currently defaults to 2, as this
was the common setting for a lot of original SpriteSurface projects. Unlike
the original SpriteSurface, you cannot set this value in the IDE, you will
have to set it in code if you wish to change it's value.
ScrollX as Integer
The horizontal scroll offset of the surface in pixels (read and write
property).
ScrollY as Integer
The vertical scroll offset of the surface in pixels (read and write property).
SurfaceTop as Integer
SurfaceLeft as Integer
SurfaceHeight as Integer
SurfaceWidth as Integer
These properties were originally ued to specify the dimensions of the
SpriteSurface when launched, but in the RBGLSpriteSurface they are completely
ignored and retained only for backwards compatibility. Use the Top, Left,
Width and Height properties of the RBGLSpriteSurface to control its dimensions
instead, just like an ordinary Canvas control.
TileWidth as Integer
TileHeight as Integer
In the original SpriteSurface, the size of background tiles was hard-coded to
64x64 pixels. RBGLSpriteSurface uses this as the default, but with the
TileWidth and TileHeight properties you can set the tile dimensions to
anything you like. If you are not using the tiles, you may ge a slight
performance boost from setting the tile width/height to match the
RBGLSpriteSurface dimensions as it will not have to call the PaintTile
event as often.
Backdrop as Picture
This image will be tiled over the background of your RBGLSpriteSurface. It can
be any size - it has no relationship to the TileWidth and TileHeight
properties. It is drawn before the PaintTile events are called, so will appear
underneath any other drawing that you do in the surface.
SpriteCount as Integer
The number of active sprites attached to the surface. This number does not
include sprites that have been marked for deletion but not yet removed.
RBGLSpriteSurface Methods
-------------------------
Attach (S as RBGLSprite)
Use this method to attach a sprite to the surface. Note that a sprite may be
assoicated only with a single surface at any given time, so if the sprite is
already attached to another surface, it will be removed from that surface
first.
Close
Terminate execution of any current run event. The behaviour is currently
identical to the Stop method.
KeyTest (KeyCode as Integer)
Test if the specified key was pressed during the current frame. This method
is equivalent to calling Keyboard.AsyncKeyDown().
NewSprite (Image as Picture, X as Integer, Y as Integer) as RBGLSprite
Creates a new RBGLSprite with the specified position and image, attaches it to
the RBGLSpriteSurface, then returns it. It is probably better to create your
own RBGLSprite subclasses for new projects and instantiate them yourself
using the new operator, but this method is retained for backwards
compatibility.
PaintTile (X as Integer, Y As Integer)
In the original SpriteSurface this would force the specified tile to be
redrawn in the next frame. Currently the RBGLSpriteSurface redraws every
visible tile each frame anyway, so this method does nothing. It is retained
for backwards compatibility, and may be used for something in a future
release.
Remove (S as RBGLSprite)
Detaches the specified sprite from the surface.
Run ([Async as Boolean], [Priority As Integer])
Runs the RBGLSpriteSurface event loop, causing the surface to be repeatedly
redrawn and the collision and update events to be called for each frame. By
default the Run method executes syncronously, which means that execution halts
until the Stop or Close methods are called, or the user interrupts the
execution some other way, such as by clicking. The RBGLSpriteSurface run
method features an enhancement over the original however: The optional Async
argument allows you to run the surface asyncronously using a thread. On
Windows a timer is used by default instead of a thread because the program
will crash on quit if the thread is still running. The timer performance is
slightly worse than the thread, so you can override this with
a constant if you need the higher performance and are prepared to work around
the crashing issue. If the async property is set to true then the Run method
will return immediately instead of blocking until the loop terminates. The
optional Priority parameter can be used to control the thread priority (see
the Thread documentation in the language reference for more detail). The
Priority parameter is ignored when using a timer.
Scroll (dx as Integer, dy as Integer)
Scrolls the surface by a given horizontal and vertical amount. This is
equivalent to setting the ScrollX and ScrollY properties manually, but note
that dx and dy are relative to the current scroll offsets, not absolute.
Stop ()
Stops the execution of the Run loop. Currently this is the same as calling
Close ().
Update ()
Forces the NextFrame, Collision and PainTile events to be called a single
time, prior to redrawing all the sprites. This method can be used to implement
your own event loop instead of using the Run () method.
Clear ()
Removes all sprites from the surface.
RBGLSpriteSurface Events
------------------------
Open ()
Called when the RGLSpriteSurface is first created. This is a good opportunity
to set properties such as FrameSpeed and disable ClickToStop.
Collision (S1 as RBGLSprite, S2 as RBGLSprite)
This is called every time two sprites with suitable group values are
deemed to have collided. You may delete or add sprites to the surface during
the execution of this method - restrictions in the previous versions of this
library have been eliminated. Note that collision logic may be better placed
in the Collision event of the RBGLSprite itself (new to vesion 1.1).
NextFrame (dt as Double)
This is called before all collision tests are performed and the view is
redrawn. Game logic such as reading user input, or calculating AI decisions or
physics should be performed in this event. The dt parameter is the number of
seconds since the previous frame (usually < 1). You can easily use this to
value to calculate the frame rate, or update time-based animations.
PaintTile (g as RBGLGraphics, xpos as Integer, ypos as Integer)
This method is called after NextFrame and before the spries are drawn. It is
called once for every tile that is visible in the RBGLSpace control. The g
parameter is an RBGLGraphics class which can be used for doing arbitrary
drawing using OpenGL. The Graphics object is clipped to the bounds of the
tile being rendered.
PaintOverlay (g as RBGLGraphics)
This method is called after the background, tiles and sprites have all been
drawn. It allows you to draw content on top of the surface - this can be
useful for drawing HUD elements, or special effects such as lightning or
laser beams that are hard to achieve with sprites.
RBGLSprite
------------
------------
The RBGLSprite replaces the old REALbasic Sprite class. It has similar
functionality, but adds a few new features made possible by the use of OpenGL.
RBGLSprite Properties
------------------------
Group As Integer
This property is used to control collision detection between sprites. If the
group value of a sprite is set to zero, it will not collide with any other
sprite. If it is set to a negative value then the sprite can collide with any
other sprite that has a non-zero group value. If it is set to a positive value
then the sprite can collide with any other sprite that does not have the same
grop value, or a value of zero.
Image As Picture
This is the image that will be drawn for the sprite. It is an ordinary
Picture, but will be converted to an OpenGL texture when the sprite is
rendered. In the original SpriteSurface, if this picture contained an 8-bit
mask, it would be ignored, and the 1-bit, white-as-transparent property would
always be treated as true, irrespective of the Transparent property of the
Picture. Whilst this would have been easy to emulate, it is not very useful
behaviour, so in the RBGLSprite, an 8-bit mask image property can be used. By
default the Transparent property of the image is set to true automatically
when it is assigned to a Sprite for compatibility with old projects, but you
can override this behaviour with the RespectImageTransparency property. If
an 8-bit mask is specified for the image, the Transparent property will be
ignored and the collision detection will be based on the 50% opacity threshold
in the mask.
CollisionMask As Picture
Sometimes the collidable area of your sprite does not match the visible area.
For example you may have a sprite with a large translucent area that should
still be collidable, or maybe your sprite is a mouse cursor, where only the
tip is active. In these cases you can use the CollisionMask property to
specify an separate image to use for collision. If the CollisionMask property
is set it will be used for collisions in prefence over the Image property.
Priority As Integer
Controls the order in which sprites are drawn. By default, sprites are drawn
in the order in which they were added to the RBGLSpriteSurface. Sprites with
a higher priority will always be drawn in front of those with a lower
priority however, irrespective of the order they are added. Priority can be
changed at any time, but frequent chnages to sorting order can impact
performance if there are a lot of sprites.
Opacity As Single
New to RBGLSprite, the opacity property lets you make your sprite translucent.
The default value is 1.0 (opaque), but can range from 1 to zero (fully
transparent) and can be adjusted on the fly without changing the image.
Tint As Color
Another new property for RBGLSprite, the Tint property lets you specify a
colour whih will be belended with the sprite image as it is drawn. You could
use this property to make a spaceship flash red when it is hit for example.
The default value is white, which is equivalent to drawing the sprite with
no colour blending at all.
Orientation As Double
This property can be used to rotate sprites to an arbitrary angle. The
value is measured in radians and rotation is relative to the centre of the
current sprite image. Note: collision detection is pixel-perfect for rotated
sprites, but detecting collisions between rotated sprites is slower than for
sprites with Orientation equal to zero.
Centered As Boolean
False by default, this handy new property determines if a sprite's X and Y
coordinates are relatie to it's top-left-hand corner or its centre. By
default they relate to the corner for backwards compatibility, but it is
often easier to work with sprites that are centered, especially if rotation
is involved.
Surface As RBGLSpriteSurface
This is the RBGLSpriteSurface that the sprite is attached to. WHen a sprite
is first created this will be nil unless the sprite was created using the
RBGLSpriteSurface.NewSprite function. WHen you set this property to a given
RBGLSpriteSurface, the sprite will be attached to that surface. If you set it
to nil then the sprite will be detached.
X As Single
Y As Single
The coodinates of the sprite relative to the RBGLSurface's origin. These
values will differ from the onscreen coordinates of the sprie if the surface
has been scrolled. Unlike the original Sprite, these values are specified as
floating poin rather than integer for better precision when positioning
sprites.
ScreenX As Single
ScreenY As Single
The actual position of the sprite in the view (takes the current scroll
values of the RBGLSurace into account). The name ScreenX is misleading
because the coordinates will only be relative to the screen if the
RBGLSprieSurface fills the whole screen. These coordinates are actually
relative to the top-left corner of the RBGLSUrface control.
RespectImageTransparency As Boolean
This property is shared between all RBGLSprites. If set to false, all sprite
images will treat white pixels as transparent, otherwise they will respect
the Transparent property of the specified Picture. This is set to false by
default to mimic the behaviour of the built-in SpriteSurface.
DebugCollisions As Boolean
If set to true, bounding circles and collision masks will be drawn in white
in front of all the sprites as they are calculated. Note that this is a shared
method so it applies to all sprites.
RBGLSprite Methods
---------------------
Close ()
Removes the sprite from its parent RBGLSpriteSurface.
CanCollideWith (S As RBGLSprite) As Boolean
This method compares the Group properties of the two sprites to determine if
they can collide with one another. If this method returns false, sprite
collisions between the two sprites will not be tested for automatically, and
the Collision event will not fire. You can still test if the sprites are
colliding manually however by using the CollidingWith() method.
CollidingWith (S As RBGLSprite) As Boolean
This method tests to see if the specified sprite is colliding with this one.
Collision detection is pixel-perfect and the collision mask is derived from
the image property. If the image has a full eight-bit alpha mask, a threshold
of 50% opacity is used for the collision mask (this is not affected by the
Opacity property of the sprite itself). The Group property is ignored for this
test.
Update ()
Triggers the NextFrame event. Usually called by the RBGLSprteSurface.
Draw (g as RBGLGraphics)
This method draws the sprite with the specified opacity and blend colour into
the passed RBGLGrpahics context. YOu can use this to draw a sprite directly
inside an RBGLCanvas if you like, or to paste it into one of the background
tiles.
RBGLSprite Events
------------------------
Collision (S as RBGLSprite)
This is called every time the sprite collides with another. You may delete or
add sprites (including the event owner) to the surface during the execution of
this event.
NextFrame (dt as Double)
This is called before all collision tests are performed and the sprite
is drawn, but afte the RBGLSpriteSurface NextFrame event. The dt parameter is
the number of seconds since the sprite was last updated (usually < 1). You
can easily use this to value to calculate the frame rate, or update time-based
animations.
Paint (g as RBGLGraphics)
This event is called after the sprite image is drawn and allows you to draw
text or special effects on top of the sprite. Drawing is positioned and
oriented relative to the center of the sprite, but it is not clipped to the
sprite area, so you could use it to draw, for example, a lightning bolt
between two sprites - something that would be hard to do using ordinary sprite
images. Note that you can also leave the Image property of the sprite as Nil
and draw the sprite manually within the Paint event if you wish.