Parasol Framework
  • Gallery
  • API
  • Wiki
  • GitHub
    •  Overview
        • CopyArea()
        • CopyRawBitmap()
        • DrawPixel()
        • DrawRGBPixel()
        • DrawRectangle()
        • GetColourFormat()
        • ReadPixel()
        • ReadRGBPixel()
        • Resample()
        • SetClipRegion()
        • Sync()
        • AccessPointer()
        • GetCursorInfo()
        • GetCursorPos()
        • GetRelativeCursorPos()
        • LockCursor()
        • RestoreCursor()
        • SetCursor()
        • SetCursorPos()
        • SetCustomCursor()
        • StartCursorDrag()
        • UnlockCursor()
        • GetDisplayInfo()
        • GetDisplayType()
        • ScaleToDPI()
        • SetHostOption()
        • GetInputTypeName()
        • SubscribeInput()
        • UnsubscribeInput()
        • CheckIfChild()
        • CopySurface()
        • ExposeSurface()
        • GetModalSurface()
        • GetSurfaceCoords()
        • GetSurfaceFlags()
        • GetSurfaceInfo()
        • GetUserFocus()
        • GetVisibleArea()
        • SetModalSurface()
        • WindowHook()
    • Audio
    • Core
    • Display
    • Fluid
    • Font
    • Network
    • Vector
      • Audio
      • Sound
      • File
      • MetaClass
      • Module
      • StorageDevice
      • Task
      • Thread
      • Time
      • Compression
      • Config
      • Script
      • XML
      • Controller
      • BlurFX
      • ColourFX
      • CompositeFX
      • ConvolveFX
      • DisplacementFX
      • FilterEffect
      • FloodFX
      • ImageFX
      • LightingFX
      • MergeFX
      • MorphologyFX
      • OffsetFX
      • RemapFX
      • SourceFX
      • TurbulenceFX
      • WaveFunctionFX
      • Scintilla
      • ScintillaSearch
      • Bitmap
      • Clipboard
      • Display
      • Document
      • Font
      • Picture
      • Pointer
      • Surface
      • SVG
      • ClientSocket
      • HTTP
      • NetSocket
      • Proxy
      • Vector
      • VectorClip
      • VectorColour
      • VectorEllipse
      • VectorFilter
      • VectorGradient
      • VectorGroup
      • VectorImage
      • VectorPath
      • VectorPattern
      • VectorPolygon
      • VectorRectangle
      • VectorScene
      • VectorShape
      • VectorSpiral
      • VectorText
      • VectorTransition
      • VectorViewport
      • VectorWave
      • Linux Builds
      • Windows Builds
      • Customising Your Build
      • Parasol Objects
      • Parasol In Depth
      • Fluid Reference Manual
      • Common API
      • FileSearch API
      • GUI API
      • JSON API
      • VFX API
      • Widgets
      • RIPL Reference Manual
      • Parasol Cmd Tool
      • Flute / Unit Testing
      • Embedded Document Format
      • FDL Reference Manual
      • FDL Tools
      • Action Reference Manual
      • System Error Codes

Display Module

Functions

Bitmap

CopyArea | CopyRawBitmap | DrawPixel | DrawRGBPixel | DrawRectangle | GetColourFormat | ReadPixel | ReadRGBPixel | Resample | SetClipRegion | Sync

Cursor

AccessPointer | GetCursorInfo | GetCursorPos | GetRelativeCursorPos | LockCursor | RestoreCursor | SetCursor | SetCursorPos | SetCustomCursor | StartCursorDrag | UnlockCursor

Display

GetDisplayInfo | GetDisplayType | ScaleToDPI | SetHostOption

Input

GetInputTypeName | SubscribeInput | UnsubscribeInput

Surfaces

CheckIfChild | CopySurface | ExposeSurface | GetModalSurface | GetSurfaceCoords | GetSurfaceFlags | GetSurfaceInfo | GetUserFocus | GetVisibleArea | SetModalSurface | WindowHook

Structures

BitmapSurface | ColourFormat | CursorInfo | DisplayInfo | InputEvent | PixelFormat | SurfaceCoords | SurfaceInfo | xrMode

Classes

Bitmap | Clipboard | Controller | Display | Pointer | Surface

Constants

ACF | ALIGN | BAF | BDF | BMF | BMP | CEF | CLIPTYPE | CPF | CRF | CS | CSRF | CT | DMF | DPMS | DRAG | DSF | DT | EXF | GMF | HOST | IRF | JET | JTYPE | LVF | MON | PF | PTC | RNF | RT | SCR | SWIN | WH

AccessPointer()

Returns a lock on the default pointer object.

objPointer * gfx::AccessPointer()

Use AccessPointer() to grab a lock on the default pointer object that is active in the system. This is typically the first object created from the Pointer class with a name of SystemPointer.

Call ReleaseObject() to free the lock once it is no longer required.

Result

Returns the address of the default pointer object.

Display module documentation © Paul Manias 2003-2025

CheckIfChild()

Check if a surface is the child of another surface.

ERR gfx::CheckIfChild(OBJECTID Parent, OBJECTID Child)
ParameterDescription
ParentThe surface that is assumed to be the parent.
ChildThe child surface to check.

This function checks if a surface identified by the Child value is the child of the surface identified by the Parent value. ERR::True is returned if the surface is confirmed as being a child of the parent, or if the Child and Parent values are equal. All other return codes indicate false or failure.

Error Codes

TrueThe Child surface belongs to the Parent.
FalseThe Child surface is not a child of Parent.
NullArgsFunction call missing argument value(s)
Display module documentation © Paul Manias 2003-2025

CopyArea()

Copies a rectangular area from one bitmap to another.

ERR gfx::CopyArea(objBitmap * Bitmap, objBitmap * Dest, BAF Flags, LONG X, LONG Y, LONG Width, LONG Height, LONG XDest, LONG YDest)
ParameterDescription
BitmapThe source bitmap.
DestPointer to the destination bitmap.
FlagsOptional flags.
XThe horizontal position of the area to be copied.
YThe vertical position of the area to be copied.
WidthThe width of the area.
HeightThe height of the area.
XDestThe horizontal position to copy the area to.
YDestThe vertical position to copy the area to.

This function copies rectangular areas from one bitmap to another. It performs a straight region-copy only, using the fastest method available. Bitmaps may be of a different type (e.g. bit depth), however this will result in performance penalties. The copy process will respect the clipping region defined in both the source and destination bitmap objects.

If the TRANSPARENT flag is set in the source object, all colours that match the Bitmap.TransIndex field will be ignored in the copy operation.

To enable dithering, pass BAF::DITHER in the Flags parameter. The drawing algorithm will use dithering if the source needs to be down-sampled to the target bitmap's bit depth. To enable alpha blending, set BAF::BLEND (the source bitmap will also need to have the BMF::ALPHA_CHANNEL flag set to indicate that an alpha channel is available).

The quality of 32-bit alpha blending can be improved by selecting the BAF::LINEAR flag. This enables an additional computation whereby each RGB value is converted to linear sRGB colour space before performing the blend. The discernible value of using this option largely depends on the level of opaqueness of either bitmap. Note that this option is not usable if either bitmap is already in a linear colourspace (ERR::InvalidState will be returned if that is the case).

Error Codes

OkayOperation successful.
MismatchThe destination bitmap is not a close enough match to the source bitmap in order to perform the blit.
InvalidStateThe LINEAR flag was used when at least one bitmap is using a linear colourspace.
NullArgsThe Dest parameter was not specified.
Display module documentation © Paul Manias 2003-2025

CopyRawBitmap()

Copies graphics data from an arbitrary surface to a bitmap.

ERR gfx::CopyRawBitmap(struct BitmapSurfaceV2 * Surface, objBitmap * Dest, CSRF Flags, LONG X, LONG Y, LONG Width, LONG Height, LONG XDest, LONG YDest)
ParameterDescription
SurfaceDescription of the surface source.
DestDestination bitmap.
FlagsOptional flags.
XHorizontal source coordinate.
YVertical source coordinate.
WidthSource width.
HeightSource height.
XDestHorizontal destination coordinate.
YDestVertical destination coordinate.

This function will copy data from a described surface to a destination bitmap object. You are required to provide the function with a full description of the source in a BitmapSurface structure.

The X, Y, Width and Height parameters define the area from the source that you wish to copy. The XDest and YDest parameters define the top left corner that you will blit the graphics to in the destination.

Error Codes

OkayOperation successful.
ArgsInvalid arguments passed to function.
NullArgsFunction call missing argument value(s)
Display module documentation © Paul Manias 2003-2025

CopySurface()

Copies surface graphics data into any bitmap object

ERR gfx::CopySurface(OBJECTID Surface, objBitmap * Bitmap, BDF Flags, LONG X, LONG Y, LONG Width, LONG Height, LONG XDest, LONG YDest)
ParameterDescription
SurfaceThe ID of the surface object to copy from.
BitmapMust reference a target Bitmap object.
FlagsOptional flags.
XThe horizontal source coordinate.
YThe vertical source coordinate.
WidthThe width of the graphic that will be copied.
HeightThe height of the graphic that will be copied.
XDestThe horizontal target coordinate.
YDestThe vertical target coordinate.

This function will copy the graphics data from any surface object to a target Bitmap. This is the fastest and most convenient way to get graphics information out of any surface. As surfaces are buffered, it is guaranteed that the result will not be obscured by any overlapping surfaces that are on the display.

Error Codes

