Appendix F: Adding Image Plug-ins

Maya features an external plug-in module mechanism that lets you create your own image file translators. This system is specific for adding new image types to Maya and is different from the Maya API. These plug-in modules are available whenever you start your application. You can access them through the list of image file types presented where you access image files.

Plug-in image modules are implemented as dynamically shared objects (DSOs or DLLs), and can be written using C or C++. You only need to implement the algorithms that read and write the image files; the user interface and flow control are implicitly handled by Maya.

This document describes the protocol for writing an image plug-in module. It does not describe how to support multiple-frame or movie files. Sample code is provided in the image subdirectory of the Developer’s Kit.

This section discusses the following:

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’s 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.

Overview

Maya invokes functions from your image plug-in primarily to read and write image files. One of the places where this can happen is in the rendering window. In this window, you can choose to save your image as a certain format. In addition, you can load an existing rendering image into this window. You are able to select a custom format that you have defined for the read and write operations of this window.

About entry points

Each plug-in must have a defined number of entry points.Maya uses these entry points to determine which features the image plug-in supports.

Some entry points are variables and others are functions. For example, the name of the plug-in is defined by the variable entry point imageName, and the function that opens an image file for reading is defined by the function entry point imageReadOpen.

Some entry points are required, while others are optional. The mandatory entry points are described in the next section. Optional entry points are described in "Optional entry points."

Tip

For your plug-in to be compatible with Maya, you only need to implement the mandatory entry points. The optional entry points of your plug-in may not be invoked by Maya, and therefore are not required.

Mandatory entry points

The following entry points must be defined:

program
type
version
imageKey
imageIsFile
imageName
imageReadOpen and its associated look-up table reading, scanline reading, and close functions (unless your plug-in cannot read as specified by the imageAccess entry point).
imageWriteOpen and its associated scanline writing and close functions (unless you specify otherwise with the imageAccess entry point).

If a mandatory entry point is omitted, the plug-in will not be loaded, and its name will not appear in any menu.

program

Definition: char *program
Description: This entry point specifies the applications that can use the plug-in. This should be Wavefront so that all of your applications can read and write image files supported by this plug-in.

Note
Definition of this entry point is mandatory.
Example: char *program = "Wavefront";

type

Definition: char *type
Description: This entry point denotes the type of plug-in that is being built. A Maya image file plug-in is of type image.

Note
Definition of this entry point is mandatory.
Example: char *type = "image";

version

Definition: char *version
Description: This entry point denotes the version of the protocol for which the plug-in was written. Always use IMF_PROTOCOL_CURRENT.

Note
Definition of this entry point is mandatory.
Example: char *version = IMF_PROTOCOL_CURRENT;

imageKey

Definition: char *imageKey
Description: This entry point specifies a unique key to identify your plug-in.

Note
Definition of this entry point is mandatory.
Example: char *imageKey = "myFormat";

imageName

Definition: char *imageName
Description: This entry point defines the name of your plug-in as displayed in menus. Names should be unique so users can distinguish between them.

Note
Definition of this entry point is mandatory.
Example: char *imageName = "My Image Format";

imageReadOpen

Definition

int imageReadOpen

(

IMF_OBJECT *imf

}

Parameter	Type	Description
imf	Modified	Image File Header
Return Value		IMF_C_NORMAL if the image was successfully opened; IMF_C_ if an error occurred.

Description

This function is called when a file is to be opened for reading.

The imf parameter contains all of the information necessary for the reading of the file. Before calling imageReadOpen, it contains the filename. After executing this routine, it must also contain pointers to the routines which access the file, information about the size and other attributes of the image being read, buffers to read scanlines of the image into, etc.

The basic steps to writing this function are as follows:

Open the file.
Read the header from the file. If the file includes a look-up table, read it at this time.
Assign the close, scanline read, and LUT read routines into imf.
Define the parameters of the image in imf->info.image[0].
Allocate buffers to contain the scanlines.
Allocate private data defining the file descriptor, etc., and associate them with imf->data.
Some image files may contain multiple images, e.g., the full image and a thumbnail representation. For this discussion, we will assume that you will only be reading the main image from such files.

The detailed steps are as follows:

