View source for Image (lx-image.hpp)

{{DISPLAYTITLE:image (lx_image.hpp)}}

<span id="S1"></span>
== Images ==

This module defines COM interfaces for dealing with pixel-map images. Greyscale, color and alpha mapped images can be read, written, loaded and saved using these interfaces.  All images present consistent features regardless of their internal representation.
<span id="C1"></span>
<span id="S1.1"></span>
=== Pixel Formats ===

Images are defined by their pixel format which consists of a datatype and vector size.  There are two data types.  The BYTE type is an 8 bit integer in the range is 0 to 255.  The FLOAT type is a 32-bit floating point number in the nominal range of 0.0 to 1.0.  Operations on integer pixel values are  clamped so the results are always in the valid range.  Floating point colors are not clamped, so the images can represent superbright and superdark pixels.

===== (1) SDK: LXiIMD_BYTE, etc. defines =====

<syntaxhighlight>
 #define [[LXiIMD_BYTE (index)|LXiIMD_BYTE]]     0x00
 #define [[LXiIMD_FLOAT (index)|LXiIMD_FLOAT]]    0x08
 #define [[LXfIMD_MASK (index)|LXfIMD_MASK]]     0x08
 
 #define [[LXxIMD_TYPE (index)|LXxIMD_TYPE]](t)  (t & [[LXfIMD_MASK (index)|LXfIMD_MASK]])
</syntaxhighlight>

<span id="C2"></span>
The vector sizes are GREY which is one monochrome component; RGB which is a vector of three color components; or RGBA which is a vector of three color components and alpha.  The alpha channel is represented by 0 for transparent, 255 for opaque if in byte format, and 1.0 for opaque if floating point format.

===== (2) SDK: LXiIMV_GREY, etc. defines =====

<syntaxhighlight>
 #define [[LXiIMV_GREY (index)|LXiIMV_GREY]]     0x01
 #define [[LXiIMV_RGB (index)|LXiIMV_RGB]]      0x03
 #define [[LXiIMV_RGBA (index)|LXiIMV_RGBA]]     0x04
 #define [[LXfIMV_MASK (index)|LXfIMV_MASK]]     0x07
 
 #define [[LXxIMV_TYPE (index)|LXxIMV_TYPE]](v)  (v & [[LXfIMV_MASK (index)|LXfIMV_MASK]])
</syntaxhighlight>

<span id="C3"></span>
Index images use the index flag.

===== (3) SDK: LXiIMT_INDEX, etc. defines =====

<syntaxhighlight>
 #define [[LXiIMT_INDEX (index)|LXiIMT_INDEX]]    0x100
 #define [[LXiIMT_MASK (index)|LXiIMT_MASK]]     0x100
</syntaxhighlight>

<span id="C4"></span>
Image pixel types are just the mask values combined together.  Here are all six of the possible combinations in more convenient form.  The color bits of an index mask can be acquired separately as well.

===== (4) SDK: LXiIMP_GREY8, etc. defines =====

<syntaxhighlight>
 #define [[LXiIMP_GREY8 (index)|LXiIMP_GREY8]]    ([[LXiIMD_BYTE (index)|LXiIMD_BYTE]]  | LXiIMV_GREY)
 #define [[LXiIMP_GREYFP (index)|LXiIMP_GREYFP]]   ([[LXiIMD_FLOAT (index)|LXiIMD_FLOAT]] | LXiIMV_GREY)
 #define [[LXiIMP_RGB24 (index)|LXiIMP_RGB24]]    ([[LXiIMD_BYTE (index)|LXiIMD_BYTE]]  | LXiIMV_RGB)
 #define [[LXiIMP_RGBFP (index)|LXiIMP_RGBFP]]    ([[LXiIMD_FLOAT (index)|LXiIMD_FLOAT]] | LXiIMV_RGB)
 #define [[LXiIMP_RGBA32 (index)|LXiIMP_RGBA32]]   ([[LXiIMD_BYTE (index)|LXiIMD_BYTE]]  | LXiIMV_RGBA)
 #define [[LXiIMP_RGBAFP (index)|LXiIMP_RGBAFP]]   ([[LXiIMD_FLOAT (index)|LXiIMD_FLOAT]] | LXiIMV_RGBA)
 
 #define [[LXiIMP_IGREY8 (index)|LXiIMP_IGREY8]]   ([[LXiIMD_BYTE (index)|LXiIMD_BYTE]]  | LXiIMV_GREY | [[LXiIMT_INDEX (index)|LXiIMT_INDEX]])
 #define [[LXiIMP_IRGB24 (index)|LXiIMP_IRGB24]]   ([[LXiIMD_BYTE (index)|LXiIMD_BYTE]]  | LXiIMV_RGB  | [[LXiIMT_INDEX (index)|LXiIMT_INDEX]])
 #define [[LXiIMP_IRGBA32 (index)|LXiIMP_IRGBA32]]  ([[LXiIMD_BYTE (index)|LXiIMD_BYTE]]  | LXiIMV_RGBA | [[LXiIMT_INDEX (index)|LXiIMT_INDEX]])
 
 // macro to check for greyscale pixel types explicitly, as LXiIMV_RGB masks LXiIMV_GREY
 #define [[LXi_IMP_ISGREY (index)|LXi_IMP_ISGREY]](x) ((x == [[LXiIMP_GREY8 (index)|LXiIMP_GREY8]]) || (x == [[LXiIMP_GREYFP (index)|LXiIMP_GREYFP]]) || (x == [[LXiIMP_IGREY8 (index)|LXiIMP_IGREY8]]))
</syntaxhighlight>

<span id="C5"></span>
===== (5) SDK: LXiPROCESS_FAST, etc. defines =====

<syntaxhighlight>
 #define [[LXiPROCESS_FAST (index)|LXiPROCESS_FAST]]         0
 #define [[LXiPROCESS_MEDIUM (index)|LXiPROCESS_MEDIUM]]       1
 #define [[LXiPROCESS_ACCURATE (index)|LXiPROCESS_ACCURATE]]     2
</syntaxhighlight>

<span id="C6"></span>
===== (6) SDK: LXtPixelFormat, etc. typedefs (types) =====

<syntaxhighlight>
 typedef unsigned int     LXtPixelFormat;
 typedef unsigned int     LXtProcessHint;
 typedef unsigned char    LXtImageByte;
 typedef float            LXtImageFloat;
 typedef unsigned int     LXtImageIndex;
 typedef LXtImageFloat    LXtColorRGBA[4];
</syntaxhighlight>

<span id="C7"></span>
Color components in stored in vector type pixels are always in RGBA order. Use these indices to access components in a more abstract way.

===== (7) SDK: LXiIMC_RED, etc. defines =====

<syntaxhighlight>
 #define [[LXiIMC_RED (index)|LXiIMC_RED]]      0
 #define [[LXiIMC_GREEN (index)|LXiIMC_GREEN]]    1
 #define [[LXiIMC_BLUE (index)|LXiIMC_BLUE]]     2
 #define [[LXiIMC_ALPHA (index)|LXiIMC_ALPHA]]    3
</syntaxhighlight>

<span id="C8"></span>
<span id="S1.2"></span>
=== Image Interfaces ===

There are several image interfaces, but they all start with the following two methods.  The first gets the width and height of the image in pixels. The second returns the pixel format closest to the native storage format for the image data.  Both must always return reasonable values, so there are no error conditions.

===== (8) SDK Common: Image methods =====

<syntaxhighlight>
         [[LXxMETHOD (index)|LXxMETHOD]]( void,
 Size) (
         [[LXtObjectID (index)|LXtObjectID]]              self,
         unsigned int            *w,
         unsigned int            *h);
 
         [[LXxMETHOD (index)|LXxMETHOD]]( LXtPixelFormat,
 Format) (
         [[LXtObjectID (index)|LXtObjectID]]              self);
</syntaxhighlight>

<span id="C9"></span>
There are also common user class extensions to allow reading the width and height independently, and to query attributes of the format.

===== (9) SDK Common User: Size methods =====

<syntaxhighlight>
         unsigned
 Width () const
 {
         unsigned                 w, h;
 
         Size (&w, &h);
         return w;
 }
 
         unsigned
 Height () const
 {
         unsigned                 w, h;
 
         Size (&w, &h);
         return h;
 }
</syntaxhighlight>

<span id="C10"></span>
===== (10) SDK Common User: Format methods =====