OkayOperation successful.
SearchThe supplied Surface ID did not refer to a recognised surface object
AccessObjectAn attempt to gain exclusive access to a shared object failed.
NullArgsFunction call missing argument value(s)
Display module documentation © Paul Manias 2003-2025

DrawPixel()

Draws a single pixel to a bitmap.

void gfx::DrawPixel(objBitmap * Bitmap, LONG X, LONG Y, ULONG Colour)
ParameterDescription
BitmapThe target bitmap object.
XThe horizontal coordinate of the pixel.
YThe vertical coordinate of the pixel.
ColourThe colour value to use for the pixel.

This function draws a pixel to the coordinates (X, Y) on a bitmap with a colour determined by the Colour index. This function will check the given coordinates to make sure that the pixel is inside the bitmap's clipping area.

Display module documentation © Paul Manias 2003-2025

DrawRGBPixel()

Draws a 24 bit pixel to a Bitmap.

void gfx::DrawRGBPixel(objBitmap * Bitmap, LONG X, LONG Y, struct RGB8 * RGB)
ParameterDescription
BitmapThe target bitmap object.
XHorizontal coordinate of the pixel.
YVertical coordinate of the pixel.
RGBThe colour to be drawn, in RGB format.

This function draws an RGB8 colour to the (X, Y) position of a target Bitmap. The function will check the given coordinates to ensure that the pixel is inside the bitmap's clipping area.

Display module documentation © Paul Manias 2003-2025

DrawRectangle()

Draws rectangles, both filled and unfilled.

void gfx::DrawRectangle(objBitmap * Bitmap, LONG X, LONG Y, LONG Width, LONG Height, ULONG Colour, BAF Flags)
ParameterDescription
BitmapPointer to the target Bitmap.
XThe left-most coordinate of the rectangle.
YThe top-most coordinate of the rectangle.
WidthThe width of the rectangle.
HeightThe height of the rectangle.
ColourThe colour value to use for the rectangle.
FlagsUse FILL to fill the rectangle. Use of BLEND will enable blending.

This function draws both filled and unfilled rectangles. The rectangle is drawn to the target bitmap at position (X, Y) with dimensions determined by the specified Width and Height. If the Flags parameter defines BAF::FILL then the rectangle will be filled, otherwise only the outline will be drawn. The colour of the rectangle is determined by the pixel value in the Colour parameter. Blending is not enabled unless the BAF::BLEND flag is defined and an alpha value is present in the Colour.

Display module documentation © Paul Manias 2003-2025

ExposeSurface()

Exposes the content of a surface to the display.

ERR gfx::ExposeSurface(OBJECTID Surface, LONG X, LONG Y, LONG Width, LONG Height, EXF Flags)
ParameterDescription
SurfaceThe ID of the surface object that will be exposed.
XThe horizontal coordinate of the area to expose.
YThe vertical coordinate of the area to expose.
WidthThe width of the expose area.
HeightThe height of the expose area.
FlagsOptional flags - using CHILDREN will expose all intersecting child regions.

This expose routine will expose all content within a defined surface area, copying it to the display. This will include all child surfaces that intersect with the region being exposed if you set the EXF::CHILDREN flag.

Error Codes

OkayOperation successful.
SearchThe Surface ID does not refer to an existing surface object
NullArgsFunction call missing argument value(s)
Display module documentation © Paul Manias 2003-2025

GetColourFormat()

Generates the values for a ColourFormat structure for a given bit depth.

void gfx::GetColourFormat(struct ColourFormat * Format, LONG BitsPerPixel, LONG RedMask, LONG GreenMask, LONG BlueMask, LONG AlphaMask)
ParameterDescription
FormatPointer to an empty ColourFormat structure.
BitsPerPixelThe depth that you would like to generate colour values for. Ignored if mask values are set.
RedMaskRed component bit mask value. Set this value to zero if the BitsPerPixel parameter is used.
GreenMaskGreen component bit mask value.
BlueMaskBlue component bit mask value.
AlphaMaskAlpha component bit mask value.

This function will generate the values for a ColourFormat structure, for either a given bit depth or customised colour bit values. The ColourFormat structure is used by internal bitmap routines to pack and unpack bit values to and from bitmap memory.

The ColourFormat structure is supported by the following macros for packing and unpacking colour bit values:

Colour = CFPackPixel(Format,Red,Green,Blue)
Colour = CFPackPixelA(Format,Red,Green,Blue,Alpha)
Colour = CFPackAlpha(Format,Alpha)
Red    = CFUnpackRed(Format,Colour)
Green  = CFUnpackGreen(Format,Colour)
Blue   = CFUnpackBlue(Format,Colour)
Alpha  = CFUnpackAlpha(Format,Colour)
Display module documentation © Paul Manias 2003-2025

GetCursorInfo()

Retrieves graphics information from the active mouse cursor.

ERR gfx::GetCursorInfo(struct CursorInfo * Info, LONG Size)
ParameterDescription
InfoPointer to a CursorInfo structure.
SizeThe byte-size of the Info structure.

The GetCursorInfo() function is used to retrieve useful information on the graphics structure of the mouse cursor. It will return the maximum possible dimensions for custom cursor graphics and indicates the optimal bits-per-pixel setting for the hardware cursor.

If there is no cursor (e.g. this is likely on touch-screen devices) then all field values will be set to zero.

Note: If the hardware cursor is monochrome, the bits-per-pixel setting will be set to 2 on return. This does not indicate a 4 colour cursor image; rather colour 0 is the mask, 1 is the foreground colour (black), 2 is the background colour (white) and 3 is an XOR pixel. When creating the bitmap, always set the palette to the RGB values that are wanted. The mask colour for the bitmap must refer to colour index 0.

Error Codes

OkayOperation successful.
NoSupportThe device does not support a cursor (common for touch screen displays).
NullArgsFunction call missing argument value(s)
Display module documentation © Paul Manias 2003-2025

GetCursorPos()

Returns the coordinates of the UI pointer.

ERR gfx::GetCursorPos(DOUBLE * X, DOUBLE * Y)
ParameterDescription
XVariable that will store the pointer's horizontal coordinate.
YVariable that will store the pointer's vertical coordinate.

This function will return the current coordinates of the mouse cursor. If the device is touch-screen based then the coordinates will reflect the last position that a touch event occurred.

Error Codes

OkayOperation successful.
AccessObjectFailed to access the SystemPointer object.
Display module documentation © Paul Manias 2003-2025

GetDisplayInfo()

Retrieves display information.

ERR gfx::GetDisplayInfo(OBJECTID Display, struct DisplayInfoV3 ** Info)
ParameterDescription
DisplayObject ID of the display to be analysed.
InfoThis reference will receive a pointer to a DISPLAYINFO structure.

The GetDisplayInfo() function returns information about a display, which includes information such as its size and bit depth. If the system is running on a hosted display (e.g. Windows or X11) then GetDisplayInfo() can also be used to retrieve information about the default monitor by using a Display of zero.

The resulting DISPLAYINFO structure values remain good until the next call to this function, at which point they will be overwritten.

Error Codes

OkayOperation successful.
AllocMemoryA call to AllocMemory() failed to create a new memory block.
NullArgsFunction call missing argument value(s)
Display module documentation © Paul Manias 2003-2025

GetDisplayType()

Returns the type of display supported.

DT gfx::GetDisplayType()

This function returns the type of display supported by the loaded Display module. Current return values are:

NameDescription
DT::GLESThe display is driven by OpenGLES.
DT::NATIVEThe display is native (supported by internal drivers).
DT::WINGDIThe display is driven by Microsoft Windows drivers.
DT::X11The display is driven by the X Window System (X11, X.Org, XFree86)

Result

Returns an integer indicating the display type.

Display module documentation © Paul Manias 2003-2025

GetInputTypeName()

Returns the string name for an input type.

CSTRING gfx::GetInputTypeName(JET Type)
ParameterDescription
TypeJET type integer.

This function converts JET integer constants to their string equivalent.

Result

A string describing the input Type is returned, or NULL if the Type is invalid.

Display module documentation © Paul Manias 2003-2025

GetModalSurface()

Returns the current modal surface (if defined).

OBJECTID gfx::GetModalSurface()

This function returns the modal surface for the running process. Returns zero if no modal surface is active.

Result

The UID of the modal surface, or zero.

Display module documentation © Paul Manias 2003-2025

GetRelativeCursorPos()

Returns the coordinates of the pointer cursor, relative to a surface object.

ERR gfx::GetRelativeCursorPos(OBJECTID Surface, DOUBLE * X, DOUBLE * Y)
ParameterDescription
SurfaceUnique ID of the surface that the coordinates need to be relative to.
XVariable that will store the pointer's horizontal coordinate.
YVariable that will store the pointer's vertical coordinate.

This function is used to retrieve the current coordinates of the pointer cursor. The coordinates are relative to the surface object that is specified in the Surface argument.

The X and Y parameters will not be set if a failure occurs.

Error Codes

OkayOperation successful.
AccessObjectFailed to access the SystemPointer object.
Display module documentation © Paul Manias 2003-2025

GetSurfaceCoords()

Returns the dimensions of a surface.

ERR gfx::GetSurfaceCoords(OBJECTID Surface, LONG * X, LONG * Y, LONG * AbsX, LONG * AbsY, LONG * Width, LONG * Height)
ParameterDescription
SurfaceThe surface to query. If zero, the top-level display is queried.
XThe X coordinate of the surface is returned here.
YThe Y coordinate of the surface is returned here.
AbsXThe absolute X coordinate of the surface is returned here.
AbsYThe absolute Y coordinate of the surface is returned here.
WidthThe width of the surface is returned here.
HeightThe height of the surface is returned here.

