Your Ad Here

API Guide

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:

• Overview
• About entry points
• Mandatory entry points
• Optional entry points
• Library Functions
• Capability settings
• Data structures
• Compiling your plug-in

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.

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.

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.

Example

char *version = IMF_PROTOCOL_CURRENT;

imageKey

Definition

char *imageKey

Description

This entry point specifies a unique key to identify your plug-in.

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.

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:

1. 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.
2. 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 );

3. 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;

4. 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.
5. If your file format defines input capabilities, extract those from imf->info.settings. (See IMF_CAPABILITY for details.)
6. 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.

7. 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 );

8. Return TRUE if your function successfully opened and read the image file header, and FALSE if an error occurred.

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:

1. 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).
2. 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.

3. 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:

1. Close the image file.
2. 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.
3. 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 scanline write routines to imf.
• Allocate private data defining the file descriptor, etc., and associate them with imf->data.

Detailed steps are as follows:

1. 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.
2. Use imf->info and imf->info.image[0] to extract attributes about the file being written.
3. 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;

4. Specify the image access routines in imf->scan and imf->close.
5. If your file format defines output capabilities, extract those from imf->info.settings. (See IMF_CAPABILITY for details.)
6. Write the file header and look-up table, if defined.
7. 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.

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:

1. 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).
2. 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.

3. 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.

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

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

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

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

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

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

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;