<syntaxhighlight>
         bool
 IsFloat () const
 {
         return [[LXxIMD_TYPE (index)|LXxIMD_TYPE]] (Format ()) == [[LXiIMD_FLOAT (index)|LXiIMD_FLOAT]];
 }
 
         unsigned
 Components () const
 {
         return [[LXxIMV_TYPE (index)|LXxIMV_TYPE]] (Format ());
 }
</syntaxhighlight>

<span id="C11"></span>
===== (11) PY Common: Image methods =====

<syntaxhighlight>
 def IsFloat(self):
     return (self.Format() & lx.symbol.fIMD_MASK) == lx.symbol.iIMD_FLOAT
 
 def Components(self):
     return self.Format() & lx.symbol.fIMV_MASK
</syntaxhighlight>

<span id="C12"></span>
<span id="S1.2.1"></span>
==== Adding Image Attributes ====

Arbitrary attributes may be added to writeable image objects.  These can be read and set using the image ILxAttributes interface.

This function allows a client to add an attribute to an ILxImageWrite object by providing an attribute name and an exotype name.  If the attribute has been added successfully, its index will be returned.

===== (12) SDK Common: Image Write methods =====

<syntaxhighlight>
         [[LXxMETHOD (index)|LXxMETHOD]](  [[LxResult (index)|LxResult]],
 AddAttribute) (
         [[LXtObjectID (index)|LXtObjectID]]              self,
         const char              *name,
         const char              *type,
         unsigned                *index);
</syntaxhighlight>

<span id="C13"></span>
<span id="S1.2.2"></span>
==== Standard Image Attributes ====

Some name and types are defined for common attributes that are read or set by the application.
{| class="wikitable"
 |-
 |DPI
 | Dots per Inch, which is the number of pixels in the image that will fit vertically in each inch of the printed image.  To know the horizontal DPI you have to take pixel aspect into account.
 |-
 |PIXASPECT
 | This is the aspect ratio of a single pixel in the image, computed as width/height.  If the pixel height is one, then the pixel width is the same as the pixel aspect.
 |-
 |REGX0, REGX1, REGY0, REGY1
 | Pixel coordinates of the borders of the rendered region of the image.  X and Y start at zero at the left and top of the image.
 |-
 |GAMMA
 | Gamma is an exponent applied to unity-normalized color values in the image before saving.  To get the "real" values for pixels in the image, the inverse gamma needs to be applied.
 |-
 |COMMENT
 | Everyone's got something to say, right?
|}

===== (13) SDK: LXsIATTRNAME_CAM_TRANS, etc. defines =====

<syntaxhighlight>
 #define [[LXsIATTRNAME_CAM_TRANS (index)|LXsIATTRNAME_CAM_TRANS]]                  "cameraTransform"
 #define [[LXsIATTRTYPE_CAM_TRANS (index)|LXsIATTRTYPE_CAM_TRANS]]          [[LXsTYPE_STRING (index)|LXsTYPE_STRING]]
 
 #define [[LXsIATTRNAME_WORLD_TO_CAM (index)|LXsIATTRNAME_WORLD_TO_CAM]]               "worldToCamera"
 #define [[LXsIATTRTYPE_WORLD_TO_CAM (index)|LXsIATTRTYPE_WORLD_TO_CAM]]               [[LXsTYPE_STRING (index)|LXsTYPE_STRING]]
 
 #define [[LXsIATTRNAME_ISO (index)|LXsIATTRNAME_ISO]]                        "ISO"
 #define [[LXsIATTRTYPE_ISO (index)|LXsIATTRTYPE_ISO]]                        [[LXsTYPE_FLOAT (index)|LXsTYPE_FLOAT]]
 
 #define [[LXsIATTRNAME_EXPTIME (index)|LXsIATTRNAME_EXPTIME]]                    "exposureTime"
 #define [[LXsIATTRTYPE_EXPTIME (index)|LXsIATTRTYPE_EXPTIME]]                    [[LXsTYPE_FLOAT (index)|LXsTYPE_FLOAT]]
 
 #define [[LXsIATTRNAME_DPI (index)|LXsIATTRNAME_DPI]]                    "DPI"
 #define [[LXsIATTRTYPE_DPI (index)|LXsIATTRTYPE_DPI]]                    [[LXsTYPE_FLOAT (index)|LXsTYPE_FLOAT]]
 
 #define [[LXsIATTRNAME_APERATUREX (index)|LXsIATTRNAME_APERATUREX]]     "aperatureX"
 #define [[LXsIATTRTYPE_APERATUREX (index)|LXsIATTRTYPE_APERATUREX]]     [[LXsTYPE_FLOAT (index)|LXsTYPE_FLOAT]]
 
 #define [[LXsIATTRNAME_APERATUREY (index)|LXsIATTRNAME_APERATUREY]]     "aperatureY"
 #define [[LXsIATTRTYPE_APERATUREY (index)|LXsIATTRTYPE_APERATUREY]]     [[LXsTYPE_FLOAT (index)|LXsTYPE_FLOAT]]
 
 #define [[LXsIATTRNAME_CLIP_DIST (index)|LXsIATTRNAME_CLIP_DIST]]      "clipDist"
 #define [[LXsIATTRTYPE_CLIP_DIST (index)|LXsIATTRTYPE_CLIP_DIST]]      [[LXsTYPE_FLOAT (index)|LXsTYPE_FLOAT]]
 
 #define [[LXsIATTRNAME_FOC_LENGTH (index)|LXsIATTRNAME_FOC_LENGTH]]     "focalLength"
 #define [[LXsIATTRTYPE_FOC_LENGTH (index)|LXsIATTRTYPE_FOC_LENGTH]]     [[LXsTYPE_FLOAT (index)|LXsTYPE_FLOAT]]
 
 #define [[LXsIATTRNAME_PIXASPECT (index)|LXsIATTRNAME_PIXASPECT]]          "pixelAspect"
 #define [[LXsIATTRTYPE_PIXASPECT (index)|LXsIATTRTYPE_PIXASPECT]]          [[LXsTYPE_FLOAT (index)|LXsTYPE_FLOAT]]
 
 #define [[LXsIATTRNAME_REGX0 (index)|LXsIATTRNAME_REGX0]]                  "regionX0"
 #define [[LXsIATTRTYPE_REGX0 (index)|LXsIATTRTYPE_REGX0]]                  [[LXsTYPE_INTEGER (index)|LXsTYPE_INTEGER]]
 
 #define [[LXsIATTRNAME_REGX1 (index)|LXsIATTRNAME_REGX1]]                  "regionX1"
 #define [[LXsIATTRTYPE_REGX1 (index)|LXsIATTRTYPE_REGX1]]                  [[LXsTYPE_INTEGER (index)|LXsTYPE_INTEGER]]
 
 #define [[LXsIATTRNAME_REGY0 (index)|LXsIATTRNAME_REGY0]]                  "regionY0"
 #define [[LXsIATTRTYPE_REGY0 (index)|LXsIATTRTYPE_REGY0]]                  [[LXsTYPE_INTEGER (index)|LXsTYPE_INTEGER]]
 
 #define [[LXsIATTRNAME_REGY1 (index)|LXsIATTRNAME_REGY1]]                  "regionY1"
 #define [[LXsIATTRTYPE_REGY1 (index)|LXsIATTRTYPE_REGY1]]                  [[LXsTYPE_INTEGER (index)|LXsTYPE_INTEGER]]
 
 #define [[LXsIATTRNAME_GAMMA (index)|LXsIATTRNAME_GAMMA]]                  "gamma"
 #define [[LXsIATTRTYPE_GAMMA (index)|LXsIATTRTYPE_GAMMA]]                  [[LXsTYPE_FLOAT (index)|LXsTYPE_FLOAT]]
 
 #define [[LXsIATTRNAME_COMMENT (index)|LXsIATTRNAME_COMMENT]]                "comment"
 #define [[LXsIATTRTYPE_COMMENT (index)|LXsIATTRTYPE_COMMENT]]                [[LXsTYPE_STRING (index)|LXsTYPE_STRING]]
 
 #define [[LXsIATTRNAME_APPLY_DISPLAY_LUT (index)|LXsIATTRNAME_APPLY_DISPLAY_LUT]]      "applyDisplayLUT"
 #define [[LXsIATTRTYPE_APPLY_DISPLAY_LUT (index)|LXsIATTRTYPE_APPLY_DISPLAY_LUT]]      [[LXsTYPE_INTEGER (index)|LXsTYPE_INTEGER]]
 
 #define [[LXsSAV_OUTPUT_PIXEL_FORMAT (index)|LXsSAV_OUTPUT_PIXEL_FORMAT]]          "outputPixelFormat"
 #define [[LXsSAV_OUTPUT_KNOWN_COLOR_SPACE (index)|LXsSAV_OUTPUT_KNOWN_COLOR_SPACE]]     "knownColorSpace"
 
 // Certain image formats have a particular color space which
 // can't be inferred from their pixel format (e.g. .hdr is 8-bit but linear)
 // Image IO Plugins can set the 'colorspace' field of the [[LXtImageTarget1 (index)|LXtImageTarget1]]
 // structure to [[LXsKNOWN_COLORSPACE_LINEAR (index)|LXsKNOWN_COLORSPACE_LINEAR]] in order to specify
 // that the colorspace of this image is linear.
 
 #define [[LXsKNOWN_COLORSPACE_LINEAR (index)|LXsKNOWN_COLORSPACE_LINEAR]]          "linear"
 
 #define [[LXsDEFAULT_COLORSPACE_8BIT (index)|LXsDEFAULT_COLORSPACE_8BIT]]          "8bit"
 #define [[LXsDEFAULT_COLORSPACE_16BIT (index)|LXsDEFAULT_COLORSPACE_16BIT]]         "16bit"
 #define [[LXsDEFAULT_COLORSPACE_FLOAT (index)|LXsDEFAULT_COLORSPACE_FLOAT]]         "float"
 #define [[LXsDEFAULT_COLORSPACE_GREY (index)|LXsDEFAULT_COLORSPACE_GREY]]          "grey"
 
 // Image IO Plugins can set the 'depth' field of the [[LXtImageTarget1 (index)|LXtImageTarget1]]
 // structure to any of the below values.
 // Modo will choose a default colorspace for the image based on this setting.
 // If 'None' is specified, no default colorspace conversion will occur.
 //
 // But users can override this choice on a per-clip basis, by setting the
 // clip's colorspace channel.
 //
 #define [[LXiDEFAULT_COLORSPACE_NONE (index)|LXiDEFAULT_COLORSPACE_NONE]]      0
 #define [[LXiDEFAULT_COLORSPACE_8BIT (index)|LXiDEFAULT_COLORSPACE_8BIT]]      1
 #define [[LXiDEFAULT_COLORSPACE_16BIT (index)|LXiDEFAULT_COLORSPACE_16BIT]]     2
 #define [[LXiDEFAULT_COLORSPACE_FLOAT (index)|LXiDEFAULT_COLORSPACE_FLOAT]]     3
 #define [[LXiDEFAULT_COLORSPACE_GREY (index)|LXiDEFAULT_COLORSPACE_GREY]]      4