GetSurfaceCoords() retrieves the dimensions that describe a surface object's area as X, Y, Width and Height. This is the fastest way to retrieve surface dimensions when access to the object structure is not already available.

Error Codes

OkayOperation successful.
SearchThe supplied Surface ID did not refer to a recognised surface object.
Display module documentation © Paul Manias 2003-2025

GetSurfaceFlags()

Retrieves the Flags field from a Surface.

ERR gfx::GetSurfaceFlags(OBJECTID Surface, RNF * Flags)
ParameterDescription
SurfaceThe surface to query. If zero, the top-level surface is queried.
FlagsThe flags value is returned here.

This function returns the current Flags field from a Surface. It provides the same result as reading the field directly, however it is considered advantageous in circumstances where the overhead of locking a surface object for a read operation is undesirable.

For information on the available flags, please refer to the Surface.Flags field.

Error Codes

OkayOperation successful.
AccessMemoryAccess to a shared memory block was denied.
NullArgsFunction call missing argument value(s)
Display module documentation © Paul Manias 2003-2025

GetSurfaceInfo()

Retrieves display information for any surface object without having to access it directly.

ERR gfx::GetSurfaceInfo(OBJECTID Surface, struct SurfaceInfoV2 ** Info)
ParameterDescription
SurfaceThe unique ID of a Surface to query. If zero, the root surface is returned.
InfoThis parameter will receive a SurfaceInfo pointer that describes the surface object.

GetSurfaceInfo() is used for quickly retrieving basic information from surfaces, allowing the client to bypass the AccessObject() function. The resulting structure values are good only up until the next call to this function, at which point those values will be overwritten.

Error Codes

OkayOperation successful.
SearchThe supplied SurfaceID did not refer to a recognised surface object.
NullArgsFunction call missing argument value(s)
Display module documentation © Paul Manias 2003-2025

GetUserFocus()

Returns the ID of the surface that currently has the user's focus.

OBJECTID gfx::GetUserFocus()

This function returns the unique ID of the surface that has the user's focus.

Result

Returns the ID of the surface object that has the user focus, or zero on failure.

Display module documentation © Paul Manias 2003-2025

GetVisibleArea()

Returns the visible region of a Surface.

ERR gfx::GetVisibleArea(OBJECTID Surface, LONG * X, LONG * Y, LONG * AbsX, LONG * AbsY, LONG * Width, LONG * Height)
ParameterDescription
SurfaceThe surface to query. If zero, the top-level display will be queried.
XThe X coordinate of the visible area.
YThe Y coordinate of the visible area.
AbsXThe absolute X coordinate of the visible area.
AbsYThe absolute Y coordinate of the visible area.
WidthThe visible width of the surface.
HeightThe visible height of the surface.

The GetVisibleArea() function returns the visible area of a Surface, which is based on its position within its parent surfaces. The resulting coordinates are relative to point 0,0 of the queried surface. If the surface is not obscured, then the resulting coordinates will be (0,0),(Width,Height).

Error Codes

OkayOperation successful.
FailedGeneral failure.
SearchThe supplied Surface ID did not refer to a recognised surface object.
Display module documentation © Paul Manias 2003-2025

LockCursor()

Anchors the cursor so that it cannot move without explicit movement signals.

ERR gfx::LockCursor(OBJECTID Surface)
ParameterDescription
SurfaceRefers to the surface object that the pointer should send movement signals to.

The LockCursor() function will lock the current pointer position and pass UserMovement signals to the surface referenced in the Surface parameter. The pointer will not move unless the SetCursorPos() function is called. The anchor is granted on a time-limited basis. It is necessary to reissue the anchor every time that a UserMovement signal is intercepted. Failure to reissue the anchor will return the pointer to its normal state, typically within 200 microseconds.

The anchor can be released at any time by calling the UnlockCursor() function.

Error Codes

OkayOperation successful.
NoSupportThe pointer cannot be locked due to system limitations.
AccessObjectFailed to access the pointer object.
NullArgsFunction call missing argument value(s)
Display module documentation © Paul Manias 2003-2025

ReadPixel()

Reads a pixel's colour from the target bitmap.

ULONG gfx::ReadPixel(objBitmap * Bitmap, LONG X, LONG Y)
ParameterDescription
BitmapPointer to a bitmap object.
XThe horizontal coordinate of the pixel.
YThe vertical coordinate of the pixel.

This function reads a pixel from a bitmap area and returns its colour index (if the Bitmap is indexed with a palette) or its packed pixel value. Zero is returned if the pixel is out of bounds.

Result

The colour value of the pixel will be returned. Zero is returned if the pixel is out of bounds.

Display module documentation © Paul Manias 2003-2025

ReadRGBPixel()

Reads a pixel's colour from the target bitmap.

void gfx::ReadRGBPixel(objBitmap * Bitmap, LONG X, LONG Y, struct RGB8 ** RGB)
ParameterDescription
BitmapPointer to a bitmap object.
XThe horizontal coordinate of the pixel.
YThe vertical coordinate of the pixel.
RGBThe colour values will be stored in this RGB8 structure.

This function reads a pixel from a bitmap surface and returns the value in an RGB8 structure that remains good up until the next call to this function. Zero is returned in the alpha component if the pixel is out of bounds.

This function is thread-safe if the target Bitmap is locked.

Display module documentation © Paul Manias 2003-2025

Resample()

Resamples a bitmap by dithering it to a new set of colour masks.

ERR gfx::Resample(objBitmap * Bitmap, struct ColourFormat * ColourFormat)
ParameterDescription
BitmapThe bitmap object to be resampled.
ColourFormatThe new colour format to be applied to the bitmap.

The Resample() function provides a means for resampling a bitmap to a new colour format without changing the actual bit depth of the image. It uses dithering so as to retain the quality of the image when down-sampling. This function is generally used to 'pre-dither' true colour bitmaps in preparation for copying to bitmaps with lower colour quality.

You are required to supply a ColourFormat structure that describes the colour format that you would like to apply to the bitmap's image data.

Error Codes

OkayOperation successful.
NullArgsFunction call missing argument value(s)
Display module documentation © Paul Manias 2003-2025

RestoreCursor()

Returns the pointer image to its original state.

ERR gfx::RestoreCursor(PTC Cursor, OBJECTID Owner)
ParameterDescription
CursorThe cursor image that the pointer will be restored to (0 for the default).
OwnerThe ownership ID that was given in the initial call to SetCursor().

Use the RestoreCursor() function to undo an earlier call to SetCursor(). It is necessary to provide the same OwnerID that was used in the original call to SetCursor().

To release ownership of the cursor without changing the current cursor image, use a Cursor setting of PTC::NOCHANGE.

Error Codes

OkayOperation successful.
ArgsInvalid arguments passed to function.
Display module documentation © Paul Manias 2003-2025

ScaleToDPI()

Scales a value to the active display's DPI.

DOUBLE gfx::ScaleToDPI(DOUBLE Value)
ParameterDescription
ValueThe number to be scaled.

ScaleToDPI() is a convenience function for scaling a value to the display's current DPI setting. The provided value must be relative to the system wide default of 96 DPI. If the display's DPI is not equal to 96, the value will be scaled to match. For instance, an 8 point font at 96 DPI would be scaled to 20 points if the display was 240 DPI.

If the DPI of the display is unknown, the value will be returned unscaled.

Result

The scaled value is returned.

Display module documentation © Paul Manias 2003-2025

SetClipRegion()

Sets a clipping region for a bitmap object.

void gfx::SetClipRegion(objBitmap * Bitmap, LONG Number, LONG Left, LONG Top, LONG Right, LONG Bottom, LONG Terminate)
ParameterDescription
BitmapThe target bitmap.
NumberThe number of the clip region to set.
LeftThe horizontal start of the clip region.
TopThe vertical start of the clip region.
RightThe right-most edge of the clip region.
BottomThe bottom-most edge of the clip region.
TerminateSet to true if this is the last clip region in the list, otherwise false.

The SetClipRegion() method is used to manage the clipping regions assigned to a bitmap object. Each new bitmap that is created has at least one clip region assigned to it, but by using SetClipRegion() you can also define multiple clipping areas, which is useful for complex graphics management.

Each clipping region that you set is assigned a Number, starting from zero which is the default. Each time that you set a new clip region you must specify the number of the region that you wish to set. If you attempt to 'skip' regions - for instance, if you set regions 0, 1, 2 and 3, then skip 4 and set 5, the routine will set region 4 instead. If you have specified multiple clip regions and want to lower the count or reset the list, set the number of the last region that you want in your list and set the Terminate parameter to true to kill the regions specified beyond it.

The ClipLeft, ClipTop, ClipRight and ClipBottom fields in the target Bitmap will be updated to reflect the overall area that is covered by the clipping regions that have been set.

Display module documentation © Paul Manias 2003-2025

SetCursor()

Sets the cursor image and can anchor the pointer to any surface.

