About the REALbasic RBGLSprites library

RBGLSprites is a 2D sprite and tile-based game engine for REALbasic that uses OpenGL for hardware-accelerated blending and scaling effects. RBGLSprites is built on top of the cross-platform RBGL library and does not rely on any plugins, either internal or external.

RBGLSprites replicates the deprecated REALbasic SpriteSurface API function-for-function, making it easy to port existing projects of any level of complexity.

Donations

If you find RBGL useful, please support us by making a small donation. Your funding will help to ensure continued development of these tools.

Acknowledgements

Thanks go to Joe Strout, Matt Neuburg, Robert Martines and Roger Clary for allowing their SpriteSurface projects to be used to test RBGL Sprites, and to David Birns for some useful feedback and troubleshooting.

RBGLSprites was written from scratch using the OpenGL specification, it is not derived from any existing REALbasic OpenGL libraries (apart from RBGL of course) or examples.

FAQ

What is this for?
The RBGLSprites library is a replacement for the deprecated REALbasic SpriteSurface control. In addition to replicating the SpriteSurface APIs, RBGLSprites adds a number of new features such as translucency, rotation and scaling.
What's REALbasic, and where can I get hold of it?
REALbasic is a visual programming environment for writing desktop applications for Mac OS, Windows and linux. Unlike RBGL it is not free, however you can download a free time-limited trial version from www.realbasic.com.
What versions of REALbasic does RBGLSprites support?
RBGLSpprites is tested with REALbasic 2007r5 and 2008r5. It is assumed to work on all versions in between, but these are not always tested individually.
What platforms does RBGLSprites support?
RBGLSprites works on Windows and Mac OS X (PPC and Intel). A linux port is planned, but will not be ready for some time.
How does RBGLSprites work?
RBGLSprites is built on top of RBGL, which uses declares to link to the OpenGL library found on all modern Macintosh and Windows machines. The OpenGL library provides hardware-accelerated 3D and 2D graphics capabilities, a subset of which is exposed bythe RBGL API.
What is the point of RBGLSprites? Why not just use OpenGL declares directly?
The RBGLSprites API operates at a much higher level than OpenGL. Rather than dealing with polygons and vertices, RBGLSprites creates an object-oriented 2D scene graph and handles sorting, orienting, animating and collisions between sprites automatically.
If RBGLSprites just replicates the SpriteSurface, why not just use that instead?
Two reasons: 1) The REALbasic SpriteSurface has been deprecated which means that it is no longer being updated, and will eventually be dropped from REALbasic. 2) RBGLSprites does way more than just replicate the SpriteSurface API, it adds translucency, rotation, scaling and loads more that could not be achieved with the original SpriteSurface.
Why replicate the SpriteSurface API instead of designing a clean new interface?
The SpriteSurface has existed for many years and people are familiar with it - there are many projects out there that use it and that could benefit from being updated to use RBGLSprites. Clean and easy-to-use APIs are not simple to design - by replicating the SpriteSurface API we have ensured that RBGLSprites supports a proven and familiar way of working for REALbasic developers.
Has supporting the SpriteSurface API limited RBGLSprites' feature set or performance?
Not at all - RBGLSprites uses a number of clever caching techniques to silently map familiar REALbasic objects such as Picture and Graphics to their OpenGL counterparts. This system is fast and efficient - no compromises have been made in RBGLSprites' performance, and it performs extremely well on modern hardware.
Why is RBGLSprites better than other libraries such as SuperSpriteSurface?
Depending on your needs, it may not be. However the goals of RBGLSprites are significantly different from those of SuperSpriteSurface - for one thing, RBGLSprites mimics the SpriteSurface API, and uses familiar objects such as Picture for drawing, making it easy to port existing code. For another, RBGLSprites does not rely on any external plugins and can produce single-file executables on Windows.
Does RBGLSprites require any plugins?
No, RBGLSprites uses only pure REALbasic code. We have also been careful to avoid using any of REALbasic's own internal plugins, so RBGLSprites projects can still compile to a single .exe file on Windows.
Is RBGLSprites free?
Yes, free and completely open source. You may use it without restriction in both free and commercial projects, and may redistribute the source as long as you do not misrepresent its origins. If you do find RBGLSprites useful however, we would appreciate a small donation, which you can make using the PayPal link at the top and bottom of this page.

Release Notes

