ComposeBitmap Method
The ComposeBitmap method collates a passed array of bitmap objects (elements) into a single bitmap object (the host bitmap itself).
This method is used to compose compound bitmaps for use by OpenROAD, particularly for bitmapped background fields (where corners and outlines need to be preserved, whatever the field size), and for fields that display sprites (active or mobile icons within the field area).
The resulting bitmap is laid out in a format that enables rapid runtime “unpacking” and display:
• The maximum size of a composed bitmap is 2400 by 2400 pixels.
• Up to 64 alternative images may be stacked (vertically) in a single bitmap object. They can be of different width or height.
• If the bitmap also contains sprite source icons, these are packed into the “last image.” Up to 256 sprite icons may be packed here, in two dimensions; they can be of different width or height.
• Images may or may not be sectored; if they are, ComposeBitmap expects them to be composed from nine-sector bitmaps that will pack exactly as 3 columns and 3 rows.
An individual ComposeBitmap call collates a single set of bitmaps of a single type. A typical approach therefore is to first apply ComposeBitmap to the set of sprite source icons that the bitmap will contain, to create the “last image,” then add this to the set of alternative image bitmaps (as the last entry), and apply ComposeBitmap to that collection, with the hasicons parameter set to TRUE.
A composed bitmap can be simply decomposed and recomposed using the Elements (see
Elements Method) and ComposeBitmap methods, if elements need to be added, removed or reordered.
If the BitmapObject is attached to a FormField or a stored TaggedValue Item, using this in your program during development may change your frame's source definition. See BitmapObject Attributes and Methods Affecting the Frame Source (see
BitmapObject Class).
This method has the following syntax:
BitmapObject = BitmapObject.ComposeBitmap(elementtype = integer,
elements = array of BitmapObject[, width = integer]
[, dividertype = integer][, hasicons = integer])
This method has the following parameters:
elementtype
(Required) Specifies the type of element being collated. Valid values are:
BE_IMAGE
Specifies that the elements are to be treated as a set of alternative images.
The method will separate the images by horizontal dividers.
BE_SECTOR
Specifies that the elements are to be treated as a set of sectors. There must be exactly 9 of these to compose a sectored image suitable for use in BDP_BORDEREDxxx backgrounds.
The method will separate the 9 sectors by two horizontal dividers and two vertical dividers.
BE_ICON
Specifies that the elements are to be treated as sprite source icons.
The method will separate the icons into rows separated by horizontal dividers. The images can be of varying sizes; on each row they will pack to occupy the defined width as far as possible; unfilled space is set to the divider color.
elements
(Required) Specifies the array of bitmap objects to be collated into a single bitmap.
width
Specifies the width of the bitmap object being composed. This is only relevant for BE_ICON; the dimensions of the composed bitmap for BE_IMAGE and BE_SECTOR are dictated by the elements provided:
• The widest of the images collated for BE_IMAGE will set the bitmap width.
• The images collated for BE_SECTOR (three to a row, three to a column) should have equal height for any given row, and equal width for any given column.
Default: The width of the widest supplied bitmap
dividertype
Specifies the type of divider used to characterize image sectors.
This applies only to BE_SECTOR. Valid values are:
BE_NODIVIDER
No divider is applied between the sectors. This may be the case if the bitmap is relying on its cornerradius setting to define the sectors for bordering purposes at runtime.
BE_FULLDIVIDER
The 4 dividers run the full width or height of the BitmapObject image.
Default: BE_FULLDIVIDER
Technical Information about Dividers:
ComposeBitmap uses dividers to separate areas of a compound bitmap. It is not typically necessary to know the colors used for these; the following information will assist developers who choose to use third-party tools to create bitmaps suitable for OpenROAD use.
• Sector dividers are RGB(254,0,255).
• Sprite source icon dividers are RGB(254,0,255).
• Image dividers are RGB(253,0,255), except where there is a source-icon-containing “last image”: this is separated from the previous image by a divider colored RGB(252,0,255).
• Image bitmaps may differ in width: where they do, any empty space is filled with RGB(253,0,255).
• Source icon bitmaps may differ in width and height: where they do, any empty space is filled with RGB(254,0,255).
hasicons
Specifies whether the last image in a BE_IMAGE ComposeBitmap call is actually a set of source icons for use with the bitmap.
Default: FALSE
This method returns the bitmap itself, changed to contain the collated elements. If unsuccessful, the errorstatus of the bitmap object is set to a non-zero error code. Descriptions of system constant values and their numeric equivalents are listed in
Error Codes.