</syntaxhighlight>

<span id="C14"></span>
<span id="S1.2.3"></span>
==== HDR Image Attributes ====

The OpenEXR file specification suggests some common metadata appropriate for HDR or physically accurate images.
{| class="wikitable"
 |-
 |LUMA
 | The luminance of a white pixel with r&#x3d;g&#x3d;b&#x3d;1.0.  The units, candela/m^2, match the 'whiteLuminance' OpenEXR standard attribute.
 |-
 |FOCDIST
 | The focus distance for the camera.
 |-
 |APERTURE
 | the aperture is given in f-stops, (focal length of the lens divided by the diameter of the iris opening).
|}

===== (14) SDK: LXsIATTRNAME_LUMA, etc. defines =====

<syntaxhighlight>
 #define [[LXsIATTRNAME_LUMA (index)|LXsIATTRNAME_LUMA]]       "luminance"
 #define [[LXsIATTRTYPE_LUMA (index)|LXsIATTRTYPE_LUMA]]        [[LXsTYPE_FLOAT (index)|LXsTYPE_FLOAT]]
 
 #define [[LXsIATTRNAME_FOCDIST (index)|LXsIATTRNAME_FOCDIST]]    "focusDist"
 #define [[LXsIATTRTYPE_FOCDIST (index)|LXsIATTRTYPE_FOCDIST]]     [[LXsTYPE_FLOAT (index)|LXsTYPE_FLOAT]]
 
 #define [[LXsIATTRNAME_APERTURE (index)|LXsIATTRNAME_APERTURE]]   "aperture"
 #define [[LXsIATTRTYPE_APERTURE (index)|LXsIATTRTYPE_APERTURE]]    [[LXsTYPE_FLOAT (index)|LXsTYPE_FLOAT]]
</syntaxhighlight>

<span id="C15"></span>
<span id="S1.2.4"></span>
==== Color Image ====

The basic image interface allows clients to read colored pixels or entire lines.  When reading pixels the client should always ask for an RGBA format, but for lines the full range of format conversions is possible.

===== (15) SDK: Image::GetPixel, etc. =====