1.2.1
  • [fix] Fixed a longstanding bug in the Sprite collision code that would cause part of the collision region not to register if the mask contained multiple independent collidable regions.
  • [opt] Improved collision efficiency for long, thin sprites by comparing bounding rectangles instead of bounding circles in some cases (prior to resorting to per-pixel collision testing).
1.2
  • [opt] Significantly improved collision detection performance for large numbers of sprites by using a radix sorting algorithm to sort by group.
  • [new] Added Paint event to RBGLSprite class which can be used to draw arbitrary content into the surface on top of the sprite, such as special effects or text.
  • [new] Added CollisionMask property to RBGLSprite class, which allows you to specify a separate image to use for collision detection which may differ from its visible shape.
  • [new] When running in Async mode the RBGLSpriteSurface now uses a thread instead of a timer for increased performance on Mac OS. You can specify the priority at which the thread will run as an additional optional parameter for the RBGLSpriteSurface.Run method. On Windows a timer is still used by default because the app crashes on quit if a thread is running.
  • [fix] When RBGLSprite.DebugCollisions is enabled, collision wireframes are now drawn in the correct place when the surface is scrolled.
  • [new] Added CanCollideWith method to RBGLSprite class.
  • [opt] Improved performance slightly by not drawing sprites that are off-screen.
  • [fix] SpriteSurface will no longer halt unexpectedly when another application if user quits another application whilst it is running.
  • [chg] App.DoEvents is no longer used when running the RBGLSurface in synchronous mode as it caused crashes on quit in Windows. This means ths the interface will freeze up, but this is consistent with the REALbasic SpriteSurface behaviour.
  • [fix] Fixed a bug in the private_sprite_collider class that could lead to incorrect bounding radii being calculated for sprites.
  • [chg] Upgraded RBGL library to version 1.6.2, which fixes a number of image rendering issues.
1.1.1
  • [fix] Fixed an issue that caused the second sprite added to the surface to be incorrectly sorted according to its priority.
  • [opt] Removed key detection caching as it was slowing down overall performance and is no longer needed.
  • [opt] Made some optimisations to the sprite collision detection routines.
  • [fix] Fixed an issue with the screenshot function in the Asteroids demo that caused multiple save dialogues to appear on Windows.
1.1
  • [new] RBGLSprites now have an Orientation property that can be used to rotate them to an arbitrary angle.
  • [new] RBGLSprites now have pixel-perfect collision detection, even when rotated.
  • [new] If StretchBackdrop property is set on RBGLSpriteSurface the backdrop image will stretch to fill the SpriteSurface and will not scroll.
  • [new] Added NextFrame and Collision events to the RBGLSprite class. The events are called automatically by the RBGLSpriteSurface prior to its own equivalents. You can use these events to manage your sprites in a more object-oriented way.
  • [new] Added dt parameter to NextFrame event. This represents the number of seconds since the last frame was drawn (hopefully < 1) and can be used for more accurate animation than relying on the FrameSpeed setting.
  • [fix] If the sprite priority is changed after attaching it to the RBGLSpriteSurface, the drawing order is now updated accordingly.
  • [opt] Replaced linear priority sorting algorithm with a faster binary insertion sort.
  • [fix] Fixed a bug in priority sorting algorithm that meant it didn't actually work.
  • [new] Added Centered property to RBGLSprite, false by default. If set, the sprite image with be centered on its coordinates instead of the coordinates representing the top left corner.
  • [new] Added PaintOverlay event to RBGLSpriteSurface. This event is ideal for drawing head up displays or special effects on top of your sprites.
  • [new] Added Clear method to RBGLSpriteSurface which removes all sprites.
  • [new] Added SpriteCount property to RBGLSpriteSurface.
  • [fix] Fixed a memory leak that occured when removing multiple sprites from the surface during a frame update.
  • [new] You can now take a screenshot of all or part of the RBGLSpriteSurface using the GetPicture function inherited from RBGLCanvas.
  • [chg] Updated RBGL library to version 1.5.
1.0.1
  • [new] Updated RBGL to version 1.4 which includes a number of bug fixes (see the RBGL release notes for details).
  • [fix] Fixed a bug in RBGLSpriteSurface.Attach (thanks go to David Birns for spotting it).
1.0
  • [new] Initial release.

Donations

If you find RBGL useful, please support us by making a small donation. Your funding will help to ensure continued development of these tools.