Render

Version:1.0
Status:Stable
Date:February 2004
Author:Rocklyte Systems
Copyright:  Rocklyte Systems (c) 2003-2004. All rights reserved.



Function Index
AccessDrawableSurface  Provides free access to bitmap data without performing any locks.
BlitDrawable  Copies drawable graphics data into any Bitmap object.
ExposeDrawable  Exposes any drawable region for which you have an ID.
GetRenderInfo  Retrieves display information for any render object without having to access it directly.
GetUserFocus  Returns the ID of the drawable that currently has the user's focus.
LockDrawableBitmap  Returns a bitmap that represents the video area covered by the render object.
ReleaseDrawableSurface  Releases any earlier call to AccessDrawableSurface().
SetDrawableRegion  Writes clipping information for a rendered area to a region object.
UnlockDrawableBitmap  Unlocks any earlier call to LockDrawableBitmap().

 

Function:AccessDrawableSurface()
Short:Provides free access to bitmap data without performing any locks.
Synopsis:ERROR AccessDrawableSurface(OBJECTID RenderID, struct BitmapSurface *Surface, LONG Size)
Arguments:
RenderID  Reference to the drawable ID that you want to access.
Surface  Pointer to a BitmapSurface structure that will receive the surface information.
Size  Size of the BitmapSurface structure.

The AccessDrawableSurface() function is used to gain free access to the bitmap data of any given render object. 'Free access' means that the graphics data will not be locked or synchronised while you have access to it, effectively allowing other tasks to also use the bitmap at the same time. This can be extremely useful for unsynchronised, high speed read/write access. However, the lack of synchronisation means that if multiple tasks are using the bitmap at once, you may encounter inconsistent results.

The surface information is returned in a BitmapSurface structure. More information on this structure is available in the documentation for the Bitmap module's BlitSurface() function.

After you have finished with the bitmap, you must match this function with a call to ReleaseDrawableSurface. Multiple calls to AccessDrawableSurface will nest. Never re-use the BitmapSurface structure when making calls to this function.

If you would like your bitmap access to be synchronised, use the LockDrawableBitmap() function instead.

Result
ERR_Okay  Access successful.
ERR_Args  Invalid arguments were supplied.
ERR_Search  The supplied RenderID did not refer to a recognised render object.
ERR_AccessMemory  Failed to access the internal renderlist memory structure, or the bitmap data was not accessible.

Function:BlitDrawable()
Short:Copies drawable graphics data into any Bitmap object.
Synopsis:ERROR BlitDrawable(OBJECTID RenderID, struct Bitmap *Bitmap, LONG Flags, LONG XCoord, LONG YCoord, LONG Width, LONG Height, LONG XDest, LONG YDest)
Arguments:
RenderID  The ID of the render object that you want to blit from.
Flags  Optional flags.
XCoord  The horizontal source coordinate.
YCoord  The vertical source coordinate.
Width  The width of the graphic that you want to copy.
Height  The height of the graphic that you want to copy.
XDest  The horizontal destination coordinate.
YDest  The vertical destination coordinate.
Bitmap  Pointer to the destination Bitmap object.

This function will copy the graphics data from any drawable object into a Bitmap of your choosing. This is the fastest and most convenient way to get graphics information out of any drawable. Because Pandora uses graphics buffering, you are also guaranteed that the resulting graphics will not be obscured by any overlapping drawables that are on the display.

In the event that the owner of the drawable is drawing to the graphics buffer at the time that you call this function, the results may be slightly out of sync. If this could be a problem, set the BDF_SYNC option in the Flags parameter. Keep in mind that syncing has the negative side effect of having to wait for the other task to complete its draw process, which can potentially result in time lags.

Result
ERR_Okay  The blit was successful.
ERR_Args  Invalid arguments were specified.
ERR_Search  The supplied RenderID did not refer to a recognised render object.
ERR_AccessMemory  Failed to access the internal renderlist memory structure.

Function:ExposeDrawable()
Short:Exposes any drawable region for which you have an ID.
Synopsis:ERROR ExposeDrawable(OBJECTID DrawableID, LONG XCoord, LONG YCoord, LONG Width, LONG Height, LONG Flags)
Arguments:
DrawableID  The ID of the render object that you want to expose.
XCoord  The horizontal coordinate of the area to expose.
YCoord  The vertical coordinate of the area to expose.
Width  The width of the expose area.
Height  The height of the expose area.
Flags  Optional flags - EXF_CHILDREN will expose all intersecting child regions.

This expose routine will expose everything within a drawable area. This will include all child drawables that intersect with the region being exposed if you set the ExposeChildren option.

Result
ERR_Okay  The function completed successfully.
ERR_Search  The RenderID does not refer to an existing drawable object.
ERR_AccessMemory  The internal renderlist could not be accessed.

Function:GetRenderInfo()
Short:Retrieves display information for any render object without having to access it directly.
Synopsis:ERROR GetRenderInfo(OBJECTID RenderID, struct RenderInfo *Info, LONG InfoSize)
Arguments:
RenderID  The unqiue ID of the render object that you want information on.
Info  Pointer to a RenderInfo structure that will be filled out by this function.
InfoSize  Must be set to 'sizeof(struct RenderInfo)'.

