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 | BAF | BDF | CRF | CSRF | EXF | HOST | JET | JTYPE | PTC | RNF | SCR | WH

AccessPointer()

Returns a lock on the default pointer object.

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.

CheckIfChild()

Check if a surface is the child of another surface.

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

CopyArea()

Copies a rectangular area from one bitmap to another.

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

CopyRawBitmap()

Copies graphics data from an arbitrary surface to a bitmap.

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

CopySurface()

Copies surface graphics data into any bitmap object

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

DrawPixel()

Draws a single pixel to a bitmap.

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.

DrawRGBPixel()

Draws a 24 bit pixel to a Bitmap.

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.

DrawRectangle()

Draws rectangles, both filled and unfilled.

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. Alpha blending is not supported.

ExposeSurface()

Exposes the content of a surface to the display.

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

GetColourFormat()

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

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)

GetCursorInfo()

Retrieves graphics information from the active mouse cursor.

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

GetCursorPos()

Returns the coordinates of the UI pointer.

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

GetDisplayInfo()

Retrieves display information.

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

GetDisplayType()

Returns the selected display driver's backend type.

This function reports the backend identity of the driver selected during Display module initialisation. Explicit and automatic driver selection therefore return the same type when they resolve to the same backend. Current values are:

Result

Returns an integer indicating the display type.

GetInputTypeName()

Returns the string name for an input type.

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.

GetModalSurface()

Returns the current modal surface (if defined).

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.

GetRelativeCursorPos()

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

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

GetSurfaceCoords()

Returns the dimensions of a surface.

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

GetSurfaceFlags()

Retrieves the Flags field from a Surface.

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

GetSurfaceInfo()

Retrieves display information for any surface object, whilst avoiding direct access.

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

GetUserFocus()

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

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.

GetVisibleArea()

Returns the visible region of a 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

LockCursor()

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

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

ReadPixel()

Reads a pixel's colour from the target bitmap.

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.

ReadRGBPixel()

Reads a pixel's colour from the target bitmap.

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.

Resample()

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

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

RestoreCursor()

Returns the pointer image to its original state.

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

ScaleToDPI()

Scales a value to the active display's DPI.

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.

SetClipRegion()

Sets a clipping region for a bitmap object.

The SetClipRegion() method is used to manage the clipping region assigned to a bitmap object. The ClipLeft, ClipTop, ClipRight and ClipBottom fields in the target Bitmap will be updated to reflect the area covered by the provided parameter values.

SetCursor()

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

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 IDs and their equivalent names are listed in the documentation for the Pointer⇒CursorID 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:

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

SetCursorPos()

Changes the position of the pointer cursor.

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

Error Codes

SetCustomCursor()

Sets the cursor to a customised bitmap image.

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

SetHostOption()

Alter options associated with the host display system.

For internal usage only.

Error Codes

SetModalSurface()

Enables a modal surface for the current task.

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).

StartCursorDrag()

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

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 character 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

SubscribeInput()

Subscribe to incoming input messages for any active surface object.

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, int 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:

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.

Error Codes

Sync()

Waits for the completion of all active bitmap operations.

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.

UnlockCursor()

Undoes an earlier call to LockCursor()

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

Error Codes

UnsubscribeInput()

Removes an input subscription.

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

Error Codes

WindowHook()

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

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

Error Codes

ACF Type

Acceleration flags for GetDisplayInfo().

BAF Type

Instructions for basic graphics operations.

BDF Type

CopySurface() flags

CRF Type

Flags for the SetCursor() function.

CSRF Type

Flags for CopySurface().

EXF Type

Optional flags for the ExposeSurface() function.

HOST Type

JET Type

JET constants are documented in GetInputEvent()

JTYPE Type

JTYPE flags are used to categorise input types

PTC Type

Predefined cursor styles

RNF Type

Switches for the Surface class' Flags field.

SCR Type

Display flags.

WH Type

Events for WindowHook()

BitmapSurface Structure

ColourFormat Structure

CursorInfo Structure

DisplayInfo Structure

InputEvent Structure

PixelFormat Structure

Carries instructions to pack or unpack RGBA colours.

SurfaceCoords Structure

SurfaceInfo Structure

xrMode Structure

Display mode.