GLIB Reference (last modified 11-Dec-2016)


This is an early and incomplete beta version of the GLIB documentation,
and includes work-in-progress, inaccurate and unreliable information.


GLIB (perhaps short for ‘Graphics LIBrary’) is a collection of graphics functions oriented heavily towards 2D bitmap-based game creation.

It is designed for use—and is compatible only—with BBC BASIC for Windows™  (a.k.a. BB4W).

Download the latest version (0.31 beta) from here (right-click then ‘Save As...’).
Extract the library file GLIB.BBC from the Zip folder, and place it in BB4W's LIB folder.
If you wish to be able to run the example programs provided in this reference, then you will also need to extract the GLIB folder from the Zip folder, and place it in BB4W's LIB folder, alongside the aforementioned GLIB.BBC file. The GLIB folder currently contains a subfolder called ‘Images’, and most of the example programs in this reference rely on the existence of those image files.

To run most of the examples in this documentation, you must also copy the GLIB folder from the Zip folder into BB4W's LIB folder.

Plotting bitmap images and ‘sprites’ with GLIB is straightforward in most cases. For example, this is all you need to plot a 64x64 bitmap:

MODE 8
INSTALL @lib$ + "GLIB"
PROCglib_Init(g{}, p{})
ON ERROR PROCglib_Cleanup : REPORT : PRINT ERL : END
sphere% = FNglib_LoadImg(@lib$ + "GLIB/Images/sphere_64x64x32.bmp", -1)
SYS p.Plot%, g{}, sphere%, 64, 64, 320, 256
PROCglib_Display
PROCglib_Cleanup

Click here to see the output produced by the above program.

Here's another quick example, which draws a background and lots of randomly positioned, semi-transparent sprites:

MODE 8
INSTALL @lib$ + "GLIB"
PROCglib_Init(g{}, p{})
ON ERROR PROCglib_Cleanup : REPORT : PRINT ERL : END
background% = FNglib_LoadImg(@lib$ + "GLIB/Images/bg1_640x512x32.bmp", -1)
sphere% = FNglib_LoadImg(@lib$ + "GLIB/Images/sphere_64x64x32.bmp", -1)
SYS p.BPlot%, g{}, background%, 640, 512, 0, 0
R% = RND(-123456789)
FOR I% = 1 TO 100
  SYS p.PlotAvg%, g{}, sphere%, 64, 64, RND(640)-32, RND(512)-32
NEXT I%
PROCglib_Display
PROCglib_Cleanup

Click here to see the output produced by the above program.

It is important to note that GLIB's graphics functions only handle raw, headerless 32-bpp ARGB32 bitmaps. Usually, a bitmap image will have a so-called ‘header’ section which contains information such as the width and height of the image, the colour depth, the size (in bytes) of the image data, and so on. None of GLIB's graphics functions read a header of any kind. All a GLIB graphics function needs to know is the memory address of a bitmap image's pixel data (not its header), and its width and height. You always have to explicitly state the bitmap's dimensions. Also, GLIB only handles 32-bpp (ARGB32) bitmaps. You should not attempt to directly plot 8-bpp (256-colour) or 24-bpp bitmap images - it simply won't work, and could result in a program/task crash. The same goes for GIF and JPEG images. You can use the function FNglib_LoadImg to load BMP, GIF and JPEG image files into memory which are then automatically converted to the required ARGB32 format. FNglib_LoadImg returns the address of the bitmap's pixel data. Any header information in the original file is discarded.


Initialising GLIB

After INSTALL'ing the library as follows (assuming GLIB.BBC is in BB4W's LIB folder as described above)

INSTALL @lib$ + "GLIB.BBC"

GLIB must be initialised as follows:

PROCglib_Init(g{}, p{})

g{} is one of two structures returned by PROCglib_Init. It contains only three members - a%, w% and h%. After calling PROCglib_Init, the first member a% contains the address of the first pixel of a memory-mapped DIB section (although a% can subsequently be set to point to the address of an arbitrary memory buffer, or even the the bitmap pixel data section of an ARGB32 BMP ) into which bitmaps, sprites, other graphical objects and text are rendered. Think of this DIB section as your canvas. The next two members, w% and h%, are the width and height (respectively) of this canvas. For information about this structure, click here.

The other structure, p{}, for the most part contains the addresses of GLIB's machine code graphics functions. You can invoke these functions with the SYS command as follows:

SYS p.Plot%, g{}, bmAddr, bmW, bmH, x, y
SYS p.RectangleFilled%, g{}, x, y, width, height, colour
SYS p.Clr%, g{}, &80FF80
  etc.

It doesn't actually matter what you call the two structures, as long as they are different and valid structure names. Here they happen to be called g{} and p{}, but they could just as well be called a{} and b{}, or d{} and glib{}, etc. In fact, in the example programs listed in this documentation, the two structures are called g{} and glib{}.