The GetRenderInfo function is used for quickly retrieving basic information on render objects without having to access them through the slower AccessObject() function. You need to supply this function with the ID of the render object that you want to analyse and provide a return structure for the resulting feedback.

The RenderInfo structure contains the following fields of information:

   OBJECTID ParentID   The object that contains the render area.
   OBJECTID BitmapID   Drawable bitmap buffer.
   OBJECTID FocusID    Indicates the focus route.
   OBJECTID ScreenID   If set, indicates the screen owned by the drawable.
   MEMORYID DataMID    Memory ID that refers to the bitmap data.
   LONG Flags          Render flags (RNF_VISIBLE etc).
   WORD XCoord         Horizontal coordianate.
   WORD YCoord         Vertical coordinate.
   WORD Width          The width of the drawable area.
   WORD Height         The height of the drawable area.
   WORD AbsX           Absolute X coordinate.
   WORD AbsY           Absolute Y coordinate.
   WORD Level          The drawable's level within the render tree.
   WORD TopLimit       Top limit (for restricting movement).
   WORD LeftLimit      Left limit.
   WORD RightLimit     Right limit.
   WORD BottomLimit    Bottom limit.
   LONG LineWidth      The bytewidth of each line in the bitmap data.
   BYTE BytesPerPixel  The number of bytes per pixel in the bitmap data.
   BYTE BitsPerPixel   The number of bits per pixel in the bitmap data.
Result
ERR_Okay  The render information was successfully retrieved.
ERR_Args  Invalid arguments were specified.
ERR_Search  The supplied RenderID did not refer to a recognised render object.
ERR_AccessMemory  Failed to access the internal renderlist memory structure.

Function:GetUserFocus()
Short:Returns the ID of the drawable that currently has the user's focus.
Synopsis:OBJECTID GetUserFocus(void)

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

Result
Returns the ID of the render object that has the user focus, or NULL on failure.


Function:LockDrawableBitmap()
Short:Returns a bitmap that represents the video area covered by the render object.
Synopsis:ERROR LockDrawableBitmap(OBJECTID RenderID, struct Bitmap **Bitmap, LONG *Info)
Arguments:
RenderID  Object ID of the render object that you want to lock.
Bitmap  The resulting bitmap will be returned in this parameter.
Info  Special flags may be returned in this parameter. If LVF_EXPOSECHANGES is set, you must expose your changes if you want to see them on the display.

Use the LockDrawableBitmap() function when you would like direct access to the bitmap information of a render object. Full access to the graphics data will be granted through the Bitmap object that is returned by this function. As the rendering buffer will be locked from the system whilst you retain access, you must keep your access time to an absolute minimum or desktop performance may suffer.

Repeated calls to LockDrawableBitmap() will nest. To release a drawable bitmap, call the UnlockDrawableBitmap() function.

If you require long-term access to the graphics data, consider using the AccessDrawableSurface() function instead.

Result
ERR_Okay  The drawable area was successfully locked.
ERR_Args  Invalid arguments were specified.

Function:ReleaseDrawableSurface()
Short:Releases any earlier call to AccessDrawableSurface().
Synopsis:ERROR ReleaseDrawableSurface(OBJECTID RenderID, struct BitmapSurface *Surface)
Arguments:
RenderID  Reference to the render object that you are releasing.
Surface  Pointer to the BitmapSurface structure being released.

This function will release bitmap data that has been acquired from previous calls to AccessDrawableSurface().

Result
ERR_Okay  Release successful.
ERR_Args  Invalid arguments were supplied.

Function:SetDrawableRegion()
Short:Writes clipping information for a rendered area to a region object.
Synopsis:ERROR SetDrawableRegion(OBJECTID RenderID, *Region)
Arguments:
RenderID  The ID of the render object that you want to scan.
Region  Pointer to a region object that will receive the clipping information.

This function is used in conjunction with the Region class to define the available drawing space within a rendered object. This function will scan the content of the render object referred to by RenderID, then produces a list of obscuring regions and sets those against the Region object. Overlapping parent regions that intersect with the buffered drawing space will also be included in the region list.

This function is intended for use after calling the LockDrawableBitmap() function, as this is the only way to get direct access to the surface of a rendered object. You will need to use the region information in conjunction with a Pen object in order to draw clipped graphics to the bitmap surface.


Function:UnlockDrawableBitmap()
Short:Unlocks any earlier call to LockDrawableBitmap().
Synopsis:ERROR UnlockDrawableBitmap(OBJECTID RenderID, struct Bitmap *Bitmap)
Arguments:
RenderID  The ID of the render object that you are releasing.
Bitmap  Pointer to the Bitmap structure returned earlier by LockDrawableBitmap().

Call the UnlockDrawableBitmap() function to release a render object from earlier calls to LockDrawableBitmap().

Result
ERR_Okay  The bitmap has been unlocked successfully.
ERR_Args  Invalid arguments were specified.