RBGLContext
-------------
-------------
The RBGLContext class is the core of RBGL. It can be used to create an OpenGL
drawing context from either a Window or Canvas.
RBGLContext Properties
--------------------
Window
The parent window of the context
Left as Integer
The leftmost edge of the context (relative to the parent window) in pixels
Top as Integer
The topmost edge of the context (relative to the parent window) in pixels
Width as Integer
The current width of the context in pixels
Height as Integer
RBGLContext Methods
-------------------
Constructor (Window as Window, [options as RBGLContextOptions])
Creates a new RBGLContext and attaches it to the window. The initial size of
the context will match the window, but if the window is resized you will need
to call the UpdateDimensions method of the context to update its size. The
optional options parameter allows you to control buffer sizes and enable
oversampling (Mac OS only).
Constructor (Canvas as Window, [options as RBGLContextOptions])
Creates a new RBGLContext and attaches it to the canvas. The initial size of
the context will match the canvas, but if the canvas is resized you will need
to call the UpdateDimensions method of the context to update its size.
Alternatively use the provided RBGLCanvas class which updates automatically.
The optional options parameter allows you to control buffer sizes and enable
oversampling (Mac OS only).
Constructor (Width as Integer, Height as Integer, [options as RBGLContextOptions])
Creates a new ofscreen RBGLContext of the specified dimensions. This context
can be drawn to using its Graphics property and the resultant image can be
extracted with the GetPicture() or GetRBGLPicture methods. Currently
offscreen contexts only work on Mac OS.
Bind ()
If you have multiple contexts in an application, call the Bind method to
switch to a particular context before attempting to draw to it or call any
other methods on it. OpenGL is a state machine which means that drawing
commands and other operations affect the last selected context.
UnBind ()
Deselect a context. You typically won't need to use this except for debugging
purposes to guarantee that a particular context is not being written to.
UpdateDimensions ()
This method updates the clipping region and viewport of the context to match
the parent Window or Canvas. Call this whenever the Window or Canvas is
resized.
SetMatrixAuthographic ([Left as Double], [Top as Double], [Right as Double],
[Bottom as Double], [NearClip as Double], [FarClip as Double])
Set the camera to an authographic (no perspective) view. The parameters allow
you to specify the mapping between the viewport and the coordinates of the
world. All parameters are optional - if omitted the view will default to a
range from -1 to 1 on both the x and y axis, with 0,0 in the centre.
SetMatrixPerspective ([FovY as Double], [AspectRatio as Double], [NearClip as
Double], [FarClip as Double])
Set the camera to a perspective view. The parameters allow you to specify the
view frustum. All parameters are optional - if omitted the view will default
such that anything rendered on the z = 0 plane will appear the same as for the
default authographic view.
Clear ([mask as UInt32])
Clear the context to the currently specified background colour. By default,
the background colour is set to whatever the background colour of the parent
window is. You can change it using the glClearColor function (access this with
an OpenGL declare). The optional mask parameter allows you to specify which
buffers are cleared (by default only the color and depth buffers are affected)
Flush ()
This method flushes the context buffers (or swaps the back and front buffers
on Windows) causing the results of any previous drawing commands to appear on
the screen. This method should normally be called at the end of any drawing
you do. It is called automatically by the RBGLCanvas after a Paint event
however.
Handle () as UInt32
Returns a pointer to the internal OpenGL context object. You may need to pass
this as a parameter to certain OpenGL functions.
DefaultOptions () as RBGLContextOptions
Get the default context options used by RBGL.
IsExtensionSupported (ExtensionName as String) as Boolean
Determine if an OpenGL extension is supported.
Enable (feature as RBGLFeature, [enable as Boolean])
Used to enable or disable an OpenGL feature such as depth testing. If the
optional enable argument is set to false then the feature will be disabled,
otherwise it will be enabled.
GetRBGLPicture ([X as Integer], [Y as Integer], [Width as Integer], [Height as
Integer]) as RBGLPicture
Used to copy all or part of the RBGLContext surface into an RBGLPicture
object, which can then be used for drawing or saving to a file. Note that
the performance of this method is quite slow unless the rectangle being copied
has dimensions that are a power of two.
RBGLGraphics
------------
------------
The RBGLGraphics object is a drop-in re-implementation of the REALbasic Graphics
class, offering the exact same functionality, but using OpenGL for rendering. The
properties and functions are mostly the same as for the ordinary Graphics class,
so only the differences are documented here.
RBGLGraphics Properties
------------------------
Context As RBGLContext (Readonly)
This property contains the underlying RBGLContext object behind the graphics.
ForeColor As RBGLColor
You are still free to set the drawing colour using the standard REALbasic
Color values and &cRRGGBB syntax, however OpenGL supports 32 bit colours with
alpha opacity, so to allow access to this, the RBGLGraphics ForeColor method
now accepts a 32bit RGBLColor instead. You can set this value using the RGBA()
global method (documented below), or you can use an eight-character hex value
like this: graphics.Forecolor = &hRRGGBBAA
CacheSize as Integer
RBGL automatically caches all images and strings that are drawn using the
RBGLGraphics methods. This yields a huge performance boost because converting
REALbasic Pictures and strings to OpenGL textures is very slow, but it can
consume a lot of memory. By default the CacheSize is set to -1 which means
that the size is unlimited and everything will be cached. If you set it to a
positive integer value then images and strings will be cached automatically
until the cache is full. You can increase or reduce the size of the cache at
any time. Note that if you reduce the cache size, the entire cache is
cleared. RBGLPicture objects are not cached as there is no performance impact
when drawing these. When possible it is recommended that you create and use
RBGLPictures yourself instead of using REALbasic Pictures and relying on the
cache.
CacheStrings as Boolean
Use this property to toggle String caching on and off. Useful if you are
intending to draw some highly dynamic text such as user-generated input or
a frame count, where cachine might lead to excessive memory consumption and
yield little performance benefit. True by default.
CachePictures as Boolean
Use this property to toggle image caching on and off. Useful when drawing
Picture objects that will only be used once, or which you intend to modify on
the fly. True by default.
RBGLGraphics Methods
---------------------
Constructor (Context As RBGLContext)
Create a new RBGLGraphics object and attach it to the given RBGLContext.
Constructor (Context As RBGLContext, X As Single, Y As Single, Width As Single,
Height As Single)
Create a new RBGLGraphics object and clip it to the specified rectangle
within the given RBGLContext. Coordinates will be relative to the top
corner of this rectangle, and any drawing will be clipped to this region.
Bind ()
OpenGL is a state machine, which means that instead of calling methods on
objects, you set a data object to work on, and all subsequent calls refer to
that object until you specify otherwise. This doesn't play veyr nicely with
REALbasic's drawing syntax, which allows you to alternate drawing calls
between graphics objects. Rather than set the context each time you draw
something, the RBGLGraphics object assumes that it is the currently selected
drawing context whenever you try to draw into it. If you do need to switch
between contexts, use the Bind() method on each RBGLGraphics before drawing.
DrawPicture (Image As RBGLPicture, X As Single, Y As Single, [DestWidth As Single],
[DestHeight As Single], [SourceX As Single], [SourceY As Single], [SourceWidth As
Single], [SourceHeight As Single], [Orientation As Double], [Blend As Boolean])
This works the same way as the ordinary DrawPicture function, but takes an
RBGLPicture as a parameter instead of a Picture. Whenever you draw a
picture in OpenGL it must be converted to a texture and copied into video
memory, so if you are drawing the same picture several times it is much more
efficient to re-use the same texture object, rather than force the
RBGLGraphics to re-create it each time. The optional Blend parameter (false
by default) will blend the image with the current ForeColor, which allows you
to control the tint and opacity. The new, optional Orientation parameter
allows you to specify an angle, in radians, to which the picture should be
rotated when it is drawn. The picture is rotated about its centre point,
within the specified rectangle.
TilePicture (Image As Picture, X As Single, Y As Single, Width As Single, Height
As Single, OffsetX As Single = 0, OffsetY As Single = 0, Blend As Boolean = False)
This method is used to tile a picture over a rectangle. Unlike the normal
DrawPicture method, this tiles (repeats) the image instead of stretching it.
The OffsetX and OffsetY parameters control the offset of the top left of the
image within the rectangle.
TilePicture (Image As RBGLPicture, X As Single, Y As Single, Width As Single,
Height As Single, OffsetX As Single = 0, OffsetY As Single = 0, Blend As
Boolean = False)
This method is identical to the other TilePicture method above, except that it
takes an RBGLPicture (an OpenGL texture) instead of a REALbasic Picture
object.
DrawPolygon (Points() As Integer/Single/Double, [ZeroBased As Boolean])
FillPolygon (Points() As Integer/Single/Double [ZeroBased As Boolean])
These are the same as the ordinary Graphics.DrawPolygon methods, with two
exceptions: 1) The Points array can be an array of Singles instead of
Integers, which is often easier when working with 3D graphics, and 2) the
optional ZeroBased parameter lets you start your array at index zero instead
of the silly and inconsistent one-based requirement of the built-in method.
RGBAPixel (X As Integer, Y As Integer) As RBGLColor
Works the same as the normal Graphics.Pixel() method, but returns an
RBGLColor instead of a Color.
Pixel (X As Integer, Y As Integer, Assigns Col As RBGLColor)
Works the same as the normal Graphics.Pixel() method, but allows you to
specify a four-component RGBA colour.
GetRBGLPicture ([X as Integer], [Y as Integer], [Width as Integer], [Height as
Integer]) as RBGLPicture
Used to copy all or part of the RBGLGraphics surface into an RBGLPicture
object, which can then be used for drawing or saving to a file. Note that
the performance of this method is quite slow unless the rectangle being copied
has dimensions that are a power of two.
GetPicture ([X as Integer], [Y as Integer], [Width as Integer], [Height as
Integer]) as Picture
Used to copy all or part of the RBGLGraphics surface into a REALbasic Picture
object, which can then be used for drawing or saving to a file. Note that
the performance of this method is quite slow unless the rectangle being copied
has dimensions that are a power of two. If you are planning to draw the
resultant Picture back into an RBGLGraphics context then use GetRBGLPicture
instead as this will perform much better.
Flush ()
OpenGL drawing operations do not happen immediately but are often queued
until the next screen refresh. If you need to force the update to happen
immediately you can call the Flush() method. This is called automatically
at the end of the RBGLCanvas Pain event.
Handle () as UInt32
Returns a pointer to the internal OpenGL context object. You may need to pass
this as a parameter to certain OpenGL functions.
Cache (Image As Picture)
Converts the specified image to a texture and stores it in the RBGL texture
cache without drawing it. All subsequent times that the Picture is drawn in
an RBGLGraphics context the cached version will be used. Pictures drawn with
the DrawPicture function will always be cached the first time they are drawn
anyway, so you only need to use this method for precaching Pictures prior to
drawing. Creating a texture takes time, so it is worth precaching images if
you can. Cached images are shared between contexts. The Cache method ignores
the CacheSize parameter and will add the image to the cache even if the cache
is already "full".
UnCache (Image As Picture)
Removes an image from the cache. Use this if you have modifed an image using
its Graphics property, or if you no longer need it. Images drawn with RBGL
are always cached, so don't just discard an image after drawing it without
UnCaching it or you will create a memory leak. If you don't want any images
to be cached, you can disable caching using the CacheSize property.
ClearCache ()
Clear the image and string caching for all RBGLContexts. You may wish to do
this periodically to avoid memory leaks, although this may have a significant
performance impact, so you are better off using the Cache and UnCache methods
to control the cache more finely.
GraphicsWrapper
---------------
---------------
This is a simple wrapper class around a standard REALbasic Graphics object. It
implements the AbstractGraphics interface, so can be used for writing dual-mode
drawing functions that can accept either an RBGLGraphics or an ordinary Graphics
as input.
GraphicsWrapper Methods
---------------------
Constructor (g As Graphics)
Create a new GraphicsWrapper from an existing Graphics Object. The
GraphicsWrapper retains a reference to the Graphics object, but if the
Picture or Window that provided the Graphics is destroyed then the
Graphics object will become invalid, and the GraphicsWrapper will no
longer work correctly.
RBGLCanvas
-----------
-----------
The RBGLCanvas class provides an easy-to-use implementation of the RBGLContext
that can be dragged directly into a Window and used right away.
RBGLCanvas Properties
---------------------
EraseBackgroundGL As Boolean
Specifies whether the background should be erased each time the Canvas is
painted. The initial value is set to whatever the EraseBackground property was
specified to be in the IDE (true by default). The EraseBackground property is
subsequently set to false, and should not be changed as it will cause the
Canvas to flicker on Windows. If you wish to preserve the Canvas content
between refreshes, use the EraseBackgroundGL property instead.
StretchBackdrop As Boolean
If set to True, the backdrop image (if specified) will be stretched to fill
the entire canvas instead of being clamped to the top-left-hand corner. False
by default.
RBGLCanvas Events
-------------------
Paint (g As RBGLGraphics)
The overloaded Paint event is called whenever the Refresh method is used, or
when some other event causes the canvas to be refreshed, e.g. resizing the
window. The event receives a reference to an RBGLGraphics object as a
parameter. Note that all binding, resizing, clearing and flushing is handled
automatically behind the scenes, so only drawing commands need to be included
in the paint event.
RBGLCanvas Methods
-------------------
Refresh ([EraseBackground As Boolean])
The overloaded Refresh method redraws the OpenGL context. The EraseBackground
parameter specfies whether or not to call the Clear method of the attached
RBGLContext automatically prior to painting, and defaults to true.
GetRBGLPicture ([X as Integer], [Y as Integer], [Width as Integer], [Height as
Integer]) as RBGLPicture
Used to copy all or part of the RBGLCanvas surface into an RBGLPicture
object, which can then be used for drawing or saving to a file. Note that
the performance of this method is quite slow unless the rectangle being copied
has dimensions that are a power of two.
GetPicture ([X as Integer], [Y as Integer], [Width as Integer], [Height as
Integer]) as Picture
Used to copy all or part of the RBGLCanvas surface into a REALbasic Picture
object, which can then be used for drawing or saving to a file. Note that
the performance of this method is quite slow unless the rectangle being copied
has dimensions that are a power of two.
RBGLPicture
--------------
--------------
The RBGLPicture class is used for creating images in a format that can be used
directly by OpenGL.
RBGLPicture Properties
-------------------------
Width As UInt32 (Read only)
Height As UInt32 (Read only)
The width and height of the picture used to create the texture. The actual
texture's width and height are converted to the nearest power of two, but
all OpenGL texture coordinates are in the range 0 to 1, so this doesn't make
any difference to usage.
ActualWidth As UInt32 (Read only)
ActualHeight As UInt32 (Read only)
The actual width and height of the texture, which is always a power of two.
All canvas drawing operations treat the width and height as that of the original
image, so you usually won't need to use these properties.
WrapX As RBGLWrapMode
WrapY As RBGLWrapMode
The wrapping horizontal and vertical wrapping method used for the texture
when coordinates are specified outside of the 0 to 1 range. Choices are
RBGLWrapMode.Repeat for tiling, or RBGLWrapMode.Clamp to stop at the edges
of the image. For images that do not need to tile, Clamp will prevent the
colours at the edges from "bleeding" into to one another.
Upscaling As RBGLScalingMode
Downscaling As RBGLScalingMode
Controls how scaling should be handled when textures are resized. Use
RBGLScalingMode.Linear for smooth scaling and RBGLScalingMode.Nearest
for blocky, pixelated scaling. Note that in some cases the latter
will actually look a lot sharper and cleaner.
DefaultOptions () as RBGLPictureOptions
Get the default texture options used by RBGLPicture.
RBGLPicture Methods
----------------------
Constructor (Image As Picture, [Format As RBGLPixelFormat], [Options As
RBGLPictureOptions])
Creates a new texture object using a REALbasic Picture as the source. The
method automatically handles resizing of the image if its dimensions are not
a power of two as required by OpenGL. The optional parameter Format allows
you to specify the format of the texture - values can include RBG, RGBA or
Alpha/Luminosity. If omitted the format is set to RGB or RGBA depending on
whether the source picture contains a mask. Use the optional Options property
to change the default texture settings such as wrap and scaling modes, and to
enable or disable mip-mapping.
Constructor (Context as RBGLContext, X As Integer, Y As Integer, Width As
Integer, Height As Integer, Options As RBGLPictureOptions])
Creates a new texture object using the contents of the supplied RBGLContext.
The texture contains a snapshot of the context contents a the time of
creation, and does not automatically update when then context is redrawn. The
X, Y, Width and Height parameters allow you to specify the sub-rectangle of
the context that you wish to copy.
Bind ()
Binds the texture to the current OpenGL context. Each texture must be
separately bound to each context. The first time a texture is bound to a
context, the data must be copied into video memory, which may take a little
while for large textures, so for performance reasons you may wish to pre-bind
textures before before use.
Draw (X As Single, Y As Single, [DestWidth As Single], [DestHeight As Single],
[SourceX As Single], [SourceY As Single], [SourceWidth As Single], [SourceHeight
As Single], [Orientation As Double])
This is a handy utility function to draw the texture image, or a subrectangle
of it into the current context. The parameters are identical to the
RBGLGraphics DrawPicture method, but unlike that method, the image is blended
with the current forecolor. If you wish the image to be shown unblended then
you will need to set the forecolor to white beforehand. The new, optional
Orientation parameter allows you to specify an angle, in radians, to which the
picture should be rotated when it is drawn. The picture is rotated about its
centre point, within the specified rectangle.
Blit (X As Integer, Y As Integer, [DestWidth As Single], [DestHeight As Single])
Copy the texture image directly to the viewport without colour blending. See
optimisation tips below for usage caveats.
Tile (X As Single, Y As Single, Width As Single, Height As Single, OffsetX As
Single = 0, OffsetY As Single = 0)
Tile the Picture over a rectangular area. See the RBGLGraphics.TilePicture
function description for more details.
GetPicture () As Picture
Converts the RBGLPicture data back to a Picture for saving ina file or
drawing into a native Graphics object. This method may be quite slow for
large pictures, although the Picture object is cached after the first call so
subsequent calls will be faster for a given RBGLPicture.
RBGLStringTexture
------------------
------------------
The RBGLStringTexture class is used for drawing text with OpenGL. OpenGL doesn't
have any native text drawing capability. RBGLStringTexture objects draw text
using the standard REALbasic text drawing methods, then cache the result in a
texture for drawing in an OpenGL context.
RBGLStringTexture Properties
----------------------------
Text As String
The text that will be displayed.
FontName As String
The name of the font to use.
FontSize As Integer
The font size. This really determines the resolution rather than the size as
the texture can be drawn at any size.
WrapWidth As Integer
Used to set the width at which the text will wrap onto a new line.
Ascent As Integer (Read only)
Descent As Integer (Read only)
Width As Double (Read only)
Height As Integer (Read only)
LineHeight As Integer (Read only)
The dimensions and metrics of the text, useful for positioning the resultant
image when drawing.
TextDirection As Integer (Read only)
The text direction of the specified text.
Bold As Boolean
Italic As Boolean
Underline As Boolean
Italic As Boolean
Condense As Boolean
The parameters control the font appearance.
Texture As RBGLPicture (Read only)
The generated texture containing the text image. The RBGLStringTexture class
uses lazy evaluation, so the texture is only generated when the Texture
property is accessed, and is then cached until any of the properties are
changed.
RBGLStringTexture Methods
----------------------------
Constructor (Text As String)
Create a new string texture with default font size, colour, etc.
Draw (X As Single, Y As Single)
Draw the string at the specified coordinates.
Blit (X As Integer, Y As Integer)
Copy the string image directly to the viewport without colour blending. See
optimisation tips below for usage caveats.
RBGLException
---------------
---------------
The RBGLException class is used to report critical errors in the RBGL system.
Only serious errors will result in an exception being thrown - OpenGL has its
own error reporting system, and you will need to hook into this using declares
if you wish to track general OpenGL errors.
RBGLException Methods
----------------------
Constructor (message as String)
Construct a new RBGLException with a given message. This can be a handy way
to raise custom OpenGL-related exceptions within your own application.
RBGLColor
---------------
---------------
The RBGLColor structure is used for storing colours with an alpha component.
RBGLColor Properties
---------------------
Red As UInt8
Green As UInt8
Blue As UInt8
Alpha As UInt8
The colour components
RBGLColor Methods
------------------
RGBColor () As Color
The method returns the Red, Green and Blue components as an ordinary
REALbasic Color value.
RBGLContextOptions
------------------
------------------
The RBGLContextOptions structure is used to specify options when constructing a
new RBGLContext. These are options that mus be specified when the context is
created, and cannot be changed later.
RBGLContextOptions Properties
------------------------------
Oversampling As UInt8
This property can be used to enable antialising for the context. A value of
zero means no antialiasing, 1 means 2x2 pixel oversampling (each pixel colour
is calculated by averaging a 2x2 block of rendered pixels), 2 means 4x4
oversampling, and so on. Currently oversampling is only supported on Mac OS.
DepthBufferBits As UInt8
StencilBufferBits As UInt8
AccumulationBufferBits As UInt8
The number of bits to use for the OpenGL depth, stencil and accumulation
buffers respectively. Values of 0, 16 or 32 are recommended.