Loading images

GLIB includes an image loading function (FNglib_LoadImg) which will load BMP, GIF and JPEG image files and then automatically convert them (in memory) to the raw ARGB32 format required by GLIB. The following examples illustrate the use of FNglib_LoadImg:

alien% = FNglib_LoadImg( @dir$+"alien.gif", -1 )
background_img% = FNglib_LoadImg( @dir$ + "images\bg.bmp", 0 )
plum% = FNglib_LoadImg( @dir$ + "resources\graphics\plum.jpg", buffer% )


Displaying graphics

When you use GLIB's graphics functions to draw images, they don't normally appear automatically on the screen (or in the program window). In order to actually display whatever it is you have plotted, you would normally use the subroutine PROCglib_Display, as employed in the above two code snippets. Bear in mind that using this subroutine in this way induces a very slight delay (tyipcally 1/60th of a second), before the imagery is displayed because it attempts to synchronise the screen/program window update with the screen's refresh (see this Wikipedia article). This synchronisation is intended (although it's not always successful) to result in smoother animation, scrolling and sprite motion on the screen, with minimal or no flicker, ‘tearing’ and jitter. It works better on some systems than others. If you don't want this attempted synchronisation to take place, then use PROCglib_Display(0) instead.

If you're doing any kind of animation, then you should issue a *REFRESH OFF command beforehand.


FunctionDescription
BoxBlurBlurs a bitmap image by applying a simplistic but relatively fast ‘box blur’ algorithm
BPlotPlots a bitmap (very fast; ideal for plotting background images)
BPlotBlendPlots a semi-transparent bitmap
ByteCopyCopies a block of data in memory, byte by byte, to another location in memory
ClrClears the screen (fills it with a specified colour)
ClrLGSimilar to Clr, except fills screen with a vertical, linear, colour gradient (‘LG’ stands for ‘linear gradient’)
CopyToAlphaChannelEssentially copies a bitmap into its own alpha channel
DrawIconRTRPlots a 32bpp BMP image with optional scaling and reflection about horizontal and/or vertical axes
DWORDCopyCopies a block of data, 4 bytes (one ‘DWORD’) at a time
FillBuffer4Fills a buffer (or contiguous block of memory) with a specified 32-bit value
InvertAlphaChannelInverts all the alpha values in the alpha channel of a bitmap
MergeAlphaMaskMerges an alpha mask (8- or 32-bpp) with a bitmap
PlotPlots a bitmap (very similar to BPlot except black pixels are not plotted, and it's a bit slower)
PlotAvgPlots a bitmap, averaging the colours of its pixels with those of the background pixels
PlotAlphaBlendPlots a bitmap, alpha blending it with the background
PlotBlendPlots a semi-transparent bitmap (identical in effect to BPlotBlend, except black pixels are not processed)
PlotPixelPlots a single pixel
PlotPointPlots a 2x2 point
PlotRotateScalePlots a bitmap, rotated and scaled
PlotRotateScaleRTRPlots a bitmap, rotated and scaled with alpha blending and subpixel positioning
PlotRotateScaleBilinearPlots a bitmap, rotated and scaled with alpha blending, subpixel positioning and bilinear interpolation
PlotScalePlots a scaled bitmap
PlotScaleBlendPlots a scaled, semi-transparent bitmap
PlotGetAlphaBitsPlots a bitmap, returning the cumulative alpha bits of overwritten background pixels
PlotSetAlphaPlots a bitmap, setting the alpha values of overwritten background pixels to a specified value
PlotSetAlphaBitPlots a bitmap, setting the specified bit in the alpha byte of overwritten background pixels
PlotShadowPlots the shape or silhouette of a bitmap as a shadow
PlotShapePlots all non-black pixels in a bitmap as pixels of a specified colour
PlotShuffleRGBPlots a bitmap with the RGB components of each pixel shuffled
PlotTintPlots a colour-tinted bitmap
PlotTintBlendPlots a colour-tinted bitmap, blending it with the background
PremultiplyAlphaMultiplies a bitmap's alpha channel with its RGB values
ReadBitmapPixelReads a pixel from an arbitrary ARGB32 bitmap
ReadPixelReads a pixel from the screen
ReadRGBAReturns the separate RGBA components of a specified pixel
RectangleFilledDraws a filled rectangle
RectangleScaleRGBScales the RGB values of a rectangular area by a factor 0 to 1 (0 to 256)
ScanBitmapScans a bitmap
SetBitmapPixelSets a pixel in an arbitrary bitmap to the specified colour
SetBitmapPixelAlphaSets the alpha value of a pixel in an arbitrary bitmap
SetGlobalAlphaSets all the alpha values in a bitmap to a specified value
ShapeGetAlphaBitsUses the shape/silhouette of a bitmap to obtain the cumulative alpha bits of background pixels
SupersampleSupersamples a bitmap