Appendix E, Part 4
Continues from Appendix E: Adding Image Plug-ins.
Library Functions
IMF_CAPABILITY_ENTRY
Definition
typedef struct imf_capability_entry
{
U_SHORT ice_code;
char *ice_name;
MSGCAT_DEFN ice_name_msg;
} IMF_CAPABILITY_ENTRY;
Purpose
This structure is used to define a single entry of a IMF_CAPABILITY_LIST.
Description
The following table gives the desciptions.
| Field | Description |
|---|
imc_code
| A 16-bit number unique among all the capability entries defined in an IMF_CAPABILITY_LIST. This number is used by your imageReadOpen and/or imageWriteOpen code to determine the list entry that was selected by the user. |
| imc_name | The character string displayed in the user interface for this list item. |
| imc_name_msg | An internationalized version of ice_name. |
IMF_CAPABILITY_LIST
Definition
typedef struct imf_capability_list
{
int icl_default;
int icl_n_entries;
IMF_CAPABILITY_ENTRY *icl_entries;
} IMF_CAPABILITY_LIST;
Purpose
When an IMF_CAPABILITY record is of type IMF_CAPABILITY_TYPE_LIST, the imc_value field points to an IMF_CAPABILITY_LIST record whose icl_entries pointer is an array of IMF_CAPABILITY_ENTRY records.
Description
The following table gives the descriptions.
| Field | Description |
|---|
icl_default
| The ice_code of the default list entry. |
| icl_n_entries | The number of entries in the list. |
| icl_entries | The list of entries. |
IMF_CAPABILITY_NUMBER
Definition
typedef struct imf_capability_number
{
float icn_default;
BOOLEAN icn_minimum_dfnd;
float icn_minimum;
BOOLEAN icn_maximum_dfnd;
float icn_maximum;
floay icn_increment;
} IMF_CAPABILITY_NUMBER;
Purpose
If the IMF_CAPABILITY record has type IMF_CAPABILITY_TYPE_NUMBER, this structure is used to define the default value and the range of values allowed for the capability.
Description
The following table gives the descriptions.
| Field | Description |
|---|
icn_default
| The default value of this number capability. |
| icn_minimum_dfnd | Denotes whether a minimum value is defined. TRUE if so, FALSE if not. |
| icn_minimum | The minimum value, applicable only if icn_minimum_dfnd is set to TRUE. |
| icn_maximum_dfnd | Denotes whether a maximum value is defined. TRUE if so, FALSE if not. |
| icn_maximum | The maximum value, applicable only if icn_maximum_dfnd is set to TRUE. |
| icn_increment | The increment used by the slider or thumbwheel. |
If icn_minimum_dfnd and icn_maximum_dfnd are both TRUE, a slider is displayed beside the text field. Otherwise, a thumbwheel is displayed.
IMF_CAP_SETTING
Definition
typedef struct imf_cap_setting
{
U_SHORT imcs_code;
union
{
float imcs_number;
int imcs_list;
} imcs_value;
} IMF_CAP_SETTING;
Purpose
This structure is used to pass the current settings of the capabilities to your plug-in when opening a file.
| Field | Description |
|---|
imcs_code
| The imc_code of the setting. |
| imcs_number | Value if the capability is an IMF_CAPABILITY_TYPE_NUMBER. |
| imcs_list | Value if the capability is an IMF_CAPABILITY_TYPE_LIST. This is a zero-based index into the list. |
IMF_IMAGE
Definition
typedef struct
{
int usage;
IMF_COLOR_RESPONSE curve;
FMT_ASPECT_INFO aspect;
WINDOW_I window;
WINDOW_I active;
int chan_config;
int chan_orient;
char *chan_format;
int chan_count;
int chan_type;
int chan_bits;
char *matte_format;
int matte_count;
int matte_type;
int matte_bits;
char *aux_format;
int aux_count;
int aux_type;
int aux_bits;
char *index_format;
int index_count;
int index_type;
int index_bits;
} IMF_IMAGE;
Purpose
IMF_IMAGE defines the contents of a single image from a file.
Description
The following table gives the descriptions.
| Field | Description |
|---|
usage
| A bit field describing the image type: IMF_C_IMAGE_ANY for any image type; IMF_C_GENERIC for a generic image (the default set by imf__init_ifd); and IMF_C_INDEX_LUT for a look-up table-based image. |
| curve | Color correction information. |
| aspect | Image aspect information. |
| window | Image window boundaries, using zero-based numbers. |
| active | Active window boundaries. |
| chan_config | Channel planarity. This field affects how scanline data is passed to the scanline reading and writing functions. There are two options available: - One of IMF_C_PLANAR_CONTIGUOUS for red, green, and blue in one large scanline buffer with values arranged in R, G, B, R, G, B, etc. order; or,
- IMF_C_PLANAR_SEPARATE for red, green, and blue in separate arrays (normally used).
|
| chan_orient | Channel orientation: IMF_C_ORIENT_BOT_LEFT for bottom-to-top ordering; or IMF_C_ORIENT_TOP_LEFT for top-to-bottom ordering. |
| chan_format | Color channel format. |
| chan_count | The number of color channels. |
| chan_type | Color channel storage type: IMF_C_INTEGER for positive integer values (the default value assigned by imf__init_ifd); IMF_C_FLOAT for single-precision float values; IMF_C_DOUBLE for double-precision double values. |
| chan_bits | Number of bits per color channel value. |
| matte_format | Matte channel format. |
| matte_count | The number of matte channels. |
| matte_type | Matte channel storage type: IMF_C_INTEGER for positive integer values (the default value assigned by imf__init_ifd); IMF_C_FLOAT for single-precision float values; IMF_C_DOUBLE for double-precision double values. |
| matte_bits | Number of bits per matte channel value. |
| aux_format | Auxiliary (z) channel format. |
| aux_count | The number of (z) auxiliary channels. |
| aux_type | Auxiliary (z) channel storage type: IMF_C_INTEGER for positive integer values (the default value assigned by imf__init_ifd); IMF_C_FLOAT for single-precision float values; IMF_C_DOUBLE for double-precision double values. |
| aux_bits | Number of bits per auxiliary (z) channel value. |
| index_format | Color index format. |
| index_count | The number of color-indexed image data channels. |
| index_type | Color-indexed data channel storage type: IMF_C_INTEGER for positive integer values (the default value assigned by imf__init_ifd); IMF_C_FLOAT for single-precision float values; IMF_C_DOUBLE for double-precision double values. |
| index_bits | Number of bits per pixel for palette indexes. |
IMF_INFO
Definition
typedef struct
{
char *key;
char *handle;
BOOLEAN handle_complete;
char *name;
char *ext;
char *desc;
char *program;
char *machine;
char *user;
char *date;
char *time;
char *filter;
char *compress;
IMF_CAP_SETTING **settings;
BOOLEAN lut_exists;
IMF_LUT *write_lut;
int job_num;
int frame;
int field;
U_LONG init_flag;
COLOR_XYZ_3F red_pri;
COLOR_XYZ_3F green_pri;
COLOR_XYZ_3F blue_pri;
COLOR_XYZ_3F white_pt;
int count;
IMF_IMAGE *image;
int track_num_frames;
float track_frame_rate;
int track_start_frame;
int num_audio_tracks;
int num_video_tracks;
} IMF_INFO;
Purpose
Contains information describing the image file.
Description
The following table gives the descriptions.
| Field | Description |
|---|
key
| The plug-in's unique identifier key. |
| handle | Filename of the image. |
| handle_complete | Denotes if handle is completely built. If FALSE, your plug-in should use imf__build_handle to build a complete filename path. |
| name | The name of the image file. |
| ext | The filename extension. |
| desc | A description of the image file type. |
| program | The program that created the image. |
| machine | The machine on which the image was created. |
| user | The user who created the image. |
| date | The creation date of the image. |
| time | The time taken to create the file. |
| filter | The filter function used by the image. |
| compress | The compression function used by the image. |
| settings | Capability settings set by the user. |
| lut_exists | TRUE if a look-up table (LUT) is used for the image data in the scanline buffers; FALSE if the data is RGB. |
| write_lut | Pointer to a LUT. Used only when writing palette-based image files. |
| job_num | Process job accounting information. |
| frame | The frame number. |
| field | Field rendering flag. |
| init_flag | Denotes whether the caller has invoked IMF_info_init. |
| red_pri | Red chroma. |
| green_pri | Green chroma. |
| blue_pri | Blue chroma. |
| white_pt | White chroma. |
| count | The number of image sub headers pointed to by the image field. |
| image | An array of image sub headers containing detailed image information. |
| track_num_frames | The number of frames in the current track. |
| track_frame_rate | The number of frames per second for the track. |
| track_start_frame | The number of the first frame in the current track. |
| num_audio_tracks | The number of audio tracks in the current file. |
| num_video_tracks | The number of video tracks in the current file. |
IMF_LUT
Definition
typedef struct imf_lut
{
IMF_LUT_ENTRY *imu_lut;
int imu_maximum;
int imu_n_entries;
float imu_gamma;
} IMF_LUT;
Purpose
This structure defines a look-up table (LUT).
Description
The following table gives the descriptions.
| Field | Description |
|---|
imu_lut
| The look-up table entries. |
| imu_maximum | The maximum value that each LUT entry can contain. |
| imu_n_entries | The number of LUT entries pointed to by imu_lut. |
| imu_gamma | The gamma value of the LUT entries. |
IMF_LUT_ENTRY
Definition
typedef struct imf_lut_entry
{
U_SHORT ile_red;
U_SHORT ile_green;
U_SHORT ile_blue;
U_CHAR ile_mode:7;
U_CHAR ile_transparent:1;
} IMF_LUT_ENTRY;
Purpose
This structure defines one entry of a look-up table.
Description
The following table gives the descriptions.
| Field | Description |
|---|
ile_red
| The red value of this entry. |
| ile_green | The green value of this entry. |
| ile_blue | The blue value of this entry. |
| ile_mode | IMF_LUT_MODE_FREE if the entry is unused; IMF_LUT_MODE_LOCKED if the entry is locked but usable; IMF_LUT_MODE_RESERVED if the entry is reserved and unusable; or IMF_LUT_MODE_USED if the entry is in use and is modifiable. |
| ile_transparent | Set to 0 if the entry is not transparent (i.e., opaque), and 1 if the entry is transparent. |
IMF_OBJECT
Definition
typedef struct imf_object
{
POINTER *data;
IMF_INFO info;
int access;
IMF_lutReadProc lut_read;
IMF_scanProc scan;
IMF_closeProc close;
IMF_playbackBindProc playback_bind;
IMF_playbackGotoProc playback_goto;
IMF_playbackPlayProc playback_play;
IMF_playbackParamsProc playback_params;
IMF_playbackStopProc playback_stop;
IMF_getFrameProc get_frame;
IMF_getRasterProc get_raster;
IMF_getRegionProc get region;
IMF_setFrameProc set_frame;
} IMF_OBJECT;
Purpose
This structure is used when calling imageReadOpen and imageWriteOpen.
Description
The following table gives the descriptions.
| Field | Description |
|---|
data
| The private data associated with your image. |
| info | Image file information. |
| access | Image access type. |
| lut_read | Function that retrieves look-up table information from an image file. |
| scan | Your scanline access function. |
| close | Image close function. |
| playback_bind | Set to NULL. |
| playback_goto | Set to NULL. |
| playback_play | Set to NULL. |
| playback_params | Set to NULL. |
| playback_stop | Set to NULL. |
| get_frame | Set to NULL. |
| get_raster | Set to NULL. |
| get_region | Set to NULL. |
| set_frame | Set to NULL. |
Compiling your plug-in
Once you have written your image file format plug-in, you need to compile it and create a shared object that can be loaded into Maya. We provide a Makefile and buildconfig in our Developer Kit for building the example using the gcc compiler. On Windows, a solution and project file is provided for building the image plug-in with Visual C++. You must first set MAYA_LOCATION before building the image plug-in example. The plug-in that is built must be copied to the $MAYA_LOCATION/bin/plug-ins/image directory before Maya has access to this new image format. Image plug-ins must be built with the compiler and linker flags we provide so that they can be loaded into Maya.