ERR gfx::SetCursor(OBJECTID Surface, CRF Flags, PTC Cursor, CSTRING Name, OBJECTID Owner)
ParameterDescription
SurfaceRefers to the surface object that the pointer should anchor itself to, if the RESTRICT flag is used. Otherwise, this parameter can be set to a surface that the new cursor image should be limited to. The object referred to here must be publicly accessible to all tasks.
FlagsOptional flags that affect the cursor.
CursorThe ID of the cursor image that is to be set.
NameThe name of the cursor image that is to be set (if Cursor is zero).
OwnerThe object nominated as the owner of the anchor, and/or owner of the cursor image setting.

Use the SetCursor() function to change the pointer image and/or restrict the movement of the pointer to a surface area.

To change the cursor image, set the Cursor or Name parameters to define the new image. Valid cursor ID's and their equivalent names are listed in the documentation for the _Pointer.Cursor_ field. If the Surface field is set to a valid surface, the cursor image will switch back to its default once the pointer moves outside of the surface's area. If both the Cursor and Name parameters are NULL, the cursor image will remain unchanged from its current image.

The SetCursor() function accepts the following flags in the Flags parameter:

NameDescription
CRF::BUFFERUse of the BUFFER option allows the cursor request to be buffered in the event that the cursor is locked at the time of calling the SetCursor() function. Use of this flag is highly recommended in most circumstances, but may not be used in conjunction with the ANCHOR option.
CRF::LMBRelease the cursor after the left mouse button is held and released.
CRF::MMBRelease the cursor after the middle mouse button is held and released.
CRF::NO_BUTTONSSet the cursor only on the condition that the user is not holding down any buttons. ERR::NothingDone is returned if the user has a button held down.
CRF::RESTRICTSimilar to the anchor option, but allows the pointer to move within the surface referred to by ObjectID.
CRF::RMBRelease the cursor after the right mouse button is held and released.

The Owner parameter is used as a locking mechanism to prevent the cursor from being changed whilst it is locked. We recommend that it is set to an object ID such as the program's task ID. As the owner, the cursor remains under your program's control until RestoreCursor() is called.

Error Codes

OkayOperation successful.
NothingDoneThere is nothing to process.
ArgsInvalid arguments passed to function.
LockFailedFailed to lock a required resource.
NoSupportThe pointer cannot be set due to system limitations.
OutOfRangeThe cursor ID is outside of acceptable range.
AccessObjectFailed to access the mouse pointer.
Display module documentation © Paul Manias 2003-2025

SetCursorPos()

Changes the position of the pointer cursor.

ERR gfx::SetCursorPos(DOUBLE X, DOUBLE Y)
ParameterDescription
XThe new horizontal coordinate for the pointer.
YThe new vertical coordinate for the pointer.

Changes the position of the pointer cursor using coordinates relative to the entire display.

Error Codes

OkayOperation successful.
AccessObjectFailed to access the SystemPointer object.
Display module documentation © Paul Manias 2003-2025

SetCustomCursor()

Sets the cursor to a customised bitmap image.

ERR gfx::SetCustomCursor(OBJECTID Surface, CRF Flags, objBitmap * Bitmap, LONG HotX, LONG HotY, OBJECTID Owner)
ParameterDescription
SurfaceRefers to the Surface object that the pointer should restrict itself to, if the RESTRICT flag is used. Otherwise, this parameter can be set to a surface that the new cursor image should be limited to. The object referred to here must be publicly accessible to all tasks.
FlagsOptional flags affecting the cursor are set here.
BitmapThe Bitmap to set for the mouse cursor.
HotXThe horizontal position of the cursor hot-spot.
HotYThe vertical position of the cursor hot-spot.
OwnerThe object nominated as the owner of the anchor.

Use the SetCustomCursor() function to change the pointer image and/or anchor the position of the pointer so that it cannot move without permission. The functionality provided is identical to that of the SetCursor() function with some minor adjustments to allow custom images to be set.

The Bitmap that is provided should be within the width, height and bits-per-pixel settings that are returned by the GetCursorInfo() function. If the basic settings are outside the allowable parameters, the Bitmap will be trimmed or resampled appropriately when the cursor is downloaded to the video card.

It may be possible to speed up the creation of custom cursors by drawing directly to the pointer's internal bitmap buffer rather than supplying a fresh bitmap. To do this, the Bitmap parameter must be NULL and it is necessary to draw to the pointer's bitmap before calling SetCustomCursor(). Note that the bitmap is always returned as a 32-bit, alpha-enabled graphics area. The following code illustrates this process:

if (auto pointer = gfx::AccessPointer()) {
   if (ScopedObjectLock<objBitmap> bitmap(pointer->BitmapID, 3000); bitmap.granted()) {
      // Adjust clipping to match the cursor size.
      buffer->Clip.Right  = CursorWidth;
      buffer->Clip.Bottom = CursorHeight;
      if (buffer->Clip.Right > buffer->Width) buffer->Clip.Right = buffer->Width;
      if (buffer->Clip.Bottom > buffer->Height) buffer->Clip.Bottom = buffer->Height;

      // Draw to the bitmap here.
      ...

      gfx::SetCustomCursor(ObjectID, NULL, NULL, 1, 1, glTaskID, NULL);
   }
   gfx::ReleasePointer(pointer);
}

Error Codes

OkayOperation successful.
ArgsInvalid arguments passed to function.
NoSupportThis request is not supported.
AccessObjectFailed to access the internally maintained image object.
Display module documentation © Paul Manias 2003-2025

SetHostOption()

Alter options associated with the host display system.

ERR gfx::SetHostOption(HOST Option, LARGE Value)
ParameterDescription
OptionOne of TRAY_ICON, TASKBAR or STICK_TO_FRONT.
ValueThe value to be applied to the option.

For internal usage only.

Error Codes

OkayOperation successful.
Display module documentation © Paul Manias 2003-2025

SetModalSurface()

Enables a modal surface for the current task.

OBJECTID gfx::SetModalSurface(OBJECTID Surface)
ParameterDescription
SurfaceThe surface to enable as modal.

Any surface that is created by a task can be enabled as a modal surface. A surface that has been enabled as modal becomes the central point for all GUI interaction with the task. All other I/O between the user and surfaces maintained by the task will be ignored for as long as the target surface remains modal.

A task can switch off the current modal surface by calling this function with a Surface parameter of zero.

If a surface is modal at the time that this function is called, it is not possible to switch to a new modal surface until the current modal state is dropped.

Result

The object ID of the previous modal surface is returned (zero if there was no currently modal surface).

Display module documentation © Paul Manias 2003-2025

StartCursorDrag()

Attaches an item to the cursor for the purpose of drag and drop.

ERR gfx::StartCursorDrag(OBJECTID Source, LONG Item, CSTRING Datatypes, OBJECTID Surface)
ParameterDescription
SourceRefers to an object that is managing the source data.
ItemA custom number that represents the item being dragged from the source.
DatatypesA null terminated byte array that lists the datatypes supported by the source item, in order of conversion preference.
SurfaceA 32-bit composite surface that represents the item being dragged.

This function starts a drag and drop operation with the mouse cursor. The user must be holding the primary mouse button to initiate the drag and drop operation.

A Source object ID is required that indicates the origin of the item being dragged and will be used to retrieve the data on completion of the drag and drop operation. An Item number, which is optional, identifies the item being dragged from the Source object.

The type of data represented by the source item and all other supportable data types are specified in the Datatypes parameter as a null terminated array. The array is arranged in order of preference, starting with the item's native data type. Acceptable data type values are listed in the documentation for the DataFeed action.

The Surface parameter allows for a composite surface to be dragged by the mouse cursor as a graphical representation of the source Item. It is recommended that the graphic be 32x32 pixels in size and no bigger than 64x64 pixels. The Surface will be hidden on completion of the drag and drop operation.

If the call to StartCursorDrag() is successful, the mouse cursor will operate in drag and drop mode. The UserMovement and UserClickRelease actions normally reported from the SystemPointer will now include the JD_DRAGITEM flag in the ButtonFlags parameter. When the user releases the primary mouse button, the drag and drop operation will stop and the DragDrop action will be passed to the surface immediately underneath the mouse cursor. Objects that are monitoring for the DragDrop action on that surface can then contact the Source object with a DataFeed DragDropRequest. The resulting data is then passed to the requesting object with a DragDropResult on the DataFeed.

Error Codes

OkayOperation successful.
InUseA drag and drop operation has already been started.
FailedThe left mouse button is not held by the user.
AccessObjectAn attempt to gain exclusive access to a shared object failed.
NullArgsFunction call missing argument value(s)
Display module documentation © Paul Manias 2003-2025

SubscribeInput()

Subscribe to incoming input messages for any active surface object.

ERR gfx::SubscribeInput(FUNCTION * Callback, OBJECTID SurfaceFilter, JTYPE Mask, OBJECTID DeviceFilter, LONG * Handle)
ParameterDescription
CallbackReference to a callback function that will receive input messages.
SurfaceFilterOptional. Only the input messages that match the given Surface ID will be received.
MaskCombine JTYPE flags to define the input messages required by the client. Set to 0xffffffff if all messages are required.
DeviceFilterOptional. Only the input messages that match the given device ID will be received. NOTE - Support not yet implemented, set to zero.
HandleA handle for the subscription is returned here.

The SubscribeInput() function provides a systematic way of receiving input events as they occur. Coverage is limited to device events that are linked to the display (i.e. events from track pads, mouse pointers, graphics tablets and touch screens). Keyboard devices are not included.

The client is required to remove the subscription with UnsubscribeInput() once tracking is no longer required.

Input events can be filtered so that they are received in relation to surfaces and devices. An input mask can also be applied so that only certain types of events are received.