If the filename is not fully qualified, complete it. Then, open the specified file. Continue only if the open was successful. If it fails, you must generate a message using ERR_printf, set imf__err to IMF_C_CANNOT_OPEN, and return FALSE.
Set the image count to be 1, and allocate and initialize one image structure to contain information about this image:
```
imf->info.count = 1;
imf->info.image = malloc( sizeof( IMF_IMAGE ) );
(void) imf__init_ifd( imf );
```
Save the format-specific information describing the file in your own data structure allocated using malloc. This private data structure can contain items like the current file descriptor, last scanline read, active window, etc.:
```
private = malloc( sizeof( PRIVATE ) );
private->... = ...;
imf->data = malloc( sizeof( POINTER ) );
imf->data[0] = private;
```
Assign your image access routines to imf->scan and imf->close. If your image file contains a look-up table, also specify the routine that reads the look-up table in imf->lut_read.
If your file format defines input capabilities, extract those from imf->info.settings. (See IMF_CAPABILITY for details.)
Read the header information from the file, and store this in your private data structure. You must also define various fields in the imf->info and imf->info.image[0] data structures.
In the imf->info structure, set the lut_exists field according to whether the image has a look-up table.

You can also set program, machine, user, date, time, frame number, job_num, and chromaticity information (red_pri, green_pri, blue_pri, white_pt) if these are stored in the file itself.

You must also set all of the fields in imf->info.image[0]. The aux_format, aux_count, aux_type, and aux_bits fields refer to z channel information. The field curve.gamma needs to be set to either the gamma defined in your file, or the default gamma by calling IMF_def_input_gamma.

Allocate a scanline buffer into which your scanline reading routine reads a row of pixels:

private_data_ptr->buffer = IMF_chan_alloc(
imf->info.image, image_width,
imf->info.key, NULL );

Return TRUE if your function successfully opened and read the image file header, and FALSE if an error occurred.
Note
Definition of this entry point is mandatory.

Scanline reading function

Definition

int your_scan_read_func

(

POINTER data,

int scan,

POINTER **line_buff

)

Parameter	Type	Description
data	Input	The private data associated with your image.
scan	Input	The scanline to read.
line_buff	Output	The scanline buffer allocated in imageReadOpen, containing the row of pixels read.
Return Value		IMF_C_BAD_SCAN if scan is outside the image; IMF_C_NORMAL if the scanline was successfully read; and IMF_C_READ_ERR if an error occurred.

Description

This function is called by Maya to read a scanline from your image file. Image files are read according to the image's orientation, either from bottom to top, or from top to bottom.

Follow these steps to create your scanline reading function:

Read the specified scanline. The scanline number is based on bottom-to-top ordering. For example, if your image size is 480 lines, and your orientation is IMF_C_TOP_LEFT, the scanlines are read in the order 479 (top), 478 (second from top), 477, ... 0 (bottom). If the ordering is IMF_C_BOT_LEFT, they are read in the order 0 (bottom), 1 (second from bottom), 2, ... 479 (top).
Transfer the scanline into the buffer allocated in imageReadOpen. The buffer allocated by IMF_chan_alloc contains 8-, 16-, or 32-bit unsigned numbers, according to the number of bits per channel in the file. (The number of bits per channel is rounded up to the nearest number above.)
Each component of the scanline is stored in a separate contiguous buffer. These are returned in the parameter line_buff, which is an array of pointers to the components that you allocated:

/*

* Unsigned char's are used for 1 to 8-bit values;

* unsigned short's, for 8 to 16-bit values;

* unsigned long's, for 17 to 32-bit values.

*/

*line_buff = data->buffer;

pr = (unsigned char *) data->buffer[0];

pg = (unsigned char *) data->buffer[1];

pb = (unsigned char *) data->buffer[2];

pm = (unsigned char *) data->buffer[3];

for ( i = 0; i < data->image_width; ++i )

{

*(pr++) = red_values[i];

*(pg++) = green_values[i];

*(pb++) = blue_values[i];

*(pm++) = matte_values[i];

}

If the file contains a look-up table, you must still return RGB data, and not the indexes into the look-up table, in line_buff.
Return IMF_C_BAD_SCAN, IMF_C_NORMAL, or IMF_C_READ_ERR as appropriate.
Your scanline reading function must not expect to read the last scanline of the image because Maya may skip the last few scanlines if they do not need to be read. Your plug-in must allow Maya to call your close function at any time after calling imageReadOpen.

