Base Modules

The following modules are included in the standard distribution and can be loaded at run-time with mod.load() in Fluid or LoadModule() in C/C++.

Use the navigation bar on the right to peruse the available functionality of the selected module.

Beginners should start with the Core module, which includes the bulk of Parasol's functionality.

• Audio
• Core
• Display
• Fluid
• Font
• Network
• Vector

AccessPointer()

Returns a lock on the default pointer object.

Description

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.

Description

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.

Description

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.

Description

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

Description

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.

Description

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.

Description

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.

Description

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.

ExposeSurface()

Exposes the content of a surface to the display.

Description

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

FlipBitmap()

Flips a bitmap around its horizontal or vertical axis.

Description

The FlipBitmap() function is used to flip bitmap images on their horizontal or vertical axis. The amount of time required to flip a bitmap is dependent on the area of the bitmap you are trying to flip over and its total number of colours.

GetColourFormat()

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

Description

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.

Description

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.

Description

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.

Description

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 type of display supported.

Description

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

Result

Returns an integer indicating the display type.

GetInputTypeName()

Returns the string name for an input type.

Description

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

Description

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.

Description

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.

Description

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.

Description

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 without having to access it directly.

Description

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.

Description

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.

Description

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

LockBitmap()

Returns a bitmap that represents the video area covered by the surface object.

Description

Use the LockBitmap() function to gain direct access to the bitmap information of a surface object. Because the layering buffer will be inaccessible to the UI whilst you retain the lock, you must keep your access time to an absolute minimum or desktop performance may suffer.

Repeated calls to this function will nest. To release a surface bitmap, call the UnlockBitmap() function.

Error Codes

LockCursor()

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

Description

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.

Description

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.

Description

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.

Description

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.

Description

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.

Description

ScaleToDPI() is a convenience function for scaling any value to the active display's current DPI setting. The value that you provide must be fixed in relation to the system wide default of 96 DPI. If the display's DPI varies differs to that, your 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, your value will be returned unscaled.

Result

The scaled value is returned.

SetClipRegion()

Sets a clipping region for a bitmap object.

Description

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.

SetCursor()

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

Description

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:

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.

Description

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.

Description

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.

Description

For internal usage only.

Error Codes

SetModalSurface()

Enables a modal surface for the current task.

Description

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.

Description

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

SubscribeInput()

Subscribe to incoming input messages for any active surface object.

Description

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:

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.

Description

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.

UnlockBitmap()

Unlocks any earlier call to gfx::LockBitmap().

Description

Call the UnlockBitmap() function to release a surface object from earlier calls to LockBitmap().

Error Codes

UnlockCursor()

Undoes an earlier call to LockCursor()

Description

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.

Description

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.

Description

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

Error Codes

ACF Type

Acceleration flags for GetDisplayInfo().

ALIGN Type

Universal values for alignment of graphics and text

BAF Type

Instructions for basic graphics operations.

BDF Type

CopySurface() flags

BMF Type

Bitmap flags

BMP Type

Bitmap types

CEF Type

CLIPTYPE Type

Clipboard types

CPF Type

Clipboard flags

CRF Type

Flags for the SetCursor() function.

CS Type

Colour space options.

CSRF Type

Flags for CopySurface().

CT Type

DMF Type

DPMS Type

Possible modes for the Display class' PowerMode field.

DRAG Type

DSF Type

DT Type

Flags for GetDisplayType().

EXF Type

Optional flags for the ExposeSurface() function.

FLIP Type

Flags for the bitmap Flip method.

GMF Type

Flags for gamma operations.

HOST Type

IRF Type

Flags for RedrawSurface().

JET Type

JET constants are documented in GetInputEvent()

JTYPE Type

JTYPE flags are used to categorise input types.

LVF Type

drwLockBitmap() result flags

MON Type

Flags for the Display class SetMonitor() method.

PF Type

Flags for the Pointer class.

PTC Type

Predefined cursor styles

RNF Type

Switches for the Surface class' Flags field.

RT Type

SCR Type

Display flags.

SWIN Type

Options for the Surface WindowType field.

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.