A callback is required for receiving the input events. The following C++ code illustrates a method for processing events in the callback:

ERR consume_input_events(const InputEvent *Events, LONG Handle)
{
   for (auto e=Events; e; e=e->Next) {
      if (((e->Flags & JTYPE::BUTTON) != JTYPE::NIL) and (e->Value > 0)) {
         process_click(Self, e->RecipientID, e->X, e->Y);
      }
   }

   return ERR::Okay;
}

All processable events are referenced in the InputEvent structure in the Events parameter.

JET constants are as follows and take note of CROSSED_IN and CROSSED_OUT which are software generated and not a device event:

NameDescription
JET::ABS_XYThe X, Y values are defined as absolute coordinates, relative to the top-left of the display.
JET::BUTTON_1Left mouse button; XBox A button, PS square button. Value is pressure sensitive, ranging between 0 - 1.0 (0 is released, 1.0 is fully depressed).
JET::BUTTON_10Non-specific button assignment.
JET::BUTTON_2Right mouse button; XBox X button, PS cross button.
JET::BUTTON_3Middle mouse button; XBox Y button, PS triangle.
JET::BUTTON_4Alt. mouse button 1; XBox B button, PS circle.
JET::BUTTON_5Alt. mouse button 2.
JET::BUTTON_6Non-specific button assignment.
JET::BUTTON_7Non-specific button assignment.
JET::BUTTON_8Non-specific button assignment.
JET::BUTTON_9Non-specific button assignment.
JET::CROSSED_INThis message is sent by the input system when the mouse pointer enters an area for the first time. The message value refers to the object ID of the container being monitored for movement.
JET::CROSSED_OUTThis message is sent by the input system when the mouse pointer leaves an area. The message value refers to the object ID of the container being monitored for movement.
JET::DEVICE_TILT_XYController tilted on the X/Y axis. Value indicates angle, -ve = left, +ve = right
JET::DEVICE_TILT_ZController is rising or falling. Value expressed as 'speed',
JET::DISPLAY_EDGERecently supplied input occurred at the edge of the display.
JET::PEN_TILT_XYFor pen-based input, this type indicates the vertical tilt of the pen device. A value of 0 indicates that the pen is laid flat with nib at the bottom, 0.5 is 90 degrees, 1.0 is laid flat with nib at the top.
JET::PRESSUREAmount of pressure applied, ranges from 0 (none) to 1.0 (normal) and possibly higher if user presses hard enough
JET::WHEELMouse wheel rotation - the value generally reflects the number of 'clicks' rotated on the wheel.
JET::WHEEL_TILTSome mouse wheels can be tilted to the left or right. Ranges from -1.0 to +1.0

The JTYPE values for the Flags field are as follows. Note that these flags also serve as input masks for the SubscribeInput() function, so to receive a message of the given type the appropriate JTYPE flag must have been set in the original subscription call.

NameDescription
JTYPE::ANALOGAnalog movement (ranging from -1.0 to 1.0)
JTYPE::ANCHOREDCursor has been anchored with LockCursor()
JTYPE::BUTTONInput is a physical button or switch
JTYPE::CROSSINGCrossing events manage the entering and leaving of an area.
JTYPE::DBL_CLICKSet by the input system if the Type is a button and the button has been clicked in quick succession so as to be classed as a double-click.
JTYPE::DIGITALD-Pad or digital joystick source (restricted to +/- 1)
JTYPE::DRAGGEDSet if sufficient movement occurred between the original click and its point of release (usually requires a 3 or more pixel difference).
JTYPE::DRAG_ITEMThis special flag is set by the input system if the pointer is click-dragging an object at the time of the event.
JTYPE::EXT_MOVEMENTExtended or indirect movement information. This covers all types of movement that are unconnected to coordinate positioning - mouse wheel movement and pen tilt are two such examples.
JTYPE::MOVEMENTX/Y coordinate movement only. Movement such as the wheel mouse spinning is not covered by this type as it does not influence the coordinate system.
JTYPE::REPEATEDInput is a repeated entry (i.e. user is holding down a button and a repetition timer is being triggered)
JTYPE::SECONDARYIndicates to the receiver of this message that it is not the primary/original recipient

Error Codes

OkayOperation successful.
NullArgsFunction call missing argument value(s)
Display module documentation © Paul Manias 2003-2025

Sync()

Waits for the completion of all active bitmap operations.

void gfx::Sync(objBitmap * Bitmap)
ParameterDescription
BitmapPointer to the bitmap that you want to synchronise or NULL to sleep on the graphics accelerator.

The Sync() function will wait for all current video operations to complete before it returns. This ensures that it is safe to write to video memory with the CPU, preventing any possibility of clashes with the onboard graphics chip.

Display module documentation © Paul Manias 2003-2025

UnlockCursor()

Undoes an earlier call to LockCursor()

ERR gfx::UnlockCursor(OBJECTID Surface)
ParameterDescription
SurfaceRefers to the surface object used for calling LockCursor().

Call this function to undo any earlier calls to LockCursor() and return the mouse pointer to its regular state.

Error Codes

OkayOperation successful.
NotLockedA lock is not present, or the lock belongs to another surface.
AccessObjectFailed to access the pointer object.
NullArgsFunction call missing argument value(s)
Display module documentation © Paul Manias 2003-2025

UnsubscribeInput()

Removes an input subscription.

ERR gfx::UnsubscribeInput(LONG Handle)
ParameterDescription
HandleReference to a handle returned by SubscribeInput().

This function removes an input subscription that has been created with SubscribeInput().

Error Codes

OkayOperation successful.
NotFoundA search routine in this function failed.
NullArgsFunction call missing argument value(s)
Display module documentation © Paul Manias 2003-2025

WindowHook()

Adds a function hook for receiving window messages from a host desktop.

ERR gfx::WindowHook(OBJECTID SurfaceID, WH Event, FUNCTION * Callback)
ParameterDescription
SurfaceIDA hosted surface to be monitored.
EventA window hook event.
CallbackA function to callback when the event is triggered.

Adds a function hook for receiving window events from a host desktop.

Error Codes

OkayOperation successful.
NullArgsFunction call missing argument value(s)
Display module documentation © Paul Manias 2003-2025

ACF Type

Acceleration flags for GetDisplayInfo().

NameDescription
ACF::SOFTWARE_BLITSoftware blitting is used (or forced) for this display.
ACF::VIDEO_BLITVideo blitting is supported for this display.
Display module documentation © Paul Manias 2003-2025

ALIGN Type

Universal values for alignment of graphics and text

NameDescription
ALIGN::BOTTOMAlign to bottom
ALIGN::CENTERSynonym for HORIZONTAL | VERTICAL
ALIGN::HORIZONTALAlign to horizontal center
ALIGN::LEFTAlign to left
ALIGN::MIDDLESynonym for HORIZONTAL | VERTICAL
ALIGN::RIGHTAlign to right
ALIGN::TOPAlign to top
ALIGN::VERTICALAlign to vertical center
Display module documentation © Paul Manias 2003-2025

BAF Type

Instructions for basic graphics operations.

NameDescription
BAF::BLENDEnable alpha blending to the destination if the source supports an alpha channel.
BAF::COPYSpecial CopyArea() option that avoids blending when the destination pixel is empty.
BAF::DITHERPerform dithering if the colour formats differ between the source and destination.
BAF::FILLFor primitive operations such as DrawRectangle(), this will fill the shape with a solid colour or texture.
BAF::LINEARUse linear interpolation to improve the quality of alpha blending.
Display module documentation © Paul Manias 2003-2025

BDF Type

CopySurface() flags

NameDescription
BDF::DITHERAllow the use of dithering to improve image quality at a cost of speed.
BDF::REDRAWRedraw the surface before performing the copy operation.
Display module documentation © Paul Manias 2003-2025

BMF Type

Bitmap flags

NameDescription
BMF::ACCELERATED_2D2D video acceleration is available.
BMF::ACCELERATED_3D3D video acceleration is available.
BMF::ALPHA_CHANNELFor 32-bit images, indicates that an alpha channel is present.
BMF::BLANK_PALETTEForces a blank/black palette on initialisation.
BMF::CLEARClear graphics on initialisation and when resizing.
BMF::COMPRESSEDThe bitmap data is compressed.
BMF::FIXED_DEPTHPrevent changing of bitmap depth after initialisation (e.g. via Resize()).
BMF::INVERSE_ALPHAIndicates reverse alpha blending, higher values are transparent.
BMF::MASKDeclare the Bitmap as a 1 or 8 bit mask. Must be set in conjunction with the Bitmap.BitsPerPixel field on initialisation.
BMF::NEVER_SHRINKIgnore resize requests that would shrink the size of the bitmap.
BMF::NO_BLENDDrawing routines that support this flag will not blend pixels.
BMF::NO_DATADo not allocate memory in the Data field on initialisation.
BMF::PREMULThe RGB values are premultiplied (32-bit only).
BMF::QUERIEDAutomatically set after a Query() on the bitmap.
BMF::TRANSPARENTIndicates that the bitmap utilises a transparent colour. This is automatically set if the Bitmap.TransIndex or Bitmap.TransColour is defined, and support exists in functions such as CopyArea().
BMF::USERThis user flag can be used to tag bitmaps with special meaning. Not used internally.
Display module documentation © Paul Manias 2003-2025

BMP Type

Bitmap types

NameDescription
BMP::CHUNKYChunky pixel mode (default).
BMP::PLANARPlanar pixel mode separates pixel bits across multiple planes. Commonly used for single bit bitmap masks.
Display module documentation © Paul Manias 2003-2025