Close function

Definition

int your_close_func

(

IMF_OBJECT *imf

)

Parameter	Type	Description
imf	Modified	Image file descriptor.
Return Value		IMF_C_NORMAL if file closing and memory de-allocation was successful; IMF_C_failure_code if error occurred (for example IMF_C_WRITE_ERR).

Description

This function is called whenever Maya is finished reading or writing your image file. Follow these steps to create your close function:

Close the image file.
Deallocate any private data pointed to by imf->data and set imf->data to NULL. To deallocate the scanline buffer allocated in either imageReadOpen or imageWriteOpen, use IMF_chan_free.
Return IMF_C_NORMAL if file closing and memory clean-up is successful, and IMF_C_failure_code if not.

imageWriteOpen

Definition

int imageWriteOpen

(

IMF_OBJECT *imf

)

Parameter	Type	Description
imf	Modified	Image file descriptor.
Return Value		TRUE if the image was successfully opened; FALSE if an error occurred.

Description

This function is called when a file is to be opened for writing.

The imf parameter contains all of the information necessary to write the file. Before calling imageWriteOpen, it contains the filename. After executing this routine, it must also contain pointers to the routines that access the file, information about the size and other attributes of the image being written, etc.

The basic steps to creating this function are as follows:

Open the file.
Write the header. If the file includes a look-up table, you may need to write it at this time.
Assign the close and scanlinewrite routines to imf.
Allocate private data defining the file descriptor, etc., and associate them with imf->data.

Detailed steps are as follows:

Open the specified file. Continue only if the open was successful. If it fails, you must generate a message using ERR_printf, set imf__err to IMF_C_CANNOT_OPEN, and return FALSE.
Use imf->info and imf->info.image[0] to extract attributes about the file being written.
Save the format-specific information describing the file in your own data structure allocated using malloc. This private data structure can contain items like the current file descriptor, active window, etc.:
```
private = malloc( sizeof( PRIVATE ) );
private->... = ...;
imf->data = malloc( sizeof( POINTER ) );
imf->data[0] = private;
```
Specify the image access routines in imf->scan and imf->close.
If your file format defines output capabilities, extract those from imf->info.settings. (See IMF_CAPABILITY for details.)
Write the file header and look-up table, if defined.
Return IMF_C_NORMAL if your function successfully opened and read the image file header. Return IMF_C_failure_code if an error occurred.
In the event of a failed attempt at opening an image file, Maya calls imf__free_obj( imf ) to free the IMF_OBJECT passed to imageWriteOpen. Therefore, you must not call imf__free_obj in your error-handling code.

Note
Definition of this entry point is mandatory.

Scanline writing function

Definition

int your_scan_write_func

(

POINTER data,

int scan,

POINTER *line_buff

)

Parameter	Type	Description
data	Input	The private data associated with your image.
scan	Input	The scanline to be written.
line_buff	Output	Buffer containing the pixels for the current scanline.
Return Value		IMF_C_BAD_SCAN if scan is outside the image; IMF_C_NORMAL if the scanline is successfully written; and IMF_C_WRITE_ERR if an error occurs.

Description

This function is called by Maya to write a scanline to your image file. Image files are written according to the image's orientation, either from bottom to top, or from top to bottom.

Follow these steps to create your scanline writing function:

Write the specified scanline. The scanline number is based on bottom-to-top ordering. For example, if your image size is 480 lines, and your orientation is IMF_C_TOP_LEFT, the scanlines are written in the order 479 (top), 478 (second from top), 477, ... 0 (bottom). If the ordering is IMF_C_BOT_LEFT, they are written in the order 0 (bottom), 1 (second from bottom), 2, ... 479 (top).
Retrieve the red color channel information from line_buff[0], green from line_buff[1], and blue from line_buff[2], where line_buff is the scanline buffer passed in by Maya. If there is a matte channel, it is in line_buff[3]. The z channel, if it exists, is in line_buff[4]. The pixels are stored from left to right.
```
pr = (unsigned char *) line_buff[0];
pg = (unsigned char *) line_buff[1];
pb = (unsigned char *) line_buff[2];
pm = (unsigned char *) line_buff[3];
for ( i = 0; i < data->image_width; ++i )
{
     red_values[i] = *(pr++);
     green_values[i] = *(pg++);
     blue_values[i] = *(pb++);
     matte_values[i] = *(pm++);
}
```
Convert the values to the format used by your file format and write the scanline to the file.
Return IMF_C_BAD_SCAN, IMF_C_NORMAL, or IMF_C_READ_ERR.

