API Guide > Appendices >

# Appendix E: 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

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:

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

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

   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:

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.

  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

### 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

  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

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.