CEF Type

NameDescription
CEF::DELETERequests that the original file source is deleted if a successful paste operation takes place.
CEF::EXTENDInstead of replacing existing clipboard data, add the new data to the group.
Display module documentation © Paul Manias 2003-2025

CLIPTYPE Type

Clipboard types

NameDescription
CLIPTYPE::AUDIOAn audio clip that is recognised by the Sound class (such as wav's and mp3's).
CLIPTYPE::DATARaw information that is uncategorised can be defined as a data clip.
CLIPTYPE::FILEPure file references are stored as file clips. This type is typically used by file managers for moving and copying files.
CLIPTYPE::IMAGEImages that are recognised by the Picture class may be stored as this type (such as jpeg's and png files).
CLIPTYPE::OBJECTAn object that has been deserialised into binary form.
CLIPTYPE::TEXTPlain text files such as ASCII and UTF-8 must be identified through this clip type.
Display module documentation © Paul Manias 2003-2025

CPF Type

Clipboard flags

NameDescription
CPF::DRAG_DROPEnables drag and drop mode. The clipboard content will be private and not share data with the host system in this mode.
CPF::HISTORY_BUFFEREnables the history buffer. Note that this results in active clipboard monitoring and the program will make copies of all potential clipboard content - whether it is used or not.
CPF::HOSTThis indicator is automatically set when a clipboard was created due to incoming content from the host system.
Display module documentation © Paul Manias 2003-2025

CRF Type

Flags for the SetCursor() function.

NameDescription
CRF::BUFFERUse of the BUFFER option allows the cursor request to be buffered in the event that the cursor is locked at the time of calling the SetCursor() function. Use of this flag is highly recommended in most circumstances, but may not be used in conjunction with the ANCHOR option.
CRF::LMBRelease the cursor after the left mouse button is held and released.
CRF::MMBRelease the cursor after the middle mouse button is held and released.
CRF::NO_BUTTONSSet the cursor only on the condition that the user is not holding down any buttons. ERR::NothingDone is returned if the user has a button held down.
CRF::RESTRICTSimilar to the anchor option, but allows the pointer to move within the surface referred to by ObjectID.
CRF::RMBRelease the cursor after the right mouse button is held and released.
Display module documentation © Paul Manias 2003-2025

CS Type

Colour space options.

NameDescription
CS::CIE_LABCartesian L*a*b* colour space defined by CIE 15.
CS::CIE_LCHPolar L*CHab colour space defined by CIE 15.
CS::LINEAR_RGBLinear RGB is used to improve colour balance in blending operations.
CS::SRGBThe default colour-space is sRGB.
Display module documentation © Paul Manias 2003-2025

CSRF Type

Flags for CopySurface().

NameDescription
CSRF::ALPHAEnable alpha blending if the source is in 32-bit colour format with an alpha channel.
CSRF::CLIPEnable clipping of the source coordinates.
CSRF::DEFAULT_FORMATIgnore the colour format defined in the source surface (if any) and generate a default format based on the BitsPerPixel value.
CSRF::OFFSETAdjust X and Y coordinates by the offset values defined in the Surface.XOffset and Surface.YOffset fields.
CSRF::TRANSLUCENTPerform a translucent copy operation, using the strength value specified in the Surface.Opacity field.
CSRF::TRANSPARENTEnable transparent copying, whereby colours matching the source's Colour field will be ignored.
Display module documentation © Paul Manias 2003-2025

CT Type

NameDescription
CT::AUDIO
CT::DATA
CT::END
CT::FILE
CT::IMAGE
CT::OBJECT
CT::TEXT
Display module documentation © Paul Manias 2003-2025

DMF Type

NameDescription
DMF::FIXED_CENTER_XThe CenterX field is a fixed size.
DMF::FIXED_CENTER_YThe CenterY field is a fixed size.
DMF::FIXED_DEPTHThe Depth field is a fixed size.
DMF::FIXED_HEIGHTThe Height field is a fixed size.
DMF::FIXED_RADIUS_XThe RadiusX field is a fixed size.
DMF::FIXED_RADIUS_YThe RadiusY field is a fixed size.
DMF::FIXED_WIDTHThe Width field is a fixed suze.
DMF::FIXED_XThe X field is a fixed coordinate.
DMF::FIXED_X_OFFSETThe XOffset field is a fixed coordinate.
DMF::FIXED_YThe Y field is a fixed coordinate.
DMF::FIXED_Y_OFFSETThe YOffset field is a fixed coordinate.
DMF::FIXED_ZThe Z field is a fixed coordinate.
DMF::SCALED_CENTER_XThe CenterX field is scaled to this object's parent.
DMF::SCALED_CENTER_YThe CenterY field is scaled to this object's parent.
DMF::SCALED_DEPTHThe Depth field is scaled to this object's parent.
DMF::SCALED_HEIGHTThe Height field is scaled to this object's parent.
DMF::SCALED_RADIUS_XThe RadiusX field is scaled to this object's parent.
DMF::SCALED_RADIUS_YThe RadiusY field is a scaled size to this object's parent.
DMF::SCALED_WIDTHThe Width field is scaled to this object's parent.
DMF::SCALED_XThe X field is scaled to this object's parent.
DMF::SCALED_X_OFFSETThe XOffset field is scaled to this object's parent.
DMF::SCALED_YThe Y field is scaled to this object's parent.
DMF::SCALED_Y_OFFSETThe YOffset field is scaled to this object's parent.
DMF::SCALED_ZThe Z field is a scaled coordinate to this object's parent.
DMF::STATUS_CHANGE_H
DMF::STATUS_CHANGE_V
Display module documentation © Paul Manias 2003-2025

DPMS Type

Possible modes for the Display class' PowerMode field.

NameDescription
DPMS::DEFAULTUse the default DPMS mode as defined by the display driver.
DPMS::OFFStop sending power to the display in order to turn it off (it may not be possible to restart the display without the user's intervention).
DPMS::STANDBYPuts the display into standby (reduced power) mode.
DPMS::SUSPENDPuts the display into suspend mode (blanks the display output while maintaining normal power levels).
Display module documentation © Paul Manias 2003-2025

DRAG Type

NameDescription
DRAG::ANCHORThe surface is being dragged and the mouse pointer is anchored to the surface.
DRAG::NONEThe surface is not being dragged.
DRAG::NORMALThe surface is being dragged.
Display module documentation © Paul Manias 2003-2025

DSF Type

NameDescription
DSF::NO_DRAWDrawing and exposures are disabled
DSF::NO_EXPOSEDrawing is enabled, exposures are disabled
Display module documentation © Paul Manias 2003-2025

DT Type

Flags for GetDisplayType().

NameDescription
DT::GLESThe display is driven by OpenGLES.
DT::NATIVEThe display is native (supported by internal drivers).
DT::WINGDIThe display is driven by Microsoft Windows drivers.
DT::X11The display is driven by the X Window System (X11, X.Org, XFree86)
Display module documentation © Paul Manias 2003-2025

EXF Type

Optional flags for the ExposeSurface() function.

NameDescription
EXF::ABSOLUTEThe supplied coordinates for exposure are absolute (relative to the display).
EXF::ABSOLUTE_COORDSThe supplied coordinates for exposure are absolute (relative to the display).
EXF::CHILDRENIf set, all child surfaces that intersect with exposed region will be included in the expose operation.
EXF::REDRAW_VOLATILERedraw every volatile object that intersects with the expose region, including internal volatile children.
EXF::REDRAW_VOLATILE_OVERLAPOnly redraw volatile objects that obscure the expose region from a position outside of the target surface and its children. Useful if no redrawing has occurred in the surface, but the surface has moved to a new position and the parents need to be redrawn.
Display module documentation © Paul Manias 2003-2025

GMF Type

Flags for gamma operations.

NameDescription
GMF::SAVESave the provided settings permanently.
Display module documentation © Paul Manias 2003-2025

HOST Type

NameDescription
HOST::STICK_TO_FRONTThe hosted display sticks to the front.
HOST::TASKBARThe hosted display is given a taskbar button.
HOST::TRANSLUCENCEChange the alpha channel level for the entire window.
HOST::TRANSPARENTDefines an RGB colour that is to be used as transparent.
HOST::TRAY_ICONAll new displays are represented in the system tray when this option is active.
Display module documentation © Paul Manias 2003-2025

IRF Type

Flags for RedrawSurface().

NameDescription
IRF::FORCE_DRAWForces redrawing to the surface buffer (overrides visibility checks).
IRF::IGNORE_CHILDRENDo not draw child surfaces (this includes volatile children).
IRF::IGNORE_NV_CHILDRENDo not draw child surfaces unless they are volatile.
IRF::RELATIVECoordinate parameters are expressed in relative format. Right and Bottom reflect Width and Height respectively.
IRF::SINGLE_BITMAPOnly draw children and/or siblings when they share our bitmap space.
Display module documentation © Paul Manias 2003-2025

JET Type

JET constants are documented in GetInputEvent()

NameDescription
JET::ABS_XYThe X, Y values are defined as absolute coordinates, relative to the top-left of the display.
JET::BUTTON_1Left mouse button; XBox A button, PS square button. Value is pressure sensitive, ranging between 0 - 1.0 (0 is released, 1.0 is fully depressed).
JET::BUTTON_10Non-specific button assignment.
JET::BUTTON_2Right mouse button; XBox X button, PS cross button.
JET::BUTTON_3Middle mouse button; XBox Y button, PS triangle.
JET::BUTTON_4Alt. mouse button 1; XBox B button, PS circle.
JET::BUTTON_5Alt. mouse button 2.
JET::BUTTON_6Non-specific button assignment.
JET::BUTTON_7Non-specific button assignment.
JET::BUTTON_8Non-specific button assignment.
JET::BUTTON_9Non-specific button assignment.
JET::CROSSED_INThis message is sent by the input system when the mouse pointer enters an area for the first time. The message value refers to the object ID of the container being monitored for movement.
JET::CROSSED_OUTThis message is sent by the input system when the mouse pointer leaves an area. The message value refers to the object ID of the container being monitored for movement.
JET::DEVICE_TILT_XYController tilted on the X/Y axis. Value indicates angle, -ve = left, +ve = right
JET::DEVICE_TILT_ZController is rising or falling. Value expressed as 'speed',
JET::DISPLAY_EDGERecently supplied input occurred at the edge of the display.
JET::PEN_TILT_XYFor pen-based input, this type indicates the vertical tilt of the pen device. A value of 0 indicates that the pen is laid flat with nib at the bottom, 0.5 is 90 degrees, 1.0 is laid flat with nib at the top.
JET::PRESSUREAmount of pressure applied, ranges from 0 (none) to 1.0 (normal) and possibly higher if user presses hard enough
JET::WHEELMouse wheel rotation - the value generally reflects the number of 'clicks' rotated on the wheel.
JET::WHEEL_TILTSome mouse wheels can be tilted to the left or right. Ranges from -1.0 to +1.0
Display module documentation © Paul Manias 2003-2025

JTYPE Type

JTYPE flags are used to categorise input types.

NameDescription
JTYPE::ANALOGAnalog movement (ranging from -1.0 to 1.0)
JTYPE::ANCHOREDCursor has been anchored with LockCursor()
JTYPE::BUTTONInput is a physical button or switch
JTYPE::CROSSINGCrossing events manage the entering and leaving of an area.
JTYPE::DBL_CLICKSet by the input system if the Type is a button and the button has been clicked in quick succession so as to be classed as a double-click.
JTYPE::DIGITALD-Pad or digital joystick source (restricted to +/- 1)
JTYPE::DRAGGEDSet if sufficient movement occurred between the original click and its point of release (usually requires a 3 or more pixel difference).
JTYPE::DRAG_ITEMThis special flag is set by the input system if the pointer is click-dragging an object at the time of the event.
JTYPE::EXT_MOVEMENTExtended or indirect movement information. This covers all types of movement that are unconnected to coordinate positioning - mouse wheel movement and pen tilt are two such examples.
JTYPE::MOVEMENTX/Y coordinate movement only. Movement such as the wheel mouse spinning is not covered by this type as it does not influence the coordinate system.
JTYPE::REPEATEDInput is a repeated entry (i.e. user is holding down a button and a repetition timer is being triggered)
JTYPE::SECONDARYIndicates to the receiver of this message that it is not the primary/original recipient
Display module documentation © Paul Manias 2003-2025

LVF Type

drwLockBitmap() result flags

NameDescription
LVF::EXPOSE_CHANGES
Display module documentation © Paul Manias 2003-2025

MON Type

Flags for the Display class SetMonitor() method.

NameDescription
MON::AUTO_DETECTMonitor settings to be auto-detected on startup.
MON::BIT_6The device is limited to 6-bit colour production in real terms.
Display module documentation © Paul Manias 2003-2025

PF Type

Flags for the Pointer class.

NameDescription
PF::ANCHORAllow the pointer to be anchored.
PF::UNUSED
PF::VISIBLEIndicates that the pointer is currently visible. Read-only.
Display module documentation © Paul Manias 2003-2025

PTC Type

Predefined cursor styles

NameDescription
PTC::CROSSHAIRThe cross hair is used for targeting specific pixel points (common in paint programs).
PTC::CUSTOMWorks in conjunction with the SetCustomCursor() function to represent a program defined bitmap.
PTC::DEFAULTThe default cursor (usually an arrow pointing to the upper left).
PTC::DRAGGABLEUsed to indicate that a surface or object can be dragged by the user.
PTC::END
PTC::HANDThe hand cursor is often used for indicating click-able content (hyper-links, icons etc).
PTC::HAND_LEFTSimilar to the standard hand cursor, but points to the left.
PTC::HAND_RIGHTSimilar to the standard hand cursor, but points to the right.
PTC::INVISIBLEThe cursor graphic is invisible (but will continue to operate as normal in all other respects).
PTC::MAGNIFIERRepresents a magnifying glass.
PTC::NO_CHANGE
PTC::PAINTBRUSHThe paintbrush cursor is typically employed by paint programs.
PTC::SIZE_BOTTOMSizing cursor - for resizing the bottom edge of any rectangular area.
PTC::SIZE_BOTTOM_LEFTSizing cursor - for resizing the bottom left corner of any rectangular area.
PTC::SIZE_BOTTOM_RIGHTSizing cursor - for resizing the bottom right corner of any rectangular area.
PTC::SIZE_LEFTSizing cursor - for resizing the left edge of any rectangular area.
PTC::SIZE_RIGHTSizing cursor - for resizing the right edge of any rectangular area.
PTC::SIZE_TOPSizing cursor - for resizing the top edge of any rectangular area.
PTC::SIZE_TOP_LEFTSizing cursor - for resizing the top left corner of any rectangular area.
PTC::SIZE_TOP_RIGHTSizing cursor - for resizing the top right corner of any rectangular area.
PTC::SIZINGMulti-directional sizing cursor - for resizing in any direction.
PTC::SLEEPThe sleep cursor is used to inform the user that the computer is busy.
PTC::SPLIT_HORIZONTALThe horizontal split cursor is typically used for splitting rectangles in half, or dragging a horizontal split within a large rectangular space.
PTC::SPLIT_VERTICALThe vertical split cursor is typically used for splitting rectangles in half, or dragging a vertical split within a large rectangular space.
PTC::STOPThe stop cursor is used to inform the user that an operation is not possible (e.g. drag and drop to an unsupported object area).
PTC::TEXTThe text cursor is popular for the precise positioning of text cursors.
Display module documentation © Paul Manias 2003-2025

RNF Type

Switches for the Surface class' Flags field.

NameDescription
RNF::AFTER_COPYRead-only. Indicates that after-copy mode has been enabled.
RNF::ASPECT_RATIOWhen resizing, enforce the aspect ratio as defined by the diagonal from Surface.MinWidth, Surface.MinHeight to Surface.MaxWidth, Surface.MaxHeight.
RNF::AUTO_QUITThe surface object will send a quit message to its supporting process when and if the Close method is called. This flag is typically used when a surface object represents a core window for an application.
RNF::COMPOSITEDo not copy background information into the surface buffer - composite on the fly instead
RNF::DISABLEDThis flag is set if the Disable action has been called on a surface object. Calling the Enable action will turn off the flag setting.
RNF::FIXED_BUFFERPasses the NEVER_SHRINK option to the surface bitmap
RNF::FIXED_DEPTHThe target buffer always remains at the same depth
RNF::FULL_SCREENAllow the surface to open as a new screen display
RNF::GRAB_FOCUSHelps application windows manage the user's focus within the window
RNF::HAS_FOCUSRead-only. If set, this flag indicates that the surface object currently has the focus.
RNF::HOSTDefine host on initialisation to create a container that can host surfaces from other processes.
RNF::IGNORE_FOCUSFocus is diverted directly to the parent
RNF::INIT_ONLYSynonym for HOST | TRANSPARENT | DISABLED | PRECOPY | VIDEO | FIXED_BUFFER | PERVASIVE_COPY | FIXED_DEPTH | FULL_SCREEN | IGNORE_FOCUS
RNF::NO_FOCUSPrevents any kind of focussing on this object; no circumvention is possible
RNF::NO_HORIZONTALTurns off all horizontal movement (applies to the Move() action only).
RNF::NO_PRECOMPOSITEDo not copy background information into the surface buffer - composite on the fly instead
RNF::NO_VERTICALTurns off all vertical movement (applies to the Move() action only).
RNF::PERVASIVE_COPYThis flag can be set in conjunction with after-copy mode. It forces the after-copy support routine to copy graphics over the entire surface area, rather than avoiding the graphics of child surfaces.
RNF::POST_COMPOSITEDo not copy background information into the surface buffer - composite on the fly instead
RNF::PRECOPYEnables pre-copy mode, which means that all graphics behind the surface object are copied into the bitmap buffer prior to any redraw. This mode can have a noticable impact on CPU time when drawing.
RNF::READ_ONLYSynonym for HAS_FOCUS | CURSOR | AFTER_COPY
RNF::STICKYPrevents any response to the Move action. It can be circumvented by writing to coordinate fields directly.
RNF::STICK_TO_BACKEnable if the surface object must stick to the back of its container.
RNF::STICK_TO_FRONTEnable if the surface object must stick to the front of its container.
RNF::TOTAL_REDRAWPerform a total redraw of the entire surface when drawing - no partial draws
RNF::TRANSPARENTEnables transparency, which means that the internal graphics routines will ignore this surface during redraws. It is typically used when creating containers that will host other surfaces.
RNF::VIDEOSet this flag if you would like the surface object's data to be managed in video memory only. While this can give some speed advantages, be warned that video based surfaces are limited to write-only operations.
RNF::VISIBLEIf a surface object is visible to the user, the VISIBLE flag will be set. If the flag is not set, the surface object is hidden.
RNF::VOLATILESynonym for PRECOPY | AFTER_COPY | CURSOR
RNF::WRITE_ONLYSet this flag if you would like the surface object's data to be managed in video memory only. While this can give some speed advantages, be warned that video based surfaces are limited to write-only operations.
Display module documentation © Paul Manias 2003-2025

RT Type

NameDescription
RT::ROOTCan be used by window surfaces to identify themselves as a root layer.
Display module documentation © Paul Manias 2003-2025

SCR Type

Display flags.

NameDescription
SCR::ALPHA_BLENDEnables alpha channel blending (if display is hosted and 32-bit).
SCR::AUTO_SAVESaves settings to the global display state when the object is freed.
SCR::BIT_6Display is limited to 6-bit output per colour gun.
SCR::BORDERLESSIf display is hosted, create it as a popup / borderless window.
SCR::BUFFERSet if you would like a complementing buffer in video RAM.
SCR::COMPOSITEEnables alpha channel blending (if display is hosted and 32-bit).
SCR::CUSTOM_WINDOWThe display has been created with a custom window reference.
SCR::DPMS_ENABLEDPower saving through DPMS is supported.
SCR::FLIPPABLEIf SCR::BUFFER is used, this flag may be set by the display manager if it is possible to flip the buffer.
SCR::GRAB_CONTROLLERSGrab controllers for receiving input when the display has the focus.
SCR::GTF_ENABLEDGTF frequency timings are supported.
SCR::HOSTEDThe display is a desktop hosted window.
SCR::MAXIMISESpecial win32 flag.
SCR::MAXSIZEFor GetDisplayInfo() only, indicates that the width and height values indicate the display's maximum size.
SCR::NO_ACCELERATION2D graphics card acceleration is not available.
SCR::POWERSAVEPower saving is active (read-only).
SCR::READ_ONLYSynonym for MAXIMISE | CUSTOM_WINDOW | FLIPPABLE | GTF_ENABLED | DPMS_ENABLED | POWERSAVE | HOSTED | MAXSIZE | REFRESH | BIT_6 | VISIBLE | NO_ACCELERATION
SCR::REFRESHFor GetDisplayInfo() only, used to indicate that a display change has recently occurred and cache refresh is required.
SCR::VISIBLESet if the screen is on display.
Display module documentation © Paul Manias 2003-2025

SWIN Type

Options for the Surface WindowType field.

NameDescription
SWIN::HOSTDefault to the standard hosted window mode with full titlebar, borders and taskbar representation.
SWIN::ICON_TRAYCreate a borderless (custom) window with icon tray representation.
SWIN::NONECreate a borderless (custom) window with no UI representation.
SWIN::TASKBARCreate a borderless (custom) window with taskbar representation.
Display module documentation © Paul Manias 2003-2025

WH Type

Events for WindowHook()

NameDescription
WH::CLOSE
Display module documentation © Paul Manias 2003-2025

BitmapSurface Structure

FieldTypeDescription
DataAPTRPointer to the bitmap graphics data.
WidthWORDPixel width of the bitmap.
HeightWORDPixel height of the bitmap.
LineWidthLONGThe distance between bitmap lines, measured in bytes.
BitsPerPixelUBYTEThe number of bits per pixel (8, 15, 16, 24, 32).
BytesPerPixelUBYTEThe number of bytes per pixel (1, 2, 3, 4).
OpacityUBYTEOpacity level of the source if CSRF::TRANSLUCENT is used.
VersionUBYTEVersion of this structure.
ColourLONGColour index to use if CSRF::TRANSPARENT is used.
Clipstruct ClipRectangleA clipping rectangle will restrict drawing operations to this region if CSRF::CLIP is used.
XOffsetWORDOffset all X coordinate references by the given value.
YOffsetWORDOffset all Y coordinate references by the given value.
Formatstruct ColourFormatThe colour format of this bitmap's pixels, or alternatively use CSRF::DEFAULT_FORMAT.
Display module documentation © Paul Manias 2003-2025

ColourFormat Structure

FieldTypeDescription
RedShiftUBYTERight shift value for red (15/16 bit formats only)
GreenShiftUBYTERight shift value for green
BlueShiftUBYTERight shift value for blue
AlphaShiftUBYTERight shift value for alpha
RedMaskUBYTEUnshifted mask value for red (ranges from 0x00 to 0xff)
GreenMaskUBYTEUnshifted mask value for green
BlueMaskUBYTEUnshifted mask value for blue
AlphaMaskUBYTEUnshifted mask value for alpha
RedPosUBYTELeft shift/positional value for red
GreenPosUBYTELeft shift/positional value for green
BluePosUBYTELeft shift/positional value for blue
AlphaPosUBYTELeft shift/positional value for alpha
BitsPerPixelUBYTENumber of bits per pixel for this format.
Display module documentation © Paul Manias 2003-2025

CursorInfo Structure

FieldTypeDescription
WidthLONGMaximum cursor width for custom cursors
HeightLONGMaximum cursor height for custom cursors
FlagsLONGCurrently unused
BitsPerPixelWORDPreferred bits-per-pixel setting for custom cursors
Display module documentation © Paul Manias 2003-2025

DisplayInfo Structure

FieldTypeDescription
DisplayOBJECTIDObject ID related to the display
FlagsSCRDisplay flags
WidthWORDPixel width of the display
HeightWORDPixel height of the display
BitsPerPixelWORDBits per pixel
BytesPerPixelWORDBytes per pixel
AccelFlagsACFFlags describing supported hardware features.
AmtColoursLONGTotal number of supported colours.
PixelFormatstruct PixelFormatThe colour format to use for each pixel.
MinRefreshFLOATMinimum refresh rate
MaxRefreshFLOATMaximum refresh rate
RefreshRateFLOATRecommended refresh rate
IndexLONGDisplay mode ID (internal)
HDensityLONGHorizontal pixel density per inch.
VDensityLONGVertical pixel density per inch.
Display module documentation © Paul Manias 2003-2025

InputEvent Structure

FieldTypeDescription
Nextconst struct InputEvent *Next event in the chain
ValueDOUBLEThe value associated with the Type
TimestampLARGEPreciseTime() of the recorded input
RecipientIDOBJECTIDSurface that the input message is being conveyed to
OverIDOBJECTIDSurface that is directly under the mouse pointer at the time of the event
AbsXDOUBLEAbsolute horizontal position of mouse cursor (relative to the top left of the display)
AbsYDOUBLEAbsolute vertical position of mouse cursor (relative to the top left of the display)
XDOUBLEHorizontal position relative to the surface that the pointer is over - unless a mouse button is held or pointer is anchored - then the coordinates are relative to the click-held surface
YDOUBLEVertical position relative to the surface that the pointer is over - unless a mouse button is held or pointer is anchored - then the coordinates are relative to the click-held surface
DeviceIDOBJECTIDThe hardware device that this event originated from
TypeJETJET constant that describes the event
FlagsJTYPEBroad descriptors for the given Type (see JTYPE flags). Automatically defined when delivered to the pointer object
MaskJTYPEMask to use for checking against subscribers
Display module documentation © Paul Manias 2003-2025

PixelFormat Structure

Carries instructions to pack or unpack RGBA colours.

FieldTypeDescription
RedShiftUBYTERight shift value
GreenShiftUBYTEGreen shift value
BlueShiftUBYTEBlue shift value
AlphaShiftUBYTEAlpha shift value
RedMaskUBYTEThe unshifted red mask value (ranges from 0x00 to 0xff)
GreenMaskUBYTEThe unshifted green mask value (ranges from 0x00 to 0xff)
BlueMaskUBYTEThe unshifted blue mask value (ranges from 0x00 to 0xff)
AlphaMaskUBYTEThe unshifted alpha mask value (ranges from 0x00 to 0xff)
RedPosUBYTELeft shift/positional value for red
GreenPosUBYTELeft shift/positional value for green
BluePosUBYTELeft shift/positional value for blue
AlphaPosUBYTELeft shift/positional value for alpha
Display module documentation © Paul Manias 2003-2025

SurfaceCoords Structure

FieldTypeDescription
XLONGHorizontal coordinate
YLONGVertical coordinate
WidthLONGWidth
HeightLONGHeight
AbsXLONGAbsolute X
AbsYLONGAbsolute Y
Display module documentation © Paul Manias 2003-2025

SurfaceInfo Structure

FieldTypeDescription
DataAPTRBitmap data memory ID
ParentIDOBJECTIDObject that contains the surface area
BitmapIDOBJECTIDSurface bitmap buffer
DisplayIDOBJECTIDRefers to the display if this object is at root level
FlagsRNFSurface flags
XLONGHorizontal coordinate
YLONGVertical coordinate
WidthLONGWidth of the surface area
HeightLONGHeight of the surface area
AbsXLONGAbsolute X coordinate
AbsYLONGAbsolute Y coordinate
LevelWORDBranch level within the tree
BitsPerPixelBYTEBits per pixel of the bitmap
BytesPerPixelBYTEBytes per pixel of the bitmap
LineWidthLONGLine width of the bitmap, in bytes
Display module documentation © Paul Manias 2003-2025

xrMode Structure

Display mode.

FieldTypeDescription
WidthLONGHorizontal
HeightLONGVertical
DepthLONGbit depth
Display module documentation © Paul Manias 2003-2025