Optional entry points

A number of additional entry points exist. If an optional entry point is not defined, a default value is used. Some optional entry points are ignored unless the feature is supported by your file format.

imageAccess

Definition: unsigned int imageAccess
Description: This variable specifies the reading and writing methods that your plug-in supports. The constants described are bit fields:

IMF_C_LUT_READ indicates that your plug-in supports reading palettes from files. A LUT reading function must be defined and assigned to imf->lut_read in the imageReadOpen routine.
IMF_C_LUT_WRITE indicates that your plug-in supports writing palettes to files.
IMF_C_READ indicates that your plug-in supports the sequential reading of scanlines.
IMF_C_READ_RANDOM indicates that your plug-in supports the random reading of scanlines.
IMF_C_WRITE indicates that your plug supports the sequential writing of scanlines.
IMF_C_WRITE_RANDOM indicates that your plug-in supports the random writing of scanlines.
The default value is IMF_C_READ|IMF_C_WRITE.
Example
This example is for a file that supports look-up tables:
unsigned int imageAccess = IMF_C_LUT_READ | IMF_C_LUT_WRITE | IMF_C_READ | IMF_C_WRITE;

imageBitsPerChannel

Definition: unsigned int imageBitsPerChannel
Description: This variable defines the number of bits per color channel that are supported. This applies to the red, green, and blue channels only.

This variable is a bit field, used to define the number of bits (from 1 to 32) that each channel can support. Setting the lowest bit indicates that the format supports 1 bit per color channel; setting the highest bit indicates that the format supports 32 bits per color channel. You need to set bits in this variable according to all of the bits-per-channel that your format supports.

The default value is 0x00000080, or 8 bits per color channel.
Example: The first example supports only 8 bits per color channel; the second example supports 8, 10, and 16 bits.

unsigned int imageBitsPerChannel = 0x00000080;

unsigned int imageBitsPerChannel = 0x00008280;

imageBitsPerMatte

Definition: unsigned int imageBitsPerMatte;
Description: This variable is identical to imageBitsPerChannel, except that it describes the number of bits supported by the matte channel.

The default value is 0x00000000, which means that the format does not support matte channels.
Example: The first example supports only 8 bits in the matte channel; the second example supports 8, 10, and 16 bits.

unsigned int imageBitsPerMatte = 0x00000080;

unsigned int imageBitsPerMatte = 0x00008280;

imageBitsPerZChannel

Definition: unsigned int imageBitsPerZChannel
Description: This variable is identical to imageBitsPerChannel, except that it describes the number of bits supported by the z channel.

The default value is 0x00000000, which means that the format does not support z channels.
Example: The first example supports only 8 bits in the z channel; the second example supports 8, 10, and 16 bits.

unsigned int imageBitsPerZChannel = 0x00000080;

unsigned int imageBitsPerZChannel = 0x00008280;

imageCapability

Definition

void imageCapability

(

IMF_CAPABILITY **capabilities,

int *num_input,

int *num_output,

int *total

)

Parameter	Type	Description
capabilities	Output	Returns a pointer to the capabilities for this file type.
num_input	Output	The number of capabilities applicable to file reading.
num_output	Output	The number of capabilities applicable to file writing.
total	Output	The total number of capabilities.

Description

This function is called during initialization when Maya determines the capabilities to display in its menus. For more information on capabilities, see IMF_CAPABILITY.

Example

This generic code fragment loops through your plug-in's list of capabilities:

int i;

*capabilities = your_capabilities;

for ( *num_input = *num_output = *total = i = 0;

i < number_elements_in( your_capabilities );

++i )

