Picture Datatype
Jump to navigation
Jump to search
TABLE OF CONTENTS
picture.datatype picture.datatype/PDTM_QUANTIZEPIXELARRAY picture.datatype/PDTM_SCALE picture.datatype/PDTM_SCALEPIXELARRAY picture_dtc/OM_DISPOSE picture_dtc/OM_GET picture_dtc/OM_NEW picture_dtc/OM_SET
picture.datatype picture.datatype
NAME picture.datatype -- the root datatype class for pictures.
FUNCTION The picture.datatype is the super-class for any picture related classes.
METHODS OM_NEW -- Create and initialise a new picture object.
OM_GET -- Obtain the value of an attribute.
OM_SET -- Set the value(s) of multiple attributes.
OM_UPDATE -- Update the value(s) of multiple attributes.
OM_DISPOSE -- Dispose of a picture object.
GM_LAYOUT -- Layout (remap) the object and notify the
application of the title and size.
GM_HITTEST -- Determine if the object has been hit by the mouse.
GM_GOACTIVE -- Tell the object to become active.
GM_HANDLEINPUT -- Handle any input directed at the object.
GM_RENDER -- Cause the graphics to render.
DTM_PROCLAYOUT -- Layout (remap) the picture on the current
application's process.
DTM_FRAMEBOX -- Obtain the display environment that the picture
requires for display purposes.
DTM_SELECT -- Select a rectangular region of the picture.
DTM_CLEARSELECTED -- Deselect the selected region of the picture.
DTM_COPY -- Copy the selected area of the picture to the
clipboard as ILBM format. If no area has been selected, the entire
picture is copied.
DTM_PRINT -- Print the selected area of the picture. If no
area has been selected, the entire picture is printed.
DTM_WRITE -- Write the selected area of the picture to a file
as ILBM format. If no area has been selected, then the entire picture
is written.
DTM_DRAW -- Causes the picture to be drawn. Requires that the
function ObtainDTDrawInfo() be called before this method to obtain
a lock on the object and that ReleaseDTDrawInfo() be called after
to release that lock.
PDTM_READPIXELARRAY -- Transfer pixel data OUT of the picture. Requires
that PDTA_DestMode is PMODE_V43, as described below.
PDTM_WRITEPIXELARRAY -- Transfer pixel data INTO the picture. Requires
that PDTA_SourceMode is PMODE_V43, as described below.
PDTM_SCALE -- Scale the pixel data to a new size. Scaling is
only possible before the first GM_LAYOUT (remap) has been performed.
PDTM_OBTAINPIXELARRAY -- Obtain a description of the internal pixel data
buffer in order to allow direct access. MAY be used as an alternative
to PDTM_READPIXELARRAY and PDTM_WRITEPIXELARRAY. Requires that
PDTA_DestMode is PMODE_V43 as described below. Returns non-zero on
success, filling the specified pdtBlitPixelArray structure with the
format of the internal buffer, with pbpa_PixelData also being non-NULL.
Ensure that pbpa_PixelArrayMod is honoured when stepping through rows.
If pbpa_PixelData is NULL, of pbpa_PixelFormat does not match your
requirements, use PDTM_READPIXELARRAY or PDTM_WRITEPIXELARRAY.
In OM_NEW of subclasses, this method SHOULD NOT be called until after
DTA_NominalHoriz / DTA_NominalVert have been specified and
PDTA_SourceMode have been set to PMODE_V43.
PDTM_SCALEPIXELARRAY -- Combines the PDTM_READPIXELARRAY and PDTM_SCALE
methods to facilitate the reading of a scaled region of the picture
without requiring the remapping process.
Requires that PDTA_DestMode is PMODE_V43.
PDTM_QUANTIZEPIXELARRAY -- Quantize the source palette into a smaller set
of colours using a specified algoritm for the purposes of remapping.
Requires that PDTA_DestMode is PMODE_V43.
TAGS
OBP_Precision (uint32)
The precision to use when obtaining pens during remapping.
See the PRECISION_#? defines in <graphics/view.h>
Defaults to PRECISION_IMAGE.
Applicability is (I)
PDTA_ModeID (uint32)
Get and set the id of the graphics mode for the picture.
See <graphics/modeid.h> for more information.
Defaults to 0.
Applicability is (ISG)
PDTA_BitMapHeader (struct BitMapHeader *)
Gets the basic dimensions of the picture. The BitMapHeader structure
is defined in <datatypes/pictureclass.h>.
Applicability is (G)
PDTA_SourceMode (int32)
Used by subclass authors, this tag determines whether the picture
object expects a BitMap as the input parameter (PMODE_V42) or MAY
accept PDTA_WRITEPIXELARRAY messages or PDTM_OBTAINPIXELARRAY access
instead (PMODE_V43).
Defaults to PMODE_V42.
Applicability is (ISG)
PDTA_DestMode (int32)
Used by application authors, this tag determines whether the picture
object will return only a standard format BitMap (PMODE_V42) up to
8-bit planar, or whether it will return a BitMap about whose memory
layout the caller must not speculate or assume.
If set to PMODE_V43, you SHOULD NOT examine or assume anything about
the contents of the resulting BitMap.
Defaults to PMODE_V42.
Applicability is (ISG)
PDTA_BitMap (struct BitMap *)
The pointer to the source bitmap. If PDTA_SourceMode = PMODE_V42,
setting this BitMap will result in it being freed in OM_DISPOSE
and may ONLY be up to 8-bit per pixel (planar).
If PDTA_SourceMode = PMODE_V43, the BitMap is COPIED into the
internal pixel buffer and MAY be any supported bit-depth. The
caller is responsible for freeing the BitMap it provides.
Where PDTA_SourceMode is PMODE_V43 and the pixel data has been
written to the internal buffer, the result of OM_GET for this
attribute will be a direct BitMap representation of the pixel
buffer.
Applicability is (ISG)
PDTA_ClassBitMap (struct BitMap *)
A pointer to a source BitMap allocated by a subclass (for example,
the ilbm.datatype) which imported the picture. The picture.dataype
will never free this BitMap and the subclass is responsible for
doing so.
Applicability is (ISG)
PDTA_DestBitMap (struct BitMap *)
A pointer to the remapped BitMap after the layout / remap process
has occurred.
Applicability is (G)
PDTA_ColorRegisters (struct ColorRegister *)
The colour table of the source picture. The contents of this
table should match the corresponding entries in PDTA_CRegs.
Applicability is (IG)
PDTA_CRegs (uint32 *)
The colour table of the source picture, containing three
long word triplets per entry representing the RGB components of the
colour. See SetRGB32() and SetRGB32CM() for more information.
Applicability is (IG)
PDTA_GRegs (uint32 *)
The colour table of the remapped picture, containing three
long word triplets per entry representing the RGB components of the
colour. See SetRGB32() and SetRGB32CM() for more information.
Applicability is (G)
PDTA_ColorTable (uint8 *)
An array of pen values representing shared pens allocated during
the remapping process.
Applicability is (G)
PDTA_ColorTable2 (uint8 *)
An array of pen values representing shared pens allocated during
the remapping process. For most use cases, this table will contain
the same values as PDTA_ColoraTable, but in other cases some of the
colours in this table MAY match the original colour palette better.
The picture.datatype uses the two tables during remapping, alternating
for each pixel.
Applicability is (G)
PDTA_AllocatedPens (uint8 *)
An array of pens allocated during the remapping process. Each entry
represents a pen allocated for a colour in the remapped colour palette.
You may receive a NULL pointer as result where PDTA_Allocated or
PDTA_NumAlloc is 0 (zero).
Note that older documentation states that the entry corresponds to the
same indexed entry in the remapped colour palette, which isn't strictly
true (see NOTES below).
Applicability is (G)
PDTA_Allocated (uint32)
Gets the number of pens allocated and present within the associated
PDTA_AllocatedPens array. This will typically be the same as the
value of PDTA_NumAlloc but will be zero (0) where no pens were
allocated on a screen. In this context, 'allocated' refers to the
colours allocated via graphics.library/ObtainBestPen().
Applicability is (G)
PDTA_NumColors (uint32)
The number of colours in the palette (PDTA_CRegs) for the source
picture or PDTA_BitMap.
Applicability is (ISG)
PDTA_NumAlloc (uint32)
The number of colours allocated to the palette (PDTA_GRegs) for the
remapped BitMap (PDTA_DestBitMap).
Applicability is (G)
PDTA_Remap (BOOL)
Indicates whether the picture should be remapped or not during the
layout process. When not remapped, the bitmap (PDTA_DestBitMap)
produces will be (almost) identical to the source BitMap.
Defaults to TRUE.
Applicability is (I)
PDTA_Screen (struct Screen *)
A pointer to a Screen structure representing the screen to remap
the picture to. Only used if the picture object is not added to
a Window; primarily used when calling DTM_OBTAINDRAWINFO in order
to remap the picture.
Defaults to NULL.
Applicability is (IS)
PDTA_FreeSourceBitMap (BOOL)
Indicates whether the source bitmap should be freed immediately
after the layout (remapping) method has finished.
When PDTA_SourceMode = PMODE_V42, this will free the BitMap
specified in PDTA_BitMap; for PDTA_SourceMode = PMODE_V43, this
will free the internal BitMap representing the pixel buffer.
Defaults to FALSE.
Applicability is (ISG)
PDTA_Grab (Point *)
A pointer to a Point structure that specifies the grab point of
the picture.
Defaults to (0,0)
Applicability is (ISG)
PDTA_SparseTable (uint8 *)
An array of pen numbers indicating which colours should be used when
remapping the picture. This array MUST contain at least as many
entries as indicated by PDTA_NumSparse. These are the pre-allocated
pens to be used as a replacement to quantization; the remapped colour
registers in PDTA_GRegs will be populated with the pen RGB colours.
Defaults to NULL.
Applicability is (I).
PDTA_NumSparse (uint16)
The number of pens in the sparse colour table PDTA_SparseTable.
Defaults to 0.
Applicability is (I)
PDTA_UseFriendBitMap (BOOL)
If set to TRUE, any BitMap allocations will be performed using a
'friend' BitMap, typically from the Screen to which the picture
is being remapped. See graphics.library/AllocBitMap().
Defaults to TRUE.
Applicability is (ISG)
PDTA_AlphaChannel (BOOL)
Analogous to mskHasAlpha in the bmh_Masking field of the BitMapHeader.
Is set to TRUE, indicates that the source picture has an alpha channel.
Defaults to FALSE.
Applicability is (IG)
PDTA_MaskPlane (PLANEPTR)
A pointer to a bitplane suitable for use with a call to the function
graphics.library/BltMaskBitMapRastPort() or NULL if the picture has
no transparent colours.
Defaults to NULL.
Applicability is (G)
PDTA_PromoteMask (BOOL)
If a colour-mapped (up to 8-bit) picture with a transparent colour
needs to be "promoted" to a true-colour format, setting this to TRUE
allows the PDTA_MaskPlane to be converted and carried over into the
alpha channel of the destination BitMap.
Defaults to FALSE.
Applicability is (ISG)
PDTA_WhichPicture (uint32)
Used by subclasses, specifies the index of the picture to load.
For file that store more than one picture, the index number 0 would
refer to the first picture, 1 to the second and so on. This tag
is intended to work in conjunction with PDTA_GetNumPictures.
To load a specific picture from a file, first check how many pictures
are available from an initial picture object before constructing a
second object to retrieve the desired picture.
Old picture.datatype subclasses might not support the PDTA_WhichPicture
and PDTA_GetNumPictures tags. The best way to determine if a subclass
supports these tags is to query the value of PDTA_GetNumPictures; if
supported, the subclass will modify this value. Old picture classes
might also not support the PDTA_WhichPicture tag and always return the
first picture, regardless of that requested.
If the requested picture is not available (for example, you ask for
picture #10 but there are only 3 pictures stored) the subclass SHOULD
return NULL and set the error code DTERROR_NOT_AVAILABLE. This does
not mean the file was not found, just that the picture with the
requested index is not available.
Defaults to 0.
Applicability is (I)
PDTA_GetNumPictures (uint32)
Query the number of pictures stored within the file.
NOTE that old subclasses will ignore this tag. Subsequently the
value supplied may not be modified, therefore you should initialise
it to the constant value PDTANUMPICTURES_Unknown.
This tag is unusual in that it does not operate on an already
existing object in the GetDTAttrs() context. This was allegedly
done for practical reasons: where the picture subclasss is still
processing the image data, it MAY be more convenient to count the
number of pictures in the file first that after the file was already
read.
Defaults to NULL.
Applicability is (I)
PDTA_MaxDitherPens (uint32)
The maximum number of pens to use during colour quantization.
NOTE that some quantization algorithms require a power of two
for optimal results.
Defaults to 125.
Applicability is (ISG)
PDTA_DitherQuality (uint32)
Specifies the quality of the dithering algorithm to be used during
colour quantization. A value of 0 (zero) yields little or no
visible quality improvements which a value of 2 will yield noticeably
better results. Generally, the higher the value requested, the
better the output.
The current version of the picture.datatype from AmigaKit Ltd can
perform no dither (0), an error diffused dither (1), Bayer's ordered
dither (2) and Burke's dither (a variant of Floyd-Steinberg, 3).
Defaults to 1.
Applicability is (ISG)
PDTA_ScaleQuality (uint32)
Specifies the quality of the scaling algorithm to be used with the
PDTM_SCALE method. A value of 0 (zero) means fast'n'ugly while
1 (one) means slow'n'nice. The results, however, may be subjective.
Defaults to 0.
Applicability is (ISG)
PDTA_ObtainPixelBuffer (struct pdtBlitPixelArray *)
Provided for OS 3.2 compatibility and is the equivalent of the
PDTM_OBTAINPIXELARRAY method.
Applicability is (S)
NOTES Contrary to previous versions of the picture.datatype, the PDTA_Allocated tag now returns the number of pens allocated during layout or remap. For the common use of the picture class, this value will be the same as that for PDTA_NumAlloc but where layout/remap has been performed without a screen, no pens can be allocated even though the (number of) colours in the destination bitmap may have been altered. Making a distinction between these two facets of the datatype allow remapping to be performed without intending to display the result; for example, simply reducing the colours or scaling a picture does not require a screen yet prior implementations require that it does. Anecdotally, I do not believe PDTA_AllocatedPens works as described in the "official" documentation since PDTA_ColorTable and PDTA_ColorTable2 are described as having potentially different pens; so when this occurs, the documented nature of a 1:1 mapping of PDTA_GRegs to PDTA_AllocatedPens is evidently false because there are two potential pens for one colour map entry with no way to distinguish those in the PDTA_AllocatedPens series. If the number of colours for a colour-mapped picture is limited to 256 (8-bit) then PDTA_NumAlloc can never be higher than this, leading to the values in PDTA_AllocatedPens only list half of the actual pens allocated. Plus, the values of PDTA_AllocatedPens do not match the palette entry when this occurs. Therefore, PDTA_NumColors is to PDTA_CRegs as PDTA_NumAlloc is to PDTA_GRegs. Thus, PDTA_Allocated shares this same relationship to PDTA_AllocatedPens since PDTA_NumAlloc may differ from PDTA_Allocated (where one is the reduced palette and the other is the number of pens allocated for display).
The picture.datatype from AmigaKit Ltd, as with many of its predecessors, does not suffer from the layout restrictions present in the old revisions. That is, for example, an extra-halfbrite or HAM picture no longer requires you to open a custom screen for display - any screen will do.
Writing greyscale data to a picture (using PBPAFMT_GREY8 pixel format and PDTM_WRITEPIXELARRAY) automagically configures the picture colour palette when the first line is written. The palette is reset to 256 shades of grey with 0 = black and 255 = white. If you do not wish this to happen, do not use PBPAFMT_GREY8 but instead use PBPAFMT_LUT8, which allows you to retain control over the picture colour palette.
Reading PBPAFMT_LUT8/GREY8 data from an underlying RGB pixel buffer will give a pseudo pen index using the RGB332 form (3 bits red, 3 bits green, 2 bits blue) into a palette of up to 256 colours. Reading the same from ARGB/RGBA pixels MAY induce colour blending with the designated background colour. Background colour defaults to (in order if priority): - the colour specified as BGCOLOR in env-var - colour index 0 for transparent/lasso masking - BACKGROUNDPEN from any screen DrawInfo available - #cccccc/rgb(204,204,204) if all else fails
The masking option of 'lasso' is supported with proviso: the fill occurs from (0,0). This means if the pixel at (0,0) is the transparent colour then effectively no fill will occur. This may or may not change in a future release of the datatype.
There is also the option of specifying certain default behaviour by use
of the environmental variable "Datatypes/picture.datatype". Such options
are the default state and will persist unless/until overridden by
explicit setters by subclasses or callers
These options are as follows:
FORCEV43/S,REDMEAN/S,NOIPREFS/S,QUANT=QUANTIZATION/K/N,DITHER/K/N,
SCALE/K/N,MAXPENS/K/N,BGCOLOR/K
Where,
- FORCEV43 will force V43 source mode by default
- REDMEAN uses a better but more intensive colour comparison;
the default is simple Euclidian distance.
- NOIPREFS do not attempt to account for IPrefs odd behaviour
- QUANT [0..3] specifies the default quantization algorithm
- DITHER [0..3] specifies the preferred dither algorithm
- SCALE [0..1] specifies the preferred scaling quality
- MAXPENS [2..256] overrides the max. pens when dithering
- BGCOLOR specifies a background colour to use when converting
ARGB/RGBA to RGB or CLUT images; should be in the
hexadecimal notation '#RGB', or '#RRGGBB'
Using different values for DITHER and QUANT can produce significantly different results, depending on your use case.
picture.datatype/PDTM_QUANTIZEPIXELARRAYture.datatype/PDTM_QUANTIZEPIXELARRAY
NAME
PDTM_QUANTIZEPIXELARRAY -- Analyse the specified rectangular pixel array
and generate a reduced colour palette for the
picture region.
FUNCTION Analyse the picture pixel buffer to determine an appropriate gamut for a reduced colour palette, using a choice of algorithms. Some quantization methods produce better results than others.
INPUTS
struct pdtQuantizePixelArray
MethodID - PDTM_SCALEPIXELARRAY
pqpa_Which - Specifies which algorithm to use (see below)
pqpa_Left - The left-most pixel to start analysing from
pqpa_Top - The top-most pixel to start analysing from
pqpa_Width - The width of the rectangle to analyse
pqpa_Height - The height of the rectangle to analyse
pqpa_ColorRegs - A pointer to the 32-bit RGB colour table
pqpa_Length - The required number of colours to find
pqpa_Attrs - Any other attributes.
Quantization algorithms:
The default quantization method for the picture datatype is controlled
by the environment variable Datatypes/picture.datatype/QUANTIZATION
with a value of "0" (popular), "1" (octree) or "2" (median cut).
PQUANTIZE_POPULAR scans the pixels and returns a palette of the most
frequently used N colours; can cause some aliasing where a lesser
used colour has been omitted from the palette.
PQUANTIZE_OCTREE scans the colours and provides an averaged (merged)
colour for similar, lesser used colours; resulting in an adaptive
colour palette for the remapped picture.
PQUANTIZE_MEDIANCUT divides the pixels into buckets and sorts those
buckets based on pixels with the greatest range before once
more splitting the bucket(s); resulting in an adaptive palette
for the remapped picture.
PQUANTIZE_PENS is a convenience function to producing the 32-bit RGB
triplet table from a pen array, similar to GetRGB32().
PQUANTIZE_VGA does not, in fact, quantize the pixel array but instead
populates the colour table with the more common of the VGA
colour palette(s), dependent on the number of colours.
RESULT Returns zero (0) if unsuccessful, otherwise a non-zero value when the scaling has completed.
NOTE This function does not perform remapping of colours and/or pens and as such does not imply a layout. The resulting palette will likely contain colours not used in the original image as colours will have been combined to produce a "better match", particularly in the octree algorithm where similar but lesser used colours are combined to reduce the palette.
The median cut algorithm requires that the number of requested colours be a power of 2 (e.g, 32, 64, 128) as the algorithm works by dividing the plane in half before analyzing colour ranges and continues until the number of colours has been reached.
This function is bespoke to the AmigaKit Ltd picture.datatype replacement and is not (currently) present on the AmigaOS "official" picture class.
picture.datatype/PDTM_SCALE picture.datatype/PDTM_SCALE
NAME PDTM_SCALE -- Scale the pixel data to a new size.
FUNCTION Resize the entire picture pixel array to the new dimensions, using either simple matrix, low-pass or bilinear scaling.
INPUTS
struct pdtScale
MethodID - PDTM_SCALE
ps_NewWidth - The width of the destination pixel array
ps_NewHeight - The height of the destination pixel array
ps_Flags - Bitwise flags; see below.
Flags currently include:
PSCALE_FAST (0) - Use simple "matrix" based transformation
PSCALE_BILINEAR (1) - Use bilinear scaling or low-pass smoothing
PSCALE_BICUBIC (2) - not yet supported
RESULT Returns zero (0) if unsuccessful, otherwise a non-zero value when the scaling has completed.
NOTES Scaling is only possible before the first GM_LAYOUT (remap) has been performed. This operation modifies the internal pixel buffer to conform to the specified width and height, effectively destroying the original image: it cannot be undone.
picture.datatype/PDTM_SCALEPIXELARRAY picture.datatype/PDTM_SCALEPIXELARRAY
NAME PDTM_SCALEPIXELARRAY -- Scale the specified rectangular pixel array.
FUNCTION Resize the rectangular region of the picture pixel array to the new dimensions, using either simple matrix, low-pass or bilinear scaling. Unlike the associated PDTM_SCALE method, the scaling of the pixel array does NOT require a layout and does not affect the destination bitmap since no remapping is done.
INPUTS
struct pdtScalePixelArray
MethodID - PDTM_SCALEPIXELARRAY
pspa_PixelData - The buffer to receive the scaled pixel array
pspa_PixelFormat - The destination pixel array format
pspa_PixelArrayMod - The number of octets per row
pspa_Left - The left-most pixel to scale from
pspa_Top - The top-most pixel to scale from
pspa_Width - The width of the rectangle to scale
pspa_Height - The height of the rectangle to scale
pspa_NewWidth - The width of the destination pixel array
pspa_NewHeight - The height of the destination pixel array
pspa_Flags - Bitwise flags; see below.
Flags currently include:
scaleFast (0) - Use simple "matrix" based transformation
scaleBilinear (1) - Use bilinear scaling or low-pass smoothing
RESULT Returns zero (0) if unsuccessful, otherwise a non-zero value when the scaling has completed.
NOTE This function does not perform remapping of colours and/or pens and as such does not imply a layout; the resulting scaled pixel array will be written to the supplied pixel buffer specified in the message. It is possible using xRGB pixel buffers that some colours may differ from the original due to smoothing.
This function is bespoke to the AmigaKit Ltd picture.datatype replacement and is not (currently) present on the AmigaOS "official" picture class.
picture_dtc/OM_DISPOSE picture_dtc/OM_DISPOSE
NAME OM_DISPOSE -- Dispose an instance of a document class object.
SYNOPSIS result = OM_DISPOSE(class, obj, msg) uint32 OM_DISPOSE(Class *, Object *, Msg)
FUNCTION Dispose of the specified document class object instance.
INPUTS class - The Class pointer obj - The Object instance. msg - The dispose operation message.
RESULT Zero.
SEE ALSO picture_dtc/OM_NEW
picture_dtc/OM_GET picture_dtc/OM_GET
NAME OM_GET -- Get an attribute values for an object.
SYNOPSIS result = OM_GET(class, obj, msg) uint32 OM_GET(Class *, Object *, struct opGet *)
FUNCTION Retrieve an attribute value from the specified class instance.
INPUTS class - The Class pointer obj - The Object instance pointer msg - The get operation message.
RESULT One (1L) if the attribute was found, otherwise zero (0L)
SEE ALSO markdown_dtc/OM_SET, <datatypes/pictureclass.h>
picture_dtc/OM_NEW picture_dtc/OM_NEW
NAME OM_NEW -- Initialise a new instance of a document class object.
SYNOPSIS result = OM_NEW(class, obj, msg) uint32 OM_NEW(Class *, Object *, struct opSet *)
FUNCTION Initialise a new instance of a document class object and apply the attribute values specified.
INPUTS class - The Class pointer obj - The "true" Class pointer msg - The set operation message.
RESULT A pointer to the object instance, or NULL on failure.
SEE ALSO picture_dtc/OM_DISPOSE
picture_dtc/OM_SET picture_dtc/OM_SET
NAME OM_SET -- Set the values for attributes on the object.
SYNOPSIS result = OM_SET(class, obj, msg) uint32 OM_SET(Class *, Object *, struct opSet *)
FUNCTION Attempt to set values for attributes on the object.
INPUTS class - The Class pointer obj - The Object instance pointer msg - The set operation message.
RESULT One (1L) if the object needs a visual referesh to reflect the changes, otherwise zero (0L)
SEE ALSO root_cl/OM_GET, <datatypes/pictureclass.h>