Appendix E, Part 3

Continues from Appendix E, Part 2.

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

Information on adding image plug-ins continues in part four of Appendix E