{

if ( your_capabilities[i].imc_when_avail

& IMF_CAPABILITY_WHEN_INPUT )

{

++( *num_input );

}

if ( your_capabilities[i].imc_when_avail

& IMF_CAPABILITY_WHEN_OUTPUT )

{

++( *num_output );

}

if ( your_capabilities[i].imc_when_avail

& ( IMF_CAPABILITY_WHEN_INPUT

| IMF_CAPABILITY_WHEN_OUTPUT ) )

{

++( *total );

}

imageDescription

Definition: char *imageDescription
Description: This variable is a string used to provide a more detailed description of the file format. It augments the imageName when displayed in menus.

The default value is NULL, which means that no additional description exists.
Example: char *imageDescription = "Version 2";

imageDone

Definition: void imageDone( void )
Description: This optional routine is called when you exit Maya. If your plug-in requires special licensing, you should also release the license at this point.

imageExtension

Definition: char *imageExtension
Description: This variable defines the default extension when generating filenames for your plug-in. It must include the preceding period. The default value is NULL, which indicates that the format does not typically use an extension.

This variable is used to determine the format of the image file when the file type is defined as Determine from extension.
Example: char *imageExtension = ".gif";

imageFormatString

Definition: char *imageFormatString
Description: This variable defines the default format of the filename, and includes the root name, frame number, and extension. It uses the same notation as sprintf.

The first %s in the variable is used for the root name; the %d is used for the frame number; and the second %s is used for the extension. The default value is %s.%04.4d.%s.
Example: This example defines a syntax where the root name is immediately followed by the non-zero padded frame number, and then followed by the period-separated extension.

char *imageFormatString = "%s%d.%s";

imageHardLinkDuplicates (UNIX only)

Definition: BOOLEAN imageHardLinkDuplicates
Description: This variable indicates whether Maya should create hard links to identical files that are created in a sequence. For example, if image.1.ext, image.2.ext, and image.3.ext are identical, setting this variable to TRUE allows Maya to create only one file, but make hard links from the other two files to the newly created one. If this variable were FALSE, three separate but identical files would be created.

The default value is TRUE.
Example: BOOLEAN imageHardLinkDuplicates = FALSE;

imageInit

Definition: int imageInit( void )
Description: If defined, this routine is invoked before your plug-in’s functionality is added to Maya. If the return value is TRUE, the plug-in is loaded as usual. However, if it returns FALSE, the plug-in is unloaded.

This initialization routine can be used in conjunction with the imageDone routine to provide a means of opening and closing any licensing schemes that you implement. If the plug-in offers multiple language support, this routine can be used to internationalize any strings. You can also set default values for imageExtension and imageNameSyntax within this call.

imageIsFile

Definition

BOOLEAN imageIsFile(

char *fn,

FILE *fp

}

Parameter	Type	Description
fn	char*	Filename, used only if fp is NULL.
fp	FILE*	File pointer.
Return Value		TRUE if fn or fp refer to a file supported by this plug-in.

Description

Checks whether a filename or pointer matches a type supported by this plug-in.

Note

Definition of this entry point is mandatory.

Example

if ( fp == NULL )

{

fp = fopen( fn, "r" ) );

}

/* Read the header from fp and check for a match with this plug-in */

fread( &magic, 1, sizeof( magic ), fp );

return ( magic & FORMATS_MAGIC_NUMBER )

imageNameSyntax

Definition: char *imageNameSyntax
Description: This variable defines the default format of the filename, and includes the root name, frame number, and extension.

The name syntax recognizes four strings:

Name, which represents the root name of the file
Ext, which represents the extension
#, which represents the frame number
punctuation, such as period (.), comma (,), and hyphen (-)

These can be combined in any way to produce the desired filename. Each of the name, frame number, and extension can occur at most once, but the # can be repeated to pad the frame number with leading zeroes.

The default value is NULL.

This string is not recognized by Maya.

Example: This example produces a name with at least two digits used for the frame number. There is no punctuation between the name and the frame number, but a period is placed between the frame number and extension.

char *imageNameSyntax = "Name##.Ext";

imageNumberOfChannels

Definition: int imageNumberOfChannels
Description: This variable defines the maximum number of color channels that your file format supports. It does not include the matte channel. Normally, this is 3 for RGB images, and 1 for formats that support gray-scale only.

The default value is 3.
Example: int imageNumberOfChannels = 3;

imageNumberOfMattes

