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.