<syntaxhighlight>
 ''[[#C8|SDK Common: Image methods]]''
 
         [[LXxMETHOD (index)|LXxMETHOD]]( [[LxResult (index)|LxResult]],
 GetPixel) (
         [[LXtObjectID (index)|LXtObjectID]]              self,
         unsigned int             x,
         unsigned int             y,
         LXtPixelFormat           type,
         void                    *pixel);
 
         [[LXxMETHOD (index)|LXxMETHOD]]( const void *,
 GetLine) (
         [[LXtObjectID (index)|LXtObjectID]]              self,
         unsigned int             y,
         LXtPixelFormat           type,
         void                    *buf);
</syntaxhighlight>

<span id="C16"></span>
This is the primary interface for image objects, and so this the GUID specified when attempting to load or save images.

===== (16) SDK: LXu_IMAGE, etc. defines =====

<syntaxhighlight>
 #define [[LXu_IMAGE (index)|LXu_IMAGE]]       "469AFBB8-E6A2-4d88-9C39-5430CA72E404"
 #define [[LXa_IMAGE (index)|LXa_IMAGE]]       "image"
 #define [[LXa_IMAGE_FLOAT (index)|LXa_IMAGE_FLOAT]] "image_float"
 #define [[LXsSAV_IMAGE_FLOAT (index)|LXsSAV_IMAGE_FLOAT]] "saver.imageFloat"</syntaxhighlight>

<span id="C17"></span>
===== (17) User Class: Image method =====

<syntaxhighlight>
 ''[[#C9|SDK Common User: Size methods]]''
 ''[[#C10|SDK Common User: Format methods]]''
</syntaxhighlight>

<span id="C18"></span>
===== (18) PY: Image method =====

<syntaxhighlight>
 ''[[#C11|PY Common: Image methods]]''
</syntaxhighlight>

<span id="C19"></span>
An image segment is a sub-range of pixels within a scanline, which is always read in FP RGBA format, and written in any given format.

===== (19) SDK: ImageSegment::GetSegment, etc. =====

<syntaxhighlight>
         [[LXxMETHOD (index)|LXxMETHOD]]( [[LxResult (index)|LxResult]],
 GetSegment) (
         [[LXtObjectID (index)|LXtObjectID]]              self,
         unsigned int             y,
         unsigned int             left,
         unsigned int             right,
         LXtImageFloat           *rgba);
 
         [[LXxMETHOD (index)|LXxMETHOD]]( [[LxResult (index)|LxResult]],
 SetSegment) (
         [[LXtObjectID (index)|LXtObjectID]]              self,
         unsigned int             y,
         unsigned int             left,
         unsigned int             right,
         LXtPixelFormat           type,
         const void              *line);
</syntaxhighlight>

<span id="C20"></span>
Empty ImageSegment Python user class.

===== (20) PY: empty ImageSegment user class =====

<syntaxhighlight>
 pass
</syntaxhighlight>

<span id="C21"></span>
===== (21) SDK: LXu_IMAGESEGMENT, etc. defines =====

<syntaxhighlight>
 #define [[LXu_IMAGESEGMENT (index)|LXu_IMAGESEGMENT]]        "370ABB2F-119E-4EEC-98F8-03388ABE7D2C"
 #define [[LXa_IMAGESEGMENT (index)|LXa_IMAGESEGMENT]]        "imagesegment"</syntaxhighlight>

<span id="C22"></span>
Writing to an image requires a different interface.  This provides methods for assigning color values to pixels or lines.  Not all images will be writable.

===== (22) SDK: ImageWrite::SetPixel, etc. =====

<syntaxhighlight>
 ''[[#C8|SDK Common: Image methods]]''
 ''[[#C12|SDK Common: Image Write methods]]''
 
         [[LXxMETHOD (index)|LXxMETHOD]]( [[LxResult (index)|LxResult]],
 SetPixel) (
         [[LXtObjectID (index)|LXtObjectID]]              self,
         unsigned int             x,
         unsigned int             y,
         LXtPixelFormat           type,
         const void              *pixel);
 
         [[LXxMETHOD (index)|LXxMETHOD]]( [[LxResult (index)|LxResult]],
 SetLine) (
         [[LXtObjectID (index)|LXtObjectID]]              self,
         unsigned int             y,
         LXtPixelFormat           type,
         const void              *line);
 
</syntaxhighlight>

<span id="C23"></span>
===== (23) SDK: LXu_IMAGEWRITE, etc. defines =====

<syntaxhighlight>
 #define [[LXu_IMAGEWRITE (index)|LXu_IMAGEWRITE]]  "8F9CF293-B6F9-498e-A124-6704E2C24662"
 #define [[LXa_IMAGEWRITE (index)|LXa_IMAGEWRITE]]  "imagewrite"</syntaxhighlight>

<span id="C24"></span>
===== (24) SDK: CLxUser_ImageWrite::AddAttribute method =====

<syntaxhighlight>
         [[LxResult (index)|LxResult]]
 AddAttribute (
         const std::string       &name,
         const std::string       &type,
         unsigned                &index)
 {
         return CLxLoc_ImageWrite::AddAttribute (name.c_str (), type.c_str (), &index);
 }
 
 ''[[#C9|SDK Common User: Size methods]]''
 ''[[#C10|SDK Common User: Format methods]]''
</syntaxhighlight>

<span id="C25"></span>
===== (25) PY: ImageWrite method =====

<syntaxhighlight>
 ''[[#C11|PY Common: Image methods]]''
</syntaxhighlight>

<span id="C26"></span>
<span id="S1.2.5"></span>
==== Index Image ====

An index image is one that stores index values at the pixel locations and uses a lookup table to get the color.  While the ILxImage interface gets the color values at each pixel, this interface allows access to the underlying index and color map.

===== (26) SDK: IndexImage::MapSize, etc. =====

<syntaxhighlight>
 ''[[#C8|SDK Common: Image methods]]''
 
         [[LXxMETHOD (index)|LXxMETHOD]]( [[LxResult (index)|LxResult]],
 MapSize) (
         [[LXtObjectID (index)|LXtObjectID]]              self,
         unsigned                *numColors);
 
         [[LXxMETHOD (index)|LXxMETHOD]]( [[LxResult (index)|LxResult]],
 GetIndex) (
         [[LXtObjectID (index)|LXtObjectID]]              self,
         unsigned int             x,
         unsigned int             y,
         LXtImageIndex           *index);
 
         [[LXxMETHOD (index)|LXxMETHOD]]( [[LxResult (index)|LxResult]],
 GetMap) (
         [[LXtObjectID (index)|LXtObjectID]]              self,
         LXtImageIndex            index,
         LXtPixelFormat           type,
         void                    *pixel);
</syntaxhighlight>

<span id="C27"></span>
===== (27) SDK: LXu_INDEXIMAGE define =====

<syntaxhighlight>
 #define [[LXu_INDEXIMAGE (index)|LXu_INDEXIMAGE]]          "08CAE3BC-ED69-4EC4-9D7D-BBDBE4E35343"</syntaxhighlight>

<span id="C28"></span>
===== (28) User Class: IndexImage method =====

<syntaxhighlight>
 ''[[#C9|SDK Common User: Size methods]]''
 ''[[#C10|SDK Common User: Format methods]]''
</syntaxhighlight>

<span id="C29"></span>
===== (29) PY: IndexImage method =====

<syntaxhighlight>
 ''[[#C11|PY Common: Image methods]]''
</syntaxhighlight>

<span id="C30"></span>
Writing to an index image can only be done with one of these interfaces.

===== (30) SDK: IndexImageWrite::SetIndex, etc. =====

<syntaxhighlight>
 ''[[#C8|SDK Common: Image methods]]''
 
 ''[[#C12|SDK Common: Image Write methods]]''
 
         [[LXxMETHOD (index)|LXxMETHOD]]( [[LxResult (index)|LxResult]],
 SetIndex) (
         [[LXtObjectID (index)|LXtObjectID]]              self,
         unsigned int             x,
         unsigned int             y,
         LXtImageIndex            index);
 
         [[LXxMETHOD (index)|LXxMETHOD]]( [[LxResult (index)|LxResult]],
 SetMap) (
         [[LXtObjectID (index)|LXtObjectID]]              self,
         LXtImageIndex            index,
         LXtPixelFormat           type,
         const void              *pixel);
</syntaxhighlight>

<span id="C31"></span>
===== (31) SDK: LXu_INDEXIMAGEWRITE define =====

<syntaxhighlight>
 #define [[LXu_INDEXIMAGEWRITE (index)|LXu_INDEXIMAGEWRITE]]     "D59C5E09-779E-445b-B317-282630CB6BD5"</syntaxhighlight>

<span id="C32"></span>
===== (32) SDK: CLxUser_IndexImageWrite::AddAttribute method =====

<syntaxhighlight>
         [[LxResult (index)|LxResult]]
 AddAttribute (
         const std::string       &name,
         const std::string       &type,
         unsigned                &index)
 {
         return CLxLoc_IndexImageWrite::AddAttribute (name.c_str (), type.c_str (), &index);
 }
 
 ''[[#C9|SDK Common User: Size methods]]''
 ''[[#C10|SDK Common User: Format methods]]''
</syntaxhighlight>

<span id="C33"></span>
===== (33) PY: IndexImageWrite method =====

<syntaxhighlight>
 ''[[#C11|PY Common: Image methods]]''
</syntaxhighlight>

<span id="C34"></span>
<span id="S1.2.6"></span>
==== Layered Images ====

In many cases it is useful to add channels to images beyond the basic R, G, B, and A. In other cases, it is useful to preserve multiple sub-images in a composition. These requirements can be met with a layered image object, consisting of a list of named, independent sub-images, each with their own dimensions, offset, and pixel type. Interlayer blending information is also associated with each layer, Photoshop style.
{| class="wikitable"
 |-
 |Size
 | This returns the bounds of the image composition. While the combination of layer sizes and offsets makes it possible that some layers' pixels will not all be in bounds, the entire composition will be cropped at (0,0) to (w,h).
|}

===== (34) SDK: LayeredImage::Size =====

<syntaxhighlight>
         [[LXxMETHOD (index)|LXxMETHOD]]( [[LxResult (index)|LxResult]],
 Size) (
         [[LXtObjectID (index)|LXtObjectID]]              self,
         unsigned int            *w,
         unsigned int            *h);
</syntaxhighlight>

<span id="C35"></span>
Adding a standard format() method here would allow this object to masquerade as an ILxImage object...  probably more confusing than useful.
{| class="wikitable"
 |-
 |Count
 | return number of layers.
 |-
 |Image
 | return ILxImage for layer at 'index'.
 |-
 |Name
 | return name for layer at 'index'.
 |-
 |Type
 | return type string and flags for layer at 'index'.
|}

===== (35) SDK: LayeredImage::Count, etc. =====

<syntaxhighlight>
         [[LXxMETHOD (index)|LXxMETHOD]]( unsigned int,
 Count) (
         [[LXtObjectID (index)|LXtObjectID]]              self);
 
         [[LXxMETHOD (index)|LXxMETHOD]]( [[LxResult (index)|LxResult]],
 Image) (
         [[LXtObjectID (index)|LXtObjectID]]              self,
         unsigned int             index,
         void                   **ppvObj);
 
         [[LXxMETHOD (index)|LXxMETHOD]]( [[LxResult (index)|LxResult]],
 Name) (
         [[LXtObjectID (index)|LXtObjectID]]              self,
         unsigned int             index,
         const char             **name);
 
         [[LXxMETHOD (index)|LXxMETHOD]]( [[LxResult (index)|LxResult]],
 Type) (
         [[LXtObjectID (index)|LXtObjectID]]              self,
         unsigned int             index,
         unsigned int            *flags,
         const char             **type);
</syntaxhighlight>

<span id="C36"></span>
{| class="wikitable"
 |-
 |Offset
 | return pixel offset for layer at 'index' relative to complete layered image composition..
 |-
 |Blend
 | returns the opacity and the image blend mode for layer at 'index'. The image blend mode is one of the LXi_IBM_ modes.
|}

===== (36) SDK: LayeredImage::Offset, etc. =====

<syntaxhighlight>
         [[LXxMETHOD (index)|LXxMETHOD]]( [[LxResult (index)|LxResult]],
 Offset) (
         [[LXtObjectID (index)|LXtObjectID]]              self,
         unsigned int             index,
         int                     *x,
         int                     *y);
 
         [[LXxMETHOD (index)|LXxMETHOD]]( [[LxResult (index)|LxResult]],
 Blend) (
         [[LXtObjectID (index)|LXtObjectID]]              self,
         unsigned int             index,
         float                   *opacity,
         unsigned int            *mode);
</syntaxhighlight>

<span id="C37"></span>
{| class="wikitable"
 |-
 |ChannelName
 | Pass back the name of the channel at the given layer and channel index, which may be overridden by the user by inserting semicolon delimiters in between each channel name in the Shader Tree.
|}

===== (37) SDK: LayeredImage::ChannelName =====

<syntaxhighlight>
         [[LXxMETHOD (index)|LXxMETHOD]]( [[LxResult (index)|LxResult]],
 ChannelName) (
         [[LXtObjectID (index)|LXtObjectID]]              self,
         unsigned                 layerIndex,
         unsigned                 channelIndex,
         const char              **name);
</syntaxhighlight>

<span id="C38"></span>
{| class="wikitable"
 |-
 |Parent
 | Returns the parent layer index, or -1 if there is no parent
 |-
 |IsGroup
 | Returns true if the layer is a group layer
|}

===== (38) SDK: LayeredImage::Parent, etc. =====

<syntaxhighlight>
         [[LXxMETHOD (index)|LXxMETHOD]]( [[LxResult (index)|LxResult]],
 Parent) (
         [[LXtObjectID (index)|LXtObjectID]]              self,
         unsigned                 layerIndex,
         int                     *parentIndex);
 
         [[LXxMETHOD (index)|LXxMETHOD]]( [[LxResult (index)|LxResult]],
 IsGroup) (
         [[LXtObjectID (index)|LXtObjectID]]              self,
         unsigned                 layerIndex,
         unsigned int            *isGroup);
</syntaxhighlight>

<span id="C39"></span>
===== (39) SDK: LXu_LAYEREDIMAGE, etc. defines =====

<syntaxhighlight>
 #define [[LXu_LAYEREDIMAGE (index)|LXu_LAYEREDIMAGE]]        "8523ECC4-B8B3-4C6E-8F14-A1D2D01E8038"
 #define [[LXa_LAYEREDIMAGE (index)|LXa_LAYEREDIMAGE]]        "layeredimage"</syntaxhighlight>

<span id="C40"></span>
===== (40) SDK: CLxUser_LayeredImage::GetImage method =====

<syntaxhighlight>
 
 ''[[#C9|SDK Common User: Size methods]]''
 
         bool
 GetImage (
         unsigned int             index,
         CLxLoc_Image            &img)
 {
         [[LXtObjectID (index)|LXtObjectID]]              obj;
 
         if ([[LXx_FAIL (index)|LXx_FAIL]] (Image (index, &obj)))
                 return false;
 
         return img.take (obj);
 }
</syntaxhighlight>

<span id="C41"></span>
Empty LayeredImage Python user class.

===== (41) PY: empty LayeredImage user class =====

<syntaxhighlight>
 pass
</syntaxhighlight>

<span id="C42"></span>
<span id="S1.2.7"></span>
==== Writing Layered Images ====

Layered image objects will provide an ILxLayeredImageWrite interface for writing.
{| class="wikitable"
 |-
 |AddLayer
 | This is the way a layered image is actually created, adding layers by passing in ILxImage objects.  The image object will be locked and released by the layered image, so clients may release the image after setting the layer.
 |-
 |SetType
 | Layer type and flags can be set using this function.
 |-
 |SetOffset
 | Pixel offsets for a layer are set with this function.
 |-
 |SetBlending
 | The blending parameter (or opacity) and the blending mode are set with this function. A list of modes should appear here shortly...
|}

===== (42) SDK: LayeredImageWrite::AddLayer, etc. =====

<syntaxhighlight>
         [[LXxMETHOD (index)|LXxMETHOD]]( [[LxResult (index)|LxResult]],
 AddLayer) (
         [[LXtObjectID (index)|LXtObjectID]]              self,
         [[LXtObjectID (index)|LXtObjectID]]              image,
         const char              *name,
         const char              **channelNames);
 
         [[LXxMETHOD (index)|LXxMETHOD]]( [[LxResult (index)|LxResult]],
 SetType) (
         [[LXtObjectID (index)|LXtObjectID]]              self,
         unsigned int             index,
         int                      flags,
         const char              *type);
 
         [[LXxMETHOD (index)|LXxMETHOD]]( [[LxResult (index)|LxResult]],
 SetOffset) (
         [[LXtObjectID (index)|LXtObjectID]]              self,
         unsigned int             index,
         int                      x,
         int                      y);
 
         [[LXxMETHOD (index)|LXxMETHOD]]( [[LxResult (index)|LxResult]],
 SetBlending) (
         [[LXtObjectID (index)|LXtObjectID]]              self,
         unsigned int             index,
         float                    blend,
         const char              *mode);
 
         [[LXxMETHOD (index)|LXxMETHOD]](  [[LxResult (index)|LxResult]],
 AddAttribute) (
         [[LXtObjectID (index)|LXtObjectID]]              self,
         const char              *name,
         const char              *type,
         int                     *index);
 
</syntaxhighlight>

<span id="C43"></span>
===== (43) SDK: LXu_LAYEREDIMAGEWRITE define =====

<syntaxhighlight>
 #define [[LXu_LAYEREDIMAGEWRITE (index)|LXu_LAYEREDIMAGEWRITE]]   "79D28886-9652-4A76-9AA7-1B1E4D553DCD"</syntaxhighlight>

<span id="C44"></span>
===== (44) SDK: empty LayeredImageWrite User Class =====

<span id="C45"></span>
Empty LayeredImageWrite Python user class.

===== (45) PY: empty LayeredImageWrite user class =====

<syntaxhighlight>
 pass
</syntaxhighlight>

<span id="C46"></span>
<span id="S1.2.8"></span>
==== Tile Image Interface ====

The tiled image interface provides a way for clients to implement images using tile trees. Tiles will themselves simply be images, so we can manage a global cache of them internally rather than depending on each implementation to manage an internal cache.

A tile tree is a collection of "levels", which are intended to be images of decreasing size. Each image level is broken into tiles, which allows us to only work on small portions of the image instead of loading an entire image. Typically, the image levels decrease in size by power of two.

For example, one dimension of a normal tile tree of an image with size 1024x1024, and tiles of size 256x256, would look like this:

Level 2     _ Level 1    _ _ Level 0  _ _ _ _

Where each _ represents a tile.

One thing to note is that the meaning of "level" is reverse from ImageLevelSample; level 0 is the base of the tile tree, where each tile is the original size, and the highest value of level will have a single tile.

Implementations of the TileImage interface are only required to be able to get the tiles at level 0; they may require the clients to generate tiles above level 0 by resizing the tiles below them.
{| class="wikitable"
 |-
 |LevelCount
 | LevelCount returns the number of levels in the tile tree.
|}

===== (46) SDK: TileImage::LevelCount =====

<syntaxhighlight>
         [[LXxMETHOD (index)|LXxMETHOD]]( unsigned,
 LevelCount) (
         [[LXtObjectID (index)|LXtObjectID]]              self);
</syntaxhighlight>

<span id="C47"></span>
{| class="wikitable"
 |-
 |GetTile
 | GetTile is the direct way of getting a tile from the tile image. In general, this will be loaded directly from the file off disk. Tiles will simply be an ILxImageID. These should be created by the implementation, and the client will release them.
|}

It should return LXe_OK if it's okay, but LXe_OUTOFBOUNDS if the tile isn't in the image.

===== (47) SDK: TileImage::GetTile =====

<syntaxhighlight>
         [[LXxMETHOD (index)|LXxMETHOD]]( [[LxResult (index)|LxResult]],
 GetTile) (
         [[LXtObjectID (index)|LXtObjectID]]               self,
         unsigned int              level,
         unsigned int              tileX,
         unsigned int              tileY,
         void                    **ppvObj);
</syntaxhighlight>

<span id="C48"></span>
{| class="wikitable"
 |-
 |GetTileSize
 | GetTileSize will determine the width and height of a given tile, and place it in *width and *height. For a given TileImage, these will usually be constant and equal except for boundary tiles.
|}

It should return LXe_OK if it's okay, but LXe_OUTOFBOUNDS if the tile isn't in the image.

===== (48) SDK: TileImage::GetTileSize =====

<syntaxhighlight>
         [[LXxMETHOD (index)|LXxMETHOD]]( [[LxResult (index)|LxResult]],
 GetTileSize) (
         [[LXtObjectID (index)|LXtObjectID]]              self,
         unsigned int             level,
         unsigned int             tileX,
         unsigned int             tileY,
         unsigned int            *width,
         unsigned int            *height);
</syntaxhighlight>

<span id="C49"></span>
{| class="wikitable"
 |-
 |GetLevelSize
 | GetLevelSize will determine the size of an entire level both in pixel counts and tile counts. It will place the former in *width and *height, and the latter in *tilesWidth and *tilesHeight.
|}

Any of the pointers should be able to be NULL, if the caller only wants to get the tile dimensions, for instance. It should return LXe_OUTOFBOUNDS if the level isn't in the image.

===== (49) SDK: TileImage::GetLevelSize =====

<syntaxhighlight>
         [[LXxMETHOD (index)|LXxMETHOD]]( [[LxResult (index)|LxResult]],
 GetLevelSize) (
         [[LXtObjectID (index)|LXtObjectID]]              self,
         unsigned int             level,
         unsigned int            *width,
         unsigned int            *height,
         unsigned int            *tilesWidth,
         unsigned int            *tilesHeight);
</syntaxhighlight>

<span id="C50"></span>
{| class="wikitable"
 |-
 |DetermineTile
 | DetermineTile will determine which tile contains a given pixel at a given level, and place it in *tileX and *tileY.
|}

It should return LXe_OK normally, but LXe_OUTOFBOUNDS if the pixel isn't on that level.

===== (50) SDK: TileImage::DetermineTile =====

<syntaxhighlight>
         [[LXxMETHOD (index)|LXxMETHOD]]( [[LxResult (index)|LxResult]],
 DetermineTile) (
         [[LXtObjectID (index)|LXtObjectID]]              self,
         unsigned int             level,
         unsigned int             x,
         unsigned int             y,
         unsigned int            *tileX,
         unsigned int            *tileY);
</syntaxhighlight>

<span id="C51"></span>
{| class="wikitable"
 |-
 |DeterminePixel
 | DeterminePixel will take in a pixel position X and Y for a given level, and put in *adjX and *adjY the position of the pixel within the tile that contains it.
|}

It should return LXe_OK normally, but LXe_OUTOFBOUNDS if the pixel isn't on that level.

===== (51) SDK: TileImage::DeterminePixel =====

<syntaxhighlight>
         [[LXxMETHOD (index)|LXxMETHOD]]( [[LxResult (index)|LxResult]],
 DeterminePixel) (
         [[LXtObjectID (index)|LXtObjectID]]              self,
         unsigned int             level,
         unsigned int             x,
         unsigned int             y,
         unsigned int            *adjX,
         unsigned int            *adjY);
</syntaxhighlight>

<span id="C52"></span>
===== (52) SDK: LXu_TILEIMAGE, etc. defines =====

<syntaxhighlight>
 #define [[LXu_TILEIMAGE (index)|LXu_TILEIMAGE]]   "BD12D6C3-C08F-4AD1-A080-399F958D28C0"
 #define [[LXa_TILEIMAGE (index)|LXa_TILEIMAGE]]   "tileImage"</syntaxhighlight>

<span id="C53"></span>
===== (53) SDK: empty TileImage User Class =====

<span id="C54"></span>
Empty TileImage Python user class.

===== (54) PY: empty TileImage user class =====

<syntaxhighlight>
 pass
</syntaxhighlight>

<span id="C55"></span>
<span id="S1.2.9"></span>
==== Image I/O ====

Images can be loaded and saved with appropriate servers of the loader and saver class.  Loading can be opaque for disk-based access, although most loaders are currently direct, so a format, type, size and number of colors must be specified by the recognition method to allow the host to create a suitable image object to receive the data. This is done using a target interface.

===== (55) SDK: ImageLoaderTarget1::SetSize, etc. =====

<syntaxhighlight>
         [[LXxMETHOD (index)|LXxMETHOD]]( [[LxResult (index)|LxResult]],
 SetSize) (
         [[LXtObjectID (index)|LXtObjectID]]              self,
         LXtPixelFormat           type,
         unsigned                 width,
         unsigned                 height);
 
         [[LXxMETHOD (index)|LXxMETHOD]]( [[LxResult (index)|LxResult]],
 SetMap) (
         [[LXtObjectID (index)|LXtObjectID]]              self,
         unsigned                 ncolor);
</syntaxhighlight>

<span id="C56"></span>
===== (56) SDK: LXu_IMAGELOADERTARGET1 define =====

<syntaxhighlight>
 #define [[LXu_IMAGELOADERTARGET1 (index)|LXu_IMAGELOADERTARGET1]]  "9F124A7B-DFC7-42E6-977B-71AE2E33B017"</syntaxhighlight>

<span id="C57"></span>
===== (57) SDK: empty ImageLoaderTarget1 User Class =====

<span id="C58"></span>
Legacy struct, still provided for older image loaders.

===== (58) SDK: LXtImageTarget1 struct =====

<syntaxhighlight>
 LXtPixelFormat           type;
 unsigned int             w, h, ncolor;
</syntaxhighlight>

<span id="C59"></span>
The latest image loader target interface. This has two additional methods. * SetColorspaceDepth * SetColorspace

These can be used to specify more accurately which colorspaces to use for the given type.

===== (59) SDK: ImageLoaderTarget::SetSize, etc. =====

<syntaxhighlight>
         [[LXxMETHOD (index)|LXxMETHOD]]( [[LxResult (index)|LxResult]],
 SetSize) (
         [[LXtObjectID (index)|LXtObjectID]]              self,
         LXtPixelFormat           type,
         unsigned                 width,
         unsigned                 height);
 
         [[LXxMETHOD (index)|LXxMETHOD]]( [[LxResult (index)|LxResult]],
 SetMap) (
         [[LXtObjectID (index)|LXtObjectID]]              self,
         unsigned                 ncolor);
 
         [[LXxMETHOD (index)|LXxMETHOD]]( [[LxResult (index)|LxResult]],
 SetColorspaceDepth) (
         [[LXtObjectID (index)|LXtObjectID]]              self,
         unsigned                 depth);
 
         [[LXxMETHOD (index)|LXxMETHOD]]( [[LxResult (index)|LxResult]],
 SetColorspace) (
         [[LXtObjectID (index)|LXtObjectID]]              self,
         const char              *colorspace);
</syntaxhighlight>

<span id="C60"></span>
===== (60) SDK: LXu_IMAGELOADERTARGET define =====

<syntaxhighlight>
 #define [[LXu_IMAGELOADERTARGET (index)|LXu_IMAGELOADERTARGET]]   "1034861C-78C4-4BEC-9588-F1D3C0B0401A"</syntaxhighlight>

<span id="C61"></span>
===== (61) SDK: empty ImageLoaderTarget User Class =====

<span id="C62"></span>
Empty ImageLoaderTarget Python user class.

===== (62) PY: empty ImageLoaderTarget user class =====

<syntaxhighlight>
 pass
</syntaxhighlight>

<span id="C63"></span>
<span id="S1.2.10"></span>
==== Image Level Access ====

Images can present an alternate interface that allows them to be accessed as a set of levels. The levels are filtered versions of the image at different scales, and typically are arranged in power-law series. The underlying implementation may be tiled, enabling access to images that are larger than the available memory, since the image server only needs sufficient memory for a single tile. Levels can be used directly when rendering so that the only levels used are those approximating the visual scale of the image in the rendered scene.

The count returns the number of different levels in the image.

===== (63) SDK: ImageLevelSample::Count =====

<syntaxhighlight>
         [[LXxMETHOD (index)|LXxMETHOD]]( unsigned,
 Count) (
         [[LXtObjectID (index)|LXtObjectID]]              self);
</syntaxhighlight>

<span id="C64"></span>
Each resolution level should be twice the size of the previous level, starting at 1x1 pixels for level zero, although the tiled image load can pass back slightly different dimensions for each resolution level, according to the needs of the tiled format. The image may or may not provide the full image as a level, although the full image must be accessible through the required ILxImage interface.

===== (64) SDK: ImageLevelSample::GetLevelSize =====

<syntaxhighlight>
         [[LXxMETHOD (index)|LXxMETHOD]]( [[LxResult (index)|LxResult]],
 GetLevelSize) (
         [[LXtObjectID (index)|LXtObjectID]]              self,
         unsigned                 level,
         unsigned                *width,
         unsigned                *height);
</syntaxhighlight>

<span id="C65"></span>
Sampling of a level is done using an array of structures, each with a pixel position in the level and a location to receive the RGBA data in floating point format.

===== (65) SDK: LXtImageSample struct =====

<syntaxhighlight>
 unsigned                 x;
 unsigned                 y;
 LXtImageFloat           *rgba;
</syntaxhighlight>

<span id="C66"></span>
Level images provide image data at a given resolution level, for an array of image samples.

===== (66) SDK: ImageLevelSample::SampleLevel =====

<syntaxhighlight>
         [[LXxMETHOD (index)|LXxMETHOD]]( [[LxResult (index)|LxResult]],
 SampleLevel) (
         [[LXtObjectID (index)|LXtObjectID]]              self,
         unsigned                 level,
         [[LXtImageSample (index)|LXtImageSample]]          *pixel,
         unsigned                 num);
</syntaxhighlight>

<span id="C67"></span>
Pixels can be directly accessed from a given level, in either integer or floating-point RGBA format, using an x- and y-coordinate in the local coordinate system of the specified level.

===== (67) SDK: ImageLevelSample::GetPixel =====

<syntaxhighlight>
         [[LXxMETHOD (index)|LXxMETHOD]]( [[LxResult (index)|LxResult]],
 GetPixel) (
         [[LXtObjectID (index)|LXtObjectID]]              self,
         unsigned                 level,
         unsigned int             x,
         unsigned int             y,
         LXtPixelFormat           type,
         void                    *pixel);
</syntaxhighlight>

<span id="C68"></span>
Levels also support line-by-line access through a modified version of the GetLine() method, which uses a y-coordinate in the local coordinate system of the specified level. The data returned is always RGBA in floating point.

===== (68) SDK: ImageLevelSample::GetLine =====

<syntaxhighlight>
         [[LXxMETHOD (index)|LXxMETHOD]]( const LXtImageFloat *,
 GetLine) (
         [[LXtObjectID (index)|LXtObjectID]]              self,
         unsigned                 level,
         unsigned                 y,
         LXtImageFloat           *buf);
</syntaxhighlight>

<span id="C69"></span>
Empty ImageLevelSample Python user class.

===== (69) PY: empty ImageLevelSample user class =====

<syntaxhighlight>
 pass
</syntaxhighlight>

<span id="C70"></span>
===== (70) SDK: LXu_IMAGELEVELSAMPLE, etc. defines =====

<syntaxhighlight>
 #define [[LXu_IMAGELEVELSAMPLE (index)|LXu_IMAGELEVELSAMPLE]]    "79A6EA0E-9589-4D03-880C-C06A6EC6CF7D"
 #define [[LXa_IMAGELEVELSAMPLE (index)|LXa_IMAGELEVELSAMPLE]]    "imageLevelSample"</syntaxhighlight>

<span id="C71"></span>
<span id="S1.3"></span>
=== Global Service ===

Image facilities can be accessed through the SDK using a global service interface.

===== (71) SDK: ImageService::ScriptQuery, etc. =====

<syntaxhighlight>
         [[LXxMETHOD (index)|LXxMETHOD]](  [[LxResult (index)|LxResult]],
 ScriptQuery) (
         [[LXtObjectID (index)|LXtObjectID]]              self,
         void                   **ppvObj);
 
         [[LXxMETHOD (index)|LXxMETHOD]](  [[LxResult (index)|LxResult]],
 Create) (
         [[LXtObjectID (index)|LXtObjectID]]              self,
         unsigned int             width,
         unsigned int             height,
         LXtPixelFormat           type,
         unsigned int             maxIndex,
         void                   **ppvObj);
 
         [[LXxMETHOD (index)|LXxMETHOD]](  [[LxResult (index)|LxResult]],
 Duplicate) (
         [[LXtObjectID (index)|LXtObjectID]]              self,
         [[LXtObjectID (index)|LXtObjectID]]              source,
         LXtPixelFormat           type,
         void                   **ppvObj);
 
         [[LXxMETHOD (index)|LXxMETHOD]](  [[LxResult (index)|LxResult]],
 Load) (
         [[LXtObjectID (index)|LXtObjectID]]              self,
         const char              *filePath,
         void                   **ppvObj);
 
         [[LXxMETHOD (index)|LXxMETHOD]](  [[LxResult (index)|LxResult]],
 Save) (
         [[LXtObjectID (index)|LXtObjectID]]              self,
         [[LXtObjectID (index)|LXtObjectID]]              image,
         const char              *filePath,
         const char              *format,
         [[LXtObjectID (index)|LXtObjectID]]              monitor);
 
         [[LXxMETHOD (index)|LXxMETHOD]](  [[LxResult (index)|LxResult]],
 Resample) (
         [[LXtObjectID (index)|LXtObjectID]]              self,
         [[LXtObjectID (index)|LXtObjectID]]              dest,
         [[LXtObjectID (index)|LXtObjectID]]              source,
         LXtProcessHint           hint);
 
         [[LXxMETHOD (index)|LXxMETHOD]](  [[LxResult (index)|LxResult]],
 Composite) (
         [[LXtObjectID (index)|LXtObjectID]]              self,
         [[LXtObjectID (index)|LXtObjectID]]              dest,
         [[LXtObjectID (index)|LXtObjectID]]              source,
         const [[LXtFVector2 (index)|LXtFVector2]]        pos);
 
         [[LXxMETHOD (index)|LXxMETHOD]](  [[LxResult (index)|LxResult]],
 DrawLine) (
         [[LXtObjectID (index)|LXtObjectID]]              self,
         [[LXtObjectID (index)|LXtObjectID]]              image,
         const [[LXtFVector2 (index)|LXtFVector2]]        p0,
         const [[LXtFVector2 (index)|LXtFVector2]]        p1,
         const [[LXtFVector (index)|LXtFVector]]         color);
 
         [[LXxMETHOD (index)|LXxMETHOD]](  [[LxResult (index)|LxResult]],
 Kelvin2RGB) (
         [[LXtObjectID (index)|LXtObjectID]]              self,
         float                    kelvin,
         [[LXtFVector (index)|LXtFVector]]               rgbColor);
 
         [[LXxMETHOD (index)|LXxMETHOD]](  [[LxResult (index)|LxResult]],
 RGB2Kelvin) (
         [[LXtObjectID (index)|LXtObjectID]]              self,
         const [[LXtFVector (index)|LXtFVector]]         rgbColor,
         float                   *kelvin);
 
         [[LXxMETHOD (index)|LXxMETHOD]](  [[LxResult (index)|LxResult]],
 CreateCrop) (
         [[LXtObjectID (index)|LXtObjectID]]              self,
         [[LXtObjectID (index)|LXtObjectID]]              sourceImage,
         double                   x,
         double                   y,
         double                   w,
         double                   h,
         void                   **ppvObj);
</syntaxhighlight>

<span id="C72"></span>
This reads the entire image into a single buffer given the pixel format. This is just like Image::GetLine() except that it does all the lines at once.

===== (72) SDK: ImageService::ImageGetBuffer =====

<syntaxhighlight>
         [[LXxMETHOD (index)|LXxMETHOD]](  [[LxResult (index)|LxResult]],
 ImageGetBuffer) (
         [[LXtObjectID (index)|LXtObjectID]]              self,
         [[LXtObjectID (index)|LXtObjectID]]              sourceImage,
         LXtPixelFormat           type,
         void                    *buf);
</syntaxhighlight>

<span id="C73"></span>
<span id="S1.4"></span>
=== Nexus 801 ===

LaodNoCache() is the same as Load(), but the image is not added to the intenral cache. This is useful when the image is only needed once (say, because it is being loaded and resized).

===== (73) SDK: ImageService::LoadNoCache =====

<syntaxhighlight>
         [[LXxMETHOD (index)|LXxMETHOD]](  [[LxResult (index)|LxResult]],
 LoadNoCache) (
         [[LXtObjectID (index)|LXtObjectID]]              self,
         const char              *filePath,
         void                   **ppvObj);
</syntaxhighlight>

<span id="C74"></span>
===== (74) SDK: LXu_IMAGESERVICE define =====

<syntaxhighlight>
 #define [[LXu_IMAGESERVICE (index)|LXu_IMAGESERVICE]]        "03A7D258-397C-4D92-B3AF-695AD676FCF9"</syntaxhighlight>

<span id="C75"></span>
Create a new image and fill in the user's user object.

===== (75) SDK: CLxUser_ImageService::New method =====

<syntaxhighlight>
         bool
 New (
         CLxUser_Image           &image,
         unsigned int             w,
         unsigned int             h,
         LXtPixelFormat           type,
         unsigned int             maxIndex = 0)
 {
         [[LXtObjectID (index)|LXtObjectID]]              obj;
         bool                     created = false;
 
         image.clear ();
         if ([[LXx_OK (index)|LXx_OK]] (Create (w, h, type, maxIndex, &obj))) {
                 image.take (obj);
                 created = true;
         }
 
         return created;
 }
 
         bool
 NewCrop (
         CLxUser_Image           &image,
         CLxUser_Image           &sourceImage,
         double                   x,
         double                   y,
         double                   w,
         double                   h)
 {
         [[LXtObjectID (index)|LXtObjectID]]              obj;
         bool                     created = false;
 
         image.clear ();
         if ([[LXx_OK (index)|LXx_OK]] (CLxLoc_ImageService::CreateCrop (sourceImage, x, y, w, h, &obj))) {
                 image.take (obj);
                 created = true;
         }
 
         return created;
 }
 
         bool
 Load (
         CLxUser_Image           &image,
         const std::string       &filePath)
 {
         [[LXtObjectID (index)|LXtObjectID]]              obj;
         bool                     found = false;
 
         image.clear ();
         if ([[LXx_OK (index)|LXx_OK]] (CLxLoc_ImageService::Load (filePath.c_str (), &obj))) {
                 image.take (obj);
                 found = true;
         }
 
         return found;
 }
 
         bool
 LoadNoCache (
         CLxUser_Image           &image,
         const std::string       &filePath)
 {
         [[LXtObjectID (index)|LXtObjectID]]              obj;
         bool                     found = false;
 
         image.clear ();
         if ([[LXx_OK (index)|LXx_OK]] (CLxLoc_ImageService::LoadNoCache (filePath.c_str (), &obj))) {
                 image.take (obj);
                 found = true;
         }
 
         return found;
 }
 
         [[LxResult (index)|LxResult]]
 Save (
         CLxUser_Image           &image,
         const std::string       &filePath,
         const std::string       &format,
         [[ILxUnknownID (index)|ILxUnknownID]]             monitor = 0)
 {
         return CLxLoc_ImageService::Save (image, filePath.c_str (), format.c_str (), monitor);
 }
 
         [[LxResult (index)|LxResult]]
 Resample (
         CLxUser_Image           &destImage,
         CLxUser_Image           &sourceImage,
         LXtProcessHint           hint)
 {
         return CLxLoc_ImageService::Resample (destImage, sourceImage, hint);
 }
 
         [[LxResult (index)|LxResult]]
 Composite (
         CLxUser_Image           &destImage,
         CLxUser_Image           &sourceImage,
         const [[LXtFVector2 (index)|LXtFVector2]]        pos)
 {
         return CLxLoc_ImageService::Composite (destImage, sourceImage, pos);
 }
 
         [[LxResult (index)|LxResult]]
 DrawLine (
         CLxUser_Image           &image,
         const [[LXtFVector2 (index)|LXtFVector2]]        p0,
         const [[LXtFVector2 (index)|LXtFVector2]]        p1,
         [[LXtFVector (index)|LXtFVector]]               color)
 {
         return CLxLoc_ImageService::DrawLine (image, p0, p1, color);
 }
 
</syntaxhighlight>

<span id="C76"></span>
Empty Image service Python user class.

===== (76) PY: empty Service.Image user class =====

<syntaxhighlight>
 pass
</syntaxhighlight>

<span id="C77"></span>
<span id="S1.5"></span>
=== Image Compression ===

Image block codec interfaces allow an image to be compressed into a block of data which can then be included in other files, such as for thumbnails. Compress() allocates and returns a block encoding the image. Free() frees the block when the client is done. Decompress() creates an image from a block.

===== (77) SDK: ImageBlockCodec::Compress, etc. =====

<syntaxhighlight>
         [[LXxMETHOD (index)|LXxMETHOD]](  [[LxResult (index)|LxResult]],
 Compress) (
         [[LXtObjectID (index)|LXtObjectID]]              self,
         [[LXtObjectID (index)|LXtObjectID]]              image,
         unsigned char          **buf,
         int                     *size);
 
         [[LXxMETHOD (index)|LXxMETHOD]](  void,
 Free) (
         [[LXtObjectID (index)|LXtObjectID]]              self,
         unsigned char           *buf,
         int                      size);
 
         [[LXxMETHOD (index)|LXxMETHOD]](  [[LxResult (index)|LxResult]],
 Decompress) (
         [[LXtObjectID (index)|LXtObjectID]]              self,
         unsigned char           *buf,
         int                      size,
         void                   **ppvObj);
</syntaxhighlight>

<span id="C78"></span>
===== (78) SDK: LXu_IMAGEBLOCKCODEC, etc. defines =====

<syntaxhighlight>
 #define [[LXu_IMAGEBLOCKCODEC (index)|LXu_IMAGEBLOCKCODEC]]     "7960B5BA-70D3-4FAD-8CA1-BD30A7938554"
 #define [[LXa_IMAGEBLOCKCODEC (index)|LXa_IMAGEBLOCKCODEC]]     "imageBlockCodec"</syntaxhighlight>

<span id="C79"></span>
<span id="S1.6"></span>
=== Animation Creation ===

Since there's really no better place for this we'll put the simple animation interface here.  This is a very simple API for creating animations.

The LXsMOVIE_OPTIONSCOMMAND tag identifies a command that should be executed to set options for the movie saver.  It is commonly called when the user has chosen the movie saver from a file dialog, and in any other situation where the user needs to be presented with saver options before actually saving the movie.

===== (79) SDK: LXu_MOVIE, etc. defines =====

<syntaxhighlight>
 #define [[LXu_MOVIE (index)|LXu_MOVIE]]               "B7BD9F49-9400-45F1-ADEE-BFE82A1C4A65"
 #define [[LXa_MOVIE (index)|LXa_MOVIE]]               "movie" 
 #define [[LXsMOVIE_SAVESTEREO (index)|LXsMOVIE_SAVESTEREO]]     "movie.stereoscopic"
 #define [[LXsMOVIE_OPTIONSCOMMAND (index)|LXsMOVIE_OPTIONSCOMMAND]] "optionsCommand"
</syntaxhighlight>

<span id="C80"></span>
Movie creation API is pretty simple - you begin a movie, add a bunch of images in sequence, and then end it.  The movie itself lives on disk at the path specified. There are currently no flags defined, but there may be in the future.  Default format is MP4 and default framerate is 15 fps.

===== (80) SDK: Movie::BeginMovie =====

<syntaxhighlight>
         [[LXxMETHOD (index)|LXxMETHOD]](  [[LxResult (index)|LxResult]],
 BeginMovie) (
         [[LXtObjectID (index)|LXtObjectID]]              self,
         const char              *fname,
         int                      w,
         int                      h,
         int                      flags);
</syntaxhighlight>

<span id="C81"></span>
Before adding any frames, you can change the framerate from the default of 15 with following method.

===== (81) SDK: Movie::SetFramerate =====

<syntaxhighlight>
         [[LXxMETHOD (index)|LXxMETHOD]](  [[LxResult (index)|LxResult]],
 SetFramerate) (
         [[LXtObjectID (index)|LXtObjectID]]              self,
         int                      frate);
</syntaxhighlight>

<span id="C82"></span>
Adding an image is straightforward.  Do this in sequence.

===== (82) SDK: Movie::AddImage =====

<syntaxhighlight>
         [[LXxMETHOD (index)|LXxMETHOD]](  [[LxResult (index)|LxResult]],
 AddImage) (
         [[LXtObjectID (index)|LXtObjectID]]              self,
         [[LXtObjectID (index)|LXtObjectID]]              image);
</syntaxhighlight>

<span id="C83"></span>
When done adding images, call this to finalize the movie and write it to disk.

===== (83) SDK: Movie::EndMovie =====

<syntaxhighlight>
         [[LXxMETHOD (index)|LXxMETHOD]](  [[LxResult (index)|LxResult]],
 EndMovie) (
         [[LXtObjectID (index)|LXtObjectID]]              self);
</syntaxhighlight>

<span id="C84"></span>
Adding an audio track. This must be called after adding all images before EndMove.

===== (84) SDK: Movie::AddAudio =====

<syntaxhighlight>
         [[LXxMETHOD (index)|LXxMETHOD]](  [[LxResult (index)|LxResult]],
 AddAudio) (
         [[LXtObjectID (index)|LXtObjectID]]              self,
         [[LXtObjectID (index)|LXtObjectID]]              audio);
</syntaxhighlight>

[[Category:Headers]]
[[Category:Autogenerated]]