Definition: int imageNumberOfMattes;
Description: This variable defines the maximum number of matte, or alpha, channels that your file format supports. Normally, this is 1 if your format supports matte, and 0 otherwise.

The default value is 0.
Example: int imageNumberOfMattes = 1;

imageNumberOfZChannels

Definition: int imageNumberOfZChannels
Description: This variable defines the maximum number of z, or depth, channels that your file format supports. Normally, this is 1 if your format supports z, and 0 otherwise.

The default value is 0.
Example: int imageNumberOfZChannels = 1;

imageSupportRemoteAccess

Definition: BOOLEAN imageSupportRemoteAccess
Description: This variable defines whether your plug-in supports remote file access. If so, set this to TRUE. Otherwise, Maya will perform remote file access where possible, and remove any leading remotehost: from filenames before passing them to your plug-in.

The default value is FALSE.
Example: BOOLEAN imageSupportRemoteAccess = TRUE;

imageSupportsActiveWindow

Definition: int imageSupportsActiveWindow
Description: This variable indicates whether your format supports the notion of an active window. The default value is FALSE.
Example: int imageSupportsActiveWindow = FALSE;

Look-up table (LUT) reading function

Definition

int your_lut_read_func

(

POINTER data,

IMF_LUT **imf_lut

)

Parameter	Type	Description
data	input	The private data associated with your image.
imf_lut	output	A pointer to a newly allocated look-up table.
Return Value		TRUE if the LUT was successfully allocated and read; FALSE if an error occurred.

Description

Maya calls this function to read the image file's color look-up table. Since LUTs usually use little space, it is recommended that they be read by imageReadOpen and stored in the private data associated with the image. This way, your_lut_read_func only needs to allocate a new IMF_LUT and copy it to the stored LUT data.

Allocate the LUT:

if ( ( *imf_lut = IMF_lut_alloc( data->your_color_map_size ) ) == NULL )
{
     return( FALSE );
}

Set (*imf_lut)->imu_maximum to the maximum value of each LUT entry. For example, if your file format stores each LUT entry as 12 bits of red, 12 bits of green, and 12 bits of blue, use 4095 for imu_maximum.
Set (*imf_lut)->imu_gamma to be the gamma of the color look-up table if it is stored in the file, or the default input gamma value using FMT_def_input_gamma. This should be the gamma that was applied to the LUT entries when they were written.
Fill in each (*imf_lut)->imu_lut[i].ile_red, (*imf_lut)->imu_lut[i].ile_green, etc. entry. See IMF_LUT for a description of the IMF_LUT structure. Each LUT entry should range from 0 to the imu_maximum entry set in step 2.
Return TRUE if successful, and FALSE if an error occurred.

Library Functions

imf__build_handle

Definition

char *imf__build_handle

(

char *path,

char *handle,

char *ext

)

Parameter	Type	Description
path	Input	The search path to use.
handle	Input	The filename.
ext	Input	The filename extension.
Return Value		The completed filename.

Description

This function constructs a filename from path, handle, and ext. Use the returned string when opening the file.

Examples

char *filename;

FILE *fp = NULL;

...

*info = &imf->info;

if ( info->handle_complete )

{

filename = info->handle;

}

else

{

filename = imf__build_handle( NULL, info->handle,

info->ext );

if ( ( fp = fopen( filename, "rb" ) ) == NULL )

{

filename = imf__build_handle( getenv(

"WF_IMG_DIR" ),

info->handle, info->ext );

}

if ( fp == NULL )

{

fp = fopen( filename, "rb" );

}

IMF_chan_alloc

Definition

POINTER *IMF_chan_alloc

(

IMF_IMAGE *image,

int res,

char *key,

int *size

)

Parameter	Type	Description
image	Input	Image information specifies the number of channels that are allocated, e.g., the number of color channels, the number of matte channels, and the number of Z channels.
res	Input	The width of a scanline, in pixels.
key	Input	The plug-in's key; used for error messages.
size	Output	Size of the allocated scanline.
Return Value		NULL if insufficient memory; otherwise, a pointer to scanline buffers.

Description

This function allocates a set of scanline buffers that are used to pass one scanline of data between Maya and your scanline reading and writing functions. The buffer is set up as an array of pointers to scanline buffers, with the first rows containing color channel data (red, green, and then blue), followed by a matte channel and a z channel (if defined by your plug-in). Call this function from your imageReadOpen routine.

IMF_chan_alloc depends on the imageBitsPerPaletteEntry, imageBitsPerChannel, imageBitsPerMatte, and imageBitsPerZChannel entry points that you define at the top of your plug-in code. If your entry point defines 1 to 8 bits per channel, then byte-sized pixels are allocated. If 9 to 16 bits per channel are defined, then 16-bit short pixels are allocated. For 17 to 32 bits per channel, 32-bit long pixels are allocated. All values are in unsigned form. Your scanline reading and writing functions must know whether to interpret channel data as 8-bit unsigned chars, 16-bit shorts, or 32-bit longs.

Example

This sample code fragment shows how to allocate and access a scanline buffer allocated by IMF_chan_alloc. There are 3 color channels with 8 bits per pixel, 1 matte channel with 12 bits per pixel, and 1 z channel with 32 bits per pixel. imf is the IMF_OBJECT structure passed into your imageReadOpen function. Note that imageWriteOpen should not call IMF_chan_alloc because the Maya application allocates the scanline buffer passed into the scanline writing function.

POINTER *p_buffer;

p_buffer = IMF_chan_alloc( imf->info.image,

image_width, imf->info.key, NULL);

In your scanline reading function, store data into the buffer as follows:

unsigned char *p_red = p_buffer[0];

unsigned char *p_blue = p_buffer[1];

unsigned char *p_green = p_buffer[2];

unsigned short *p_matte = p_buffer[3];

unsigned long *p_z = p_buffer[4];

for ( i = 0; i < image_width; ++i )

{

p_red[i] = red_values[i];

p_blue[i] = blue_values[i];

p_green[i] = green_values[i];

p_matte[i] = matte_values[i];

p_z[i] = z_values[i];

}

Your scanline writing function should access the buffer in a similar way.

Related Functions

IMF_chan_free

Definition

int IMF_chan_free

(

POINTER *chan_data

)

Parameter	Type	Description
chan_data	Modified	The address of a pointer to a scanline buffer allocated by IMF_chan_alloc.
Return Value		Unused.

Description

This function de-allocates a set of scanline buffers that were previously allocated by IMF_chan_alloc.

Example

If data->buffer points to your scanline buffer, free the buffer using:

IMF_chan_free( data->buffer );

Related Functions

IMF_chan_alloc

imf__free_obj

Definition

int imf__free_obj

(

IMF_OBJECT *imf

)

Parameter	Type	Description
imf	Modified	Structure storing image characteristics such as width and height.
Return Value		Unused.

Description

This function de-allocates space occupied by the IMF_OBJECT structure. This function should be called in your close function.

If imf->data is not NULL, then imf__free_obj frees the space pointed to by imf->data[0] and then frees imf->data. Therefore, if you have allocated imf->data[1] or any other extra space, then your close function and your error-handling routines in imageReadOpen and imageWriteOpen must deallocate the space to avoid a memory leak.

In the event of a failed attempt at opening an image file, Maya calls imf__free_obj( imf ) to free the IMF_OBJECT passed to imageReadOpen. Therefore, you must not call imf__free_obj in your error-handling code. If you call your close function to perform the error-handling and clean-up, your close function must distinguish between a close after a failed open attempt and a close after having successfully read an image file. Your close function must call imf__free_obj only if the image file was successfully read.

Example

imf__free_obj( imf );

Related Functions

imf__init_ifd

Definition

int imf__init_ifd

(

IMF_OBJECT *imf

)

Parameter	Type	Description
imf	Modified	Structure storing image characteristics such as width and height.
Return Value		Unused.

Description

This function initializes the image file descriptor structure pointed to by imf->info.image. This function should be called in your imageReadOpen function. Note that the imf->info.image field must have been allocated by your function before invoking imf__init_ifd.

The following defines the default values of the IMF_IMAGE structure:

usage: IMF_C_GENERIC
curve.usage: IMF_C_CORRECTION_GAMMA
curve.gamma: fmt_def_gamma
curve.info.name: NULL
curve.info.count: 1
curve.info.elems: 256
curve.info.type: IMF_C_INTEGER
curve.info.bits: LOG( fmt__gamma_tab_res ) / LOG( 2.0 )
curve.response: NULL
aspect.name: NULL
chan_format: NULL
matte_format: NULL
aux_format: NULL
index_format: NULL
chan_config: IMF_C_PLANAR_SEPARATE
chan_orient: IMF_C_BOT_LEFT
chan_count: 0
chan_type: IMF_C_INTEGER
chan_bits: 8
matte_count: 0
matte_type: IMF_C_INTEGER
matte_bits: 8
aux_count: 0
aux_type: IMF_C_INTEGER
aux_bits: 8
index_count: 0
index_type: IMF_C_INTEGER
index_bits: 8
Example

imf__init_ifd( imf );

Related Functions

imf__free_obj

Capability settings

When you implement an image plug-in, you need to decide what file format features your plug-in supports, and whether and how the user can specify them in the file browsers used to access image files. Maya automatically passes these features, called capability settings, to your image plug-in when it accesses a file. For example, when writing an image to disk, you may allow the user to select the type of compression to be used. Sometimes, your file format has no special features and does not require capability settings.

The user interface supports two pre-defined capability types:

List-presents an option menu with a list of names (strings)
Number-displays a numeric field and a thumbwheel for an unbounded number, or numeric field and a slider for a bounded number.
For more information, see imageCapability and IMF_CAPABILITY.

Data structures

IMF_CAPABILITY

Definition

typedef struct imf_capability

{

U_SHORT imc_code;

char *imc_name;

MSGCAT_DEFN imc_name_msg;

U_CHAR imc_type;

POINTER imc_value;

U_CHAR imc_when_avail;

} IMF_CAPABILITY;

Purpose

For those image files with special, type-specific parameters, use the IMF_CAPABILITY structure to define the type-specific capabilities of the driver. The capabilities are stored as an array, with one entry per capability. For example, the SGI driver has two capabilities: one for the compression mode (raw vs. RGB), and one for defining whether a matte channel should be created in the file.

Description

The following table gives the descriptions.

Field	Description
imc_code	A 16-bit number unique among all the capabilities defined in your IMF_CAPABILITY array.
imc_name	The string displayed in the user interface describing the capability.
imc_name_msg	The internationalized version of imc_name.
imc_type	The capability type. Currently, this can be either IMF_CAPABILITY_TYPE_LIST or IMF_CAPABILITY_TYPE_NUMBER.
imc_value	A pointer to either a IMF_CAPABILITY_LIST or a IMF_CAPABILITY_NUMBER structure, depending on imc_type.
imc_when_avail	Defines when this capability is valid. Set to IMF_CAPABILITY_WHEN_ALWAYS for both reading and writing images; IMF_CAPABILITY_WHEN_INPUT for reading images; or IMF_CAPABILITY_WHEN_OUTPUT for writing images.

The capabilities are generic parameters. When imageReadOpen or imageWriteOpen is called, the specific user-defined instances of the capabilities are passed in as settings. This sample code fragment shows you how to extract the meanings of these settings:

static BOOLEAN your_get_capability_settings
(
 IMF_OBJECT			*imf,
 int			*mode
)
{
     IMF_CAPABILITY			*capability;
     IMF_CAP_SETTING			*setting;
     IMF_CAP_SETTING			**settings;
     if ( ( settings = imf->info.settings ) == NULL )
     {
         return( TRUE );
     }
     for ( /* Nothing */; setting = *settings; ++settings )
     {
          /*
          * Lookup the capability by code.
          */
         	for ( capability = your__capabilities; capability->imc_name_msg.mcd_set!= 0; ++capability )
          {
              if ( capability->imc_code == setting->imcs_code )
              {
                  break;
              }
          }
          if ( capability->imc_name_msg.mcd_set == 0 )
          {
              ERR_printf( "Bad capability found." );
              return( FALSE );
          }
          switch ( capability->imc_code )
          {
              case YOUR_CAPABILITY_IMC_CODE:
                  *mode =setting->imcs_value.imcs_list;
                  break;
              case ANOTHER_CAPABILITY_IMC_CODE:
                  ...;
                  break;
              case ...:
              default:
                  ERR_printf( "Bad capability found.");
              return( FALSE );
         }
     }
     return( TRUE );
}

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