Show in Contents
Add to Favorites
Home: Autodesk Maya Online Help
Appendix E: API and Devkit limitations
Appendices
Environment Variables
Appendix F: Adding Image
Plug-ins
Maya features an external
plug-in module mechanism that lets you create your own image file
translators. This system is specific for adding new image types
to Maya and is different from the Maya API. These plug-in modules
are available whenever you start your application. You can access
them through the list of image file types presented where you access
image files.
Plug-in image modules
are implemented as dynamically shared objects (DSOs or DLLs), and
can be written using C or C++. You only need to implement the algorithms
that read and write the image files; the user interface and flow
control are implicitly handled by Maya.
This document describes
the protocol for writing an image plug-in module. It does not describe
how to support multiple-frame or movie files. Sample code is provided
in the image subdirectory of the Developer’s Kit.
This section discusses
the following:
Once you have written
your image file format plug-in, you need to compile it and create
a shared object that can be loaded into Maya. We provide a Makefile
and buildconfig in our Developer’s Kit for building the example using
the gcc compiler. On Windows, a solution and project file is provided for
building the image plug-in with Visual C++. You must first set MAYA_LOCATION
before building the image plug-in example. The plug-in that is built
must be copied to the $MAYA_LOCATION/bin/plug-ins/image directory
before Maya has access to this new image format. Image plug-ins must
be built with the compiler and linker flags we provide so that they
can be loaded into Maya.
Overview
Maya invokes functions
from your image plug-in primarily to read and write image files.
One of the places where this can happen is in the rendering window.
In this window, you can choose to save your image as a certain format. In
addition, you can load an existing rendering image into this window.
You are able to select a custom format that you have defined for
the read and write operations of this window.
About entry points
Each plug-in must have
a defined number of entry points.Maya uses these entry points to
determine which features the image plug-in supports.
Some entry points are
variables and others are functions. For example, the name of the
plug-in is defined by the variable entry point imageName, and the function that opens
an image file for reading is defined by the function entry point imageReadOpen.
Some entry points are
required, while others are optional. The mandatory entry points
are described in the next section. Optional entry points are described
in "Optional entry points."
TipFor 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:
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
-
- 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.
NoteDefinition of this
entry point is mandatory.
- Example
-
char
*program = "Wavefront";
type
- Definition
-
- Description
-
This entry point denotes
the type of plug-in that is being built. A Maya image file plug-in
is of type image.
NoteDefinition of this
entry point is mandatory.
- Example
-
version
- Definition
-
- Description
-
This entry point denotes
the version of the protocol for which the plug-in was written. Always
use IMF_PROTOCOL_CURRENT.
NoteDefinition of this
entry point is mandatory.
- Example
-
char
*version = IMF_PROTOCOL_CURRENT;
imageKey
- Definition
-
- Description
-
This entry point specifies
a unique key to identify your plug-in.
NoteDefinition of this
entry point is mandatory.
- Example
-
char
*imageKey = "myFormat";
imageName
- Definition
-
- 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.
NoteDefinition of this
entry point is mandatory.
- Example
-
char
*imageName = "My Image Format";
imageReadOpen
- Definition
-
int
imageReadOpen
(
IMF_OBJECT
*imf
}
Parameter |
Type |
Description |
imf |
Modified
|
Image File Header
|
Return Value |
|
IMF_C_NORMAL if
the image was successfully opened; IMF_C_ if
an error occurred.
|
- Description
-
This function is called
when a file is to be opened for reading.
The imf parameter contains all of the information
necessary for the reading of the file. Before calling imageReadOpen, it contains the filename.
After executing this routine, it must also contain pointers to the
routines which access the file, information about the size and other
attributes of the image being read, buffers to read scanlines of
the image into, etc.
The basic steps to writing
this function are as follows:
- Open the file.
- Read the header from the file. If the
file includes a look-up table, read it at this time.
- Assign the close, scanline read, and LUT read routines into imf.
- Define the parameters of the image in imf->info.image[0].
- Allocate buffers to contain the scanlines.
- Allocate private data defining the file
descriptor, etc., and associate them with imf->data.
Some image files may
contain multiple images, e.g., the full image and a thumbnail representation.
For this discussion, we will assume that you will only be reading
the main image from such files.
The detailed steps are
as follows:
- If the filename is not fully qualified,
complete it. Then, open the specified file. Continue only if the
open was successful. If it fails, you must generate a message using ERR_printf, set imf__err to IMF_C_CANNOT_OPEN, and return FALSE.
- Set the image count to be 1, and allocate
and initialize one image structure to contain information about
this image:
imf->info.count = 1;
imf->info.image = malloc( sizeof( IMF_IMAGE ) );
(void) imf__init_ifd( imf );
- Save the format-specific information
describing the file in your own data structure allocated using malloc. This private data structure
can contain items like the current file descriptor, last scanline
read, active window, etc.:
private = malloc( sizeof( PRIVATE ) );
private->... = ...;
imf->data = malloc( sizeof( POINTER ) );
imf->data[0] = private;
- Assign your image access routines to imf->scan and imf->close.
If your image file contains a look-up table, also specify the routine
that reads the look-up table in imf->lut_read.
- If your file format defines input capabilities,
extract those from imf->info.settings.
(See
IMF_CAPABILITY for
details.)
- Read the header information from the
file, and store this in your private data structure. You must also
define various fields in the imf->info and imf->info.image[0] data structures.
In the imf->info structure, set the lut_exists field according to whether
the image has a look-up table.
You can also set program, machine, user, date, time, frame number, job_num, and chromaticity information
(red_pri, green_pri, blue_pri, white_pt)
if these are stored in the file itself.
You must also set all
of the fields in imf->info.image[0].
The aux_format, aux_count, aux_type,
and aux_bits fields
refer to z channel information. The field curve.gamma needs
to be set to either the gamma defined in your file, or the default
gamma by calling IMF_def_input_gamma.
- Allocate a scanline buffer into which
your scanline reading routine reads a row of pixels:
private_data_ptr->buffer = IMF_chan_alloc(
imf->info.image, image_width,
imf->info.key, NULL );
- Return TRUE if
your function successfully opened and read the image file header,
and FALSE if an error
occurred.
NoteDefinition of this
entry point is mandatory.
Scanline reading function
- Definition
-
int
your_scan_read_func
(
POINTER
data,
int
scan,
POINTER
**line_buff
)
Parameter |
Type |
Description |
data |
Input
|
The private data associated with
your image.
|
scan |
Input |
The scanline to read.
|
line_buff |
Output |
The scanline buffer allocated in imageReadOpen, containing the row of
pixels read.
|
Return Value |
|
IMF_C_BAD_SCAN if
scan is outside the image; IMF_C_NORMAL if
the scanline was successfully read; and IMF_C_READ_ERR if
an error occurred.
|
- Description
-
This function is called
by Maya to read a scanline from your image file. Image files are read
according to the image's orientation, either from bottom to top,
or from top to bottom.
Follow these steps to
create your scanline reading function:
- Read the specified scanline. The scanline
number is based on bottom-to-top ordering. For example, if your
image size is 480 lines, and your orientation is IMF_C_TOP_LEFT, the scanlines are read
in the order 479 (top), 478 (second from top), 477, ... 0 (bottom).
If the ordering is IMF_C_BOT_LEFT, they
are read in the order 0 (bottom), 1 (second from bottom), 2, ...
479 (top).
- Transfer the scanline into the buffer
allocated in imageReadOpen.
The buffer allocated by IMF_chan_alloc contains
8-, 16-, or 32-bit unsigned numbers, according to the number of
bits per channel in the file. (The number of bits per channel is
rounded up to the nearest number above.)
Each component of the
scanline is stored in a separate contiguous buffer. These are returned
in the parameter line_buff, which
is an array of pointers to the components that you allocated:
/*
*
Unsigned char's are used for 1 to 8-bit values;
*
unsigned short's, for 8 to 16-bit values;
*
unsigned long's, for 17 to 32-bit values.
*/
*line_buff
= data->buffer;
pr
= (unsigned char *) data->buffer[0];
pg
= (unsigned char *) data->buffer[1];
pb
= (unsigned char *) data->buffer[2];
pm
= (unsigned char *) data->buffer[3];
for
( i = 0; i < data->image_width; ++i )
{
*(pr++)
= red_values[i];
*(pg++)
= green_values[i];
*(pb++)
= blue_values[i];
*(pm++)
= matte_values[i];
}
If the file contains
a look-up table, you must still return RGB data, and not the indexes
into the look-up table, in line_buff.
- Return IMF_C_BAD_SCAN, IMF_C_NORMAL, or IMF_C_READ_ERR as
appropriate.
Your scanline reading
function must not expect to read the last scanline of the image
because Maya may skip the last few scanlines if they do not need
to be read. Your plug-in must allow Maya to call your close function at
any time after calling imageReadOpen.
Close function
- Definition
-
int
your_close_func
(
IMF_OBJECT *imf
)
Parameter |
Type |
Description |
imf |
Modified
|
Image file descriptor.
|
Return Value |
|
IMF_C_NORMAL if
file closing and memory de-allocation was successful; IMF_C_failure_code if error occurred
(for example IMF_C_WRITE_ERR).
|
Description
This function is called
whenever Maya is finished reading or writing your image file. Follow
these steps to create your close function:
- Close the image file.
- Deallocate any private data pointed to
by imf->data and
set imf->data to NULL. To deallocate the scanline buffer
allocated in either imageReadOpen or imageWriteOpen, use IMF_chan_free.
- Return IMF_C_NORMAL if
file closing and memory clean-up is successful, and IMF_C_failure_code if not.
imageWriteOpen
- Definition
-
int
imageWriteOpen
(
IMF_OBJECT
*imf
)
Parameter |
Type |
Description |
imf |
Modified
|
Image file descriptor.
|
Return Value |
|
TRUE if
the image was successfully opened; FALSE if
an error occurred.
|
- Description
-
This function is called
when a file is to be opened for writing.
The imf parameter contains all of the information
necessary to write the file. Before calling imageWriteOpen,
it contains the filename. After executing this routine, it must also
contain pointers to the routines that access the file, information
about the size and other attributes of the image being written,
etc.
The basic steps to creating
this function are as follows:
- Open the file.
- Write the header. If the file includes
a look-up table, you may need to write it at this time.
- Assign the close and scanline write routines
to imf.
- Allocate private data defining the file
descriptor, etc., and associate them with imf->data.
Detailed steps are as
follows:
- Open the specified file. Continue only
if the open was successful. If it fails, you must generate a message
using ERR_printf, set imf__err to IMF_C_CANNOT_OPEN,
and return FALSE.
- Use imf->info and imf->info.image[0] to extract attributes
about the file being written.
- Save the format-specific information
describing the file in your own data structure allocated using malloc. This private data structure
can contain items like the current file descriptor, active window,
etc.:
private = malloc( sizeof( PRIVATE ) );
private->... = ...;
imf->data = malloc( sizeof( POINTER ) );
imf->data[0] = private;
- Specify the image access routines in imf->scan and imf->close.
- If your file format defines output capabilities,
extract those from imf->info.settings.
(See
IMF_CAPABILITY for
details.)
- Write the file header and look-up table,
if defined.
- Return IMF_C_NORMAL if
your function successfully opened and read the image file header.
Return IMF_C_failure_code if
an error occurred.
In the event of a failed
attempt at opening an image file, Maya calls imf__free_obj(
imf ) to free the IMF_OBJECT passed
to imageWriteOpen. Therefore,
you must not call imf__free_obj in
your error-handling code.
NoteDefinition of this
entry point is mandatory.
Scanline writing function
- Definition
-
int
your_scan_write_func
(
POINTER
data,
int
scan,
POINTER
*line_buff
)
Parameter |
Type |
Description |
data |
Input
|
The private data associated with
your image.
|
scan |
Input |
The scanline to be written.
|
line_buff |
Output |
Buffer containing the
pixels for the current scanline.
|
Return Value |
|
IMF_C_BAD_SCAN if
scan is outside the image; IMF_C_NORMAL if
the scanline is successfully written; and IMF_C_WRITE_ERR if
an error occurs.
|
- Description
-
This function is called
by Maya to write a scanline to your image file. Image files are written
according to the image's orientation, either from bottom to top,
or from top to bottom.
Follow these steps to
create your scanline writing function:
- Write the specified scanline. The scanline
number is based on bottom-to-top ordering. For example, if your
image size is 480 lines, and your orientation is IMF_C_TOP_LEFT, the scanlines are written
in the order 479 (top), 478 (second from top), 477, ... 0 (bottom).
If the ordering is IMF_C_BOT_LEFT,
they are written in the order 0 (bottom), 1 (second from bottom),
2, ... 479 (top).
- Retrieve the red color channel information
from line_buff[0], green from line_buff[1], and blue from line_buff[2], where line_buff is the scanline buffer passed
in by Maya. If there is a matte channel, it is in line_buff[3]. The z channel, if it
exists, is in line_buff[4]. The
pixels are stored from left to right.
pr = (unsigned char *) line_buff[0];
pg = (unsigned char *) line_buff[1];
pb = (unsigned char *) line_buff[2];
pm = (unsigned char *) line_buff[3];
for ( i = 0; i < data->image_width; ++i )
{
red_values[i] = *(pr++);
green_values[i] = *(pg++);
blue_values[i] = *(pb++);
matte_values[i] = *(pm++);
}
Convert the values to
the format used by your file format and write the scanline to the
file.
- Return IMF_C_BAD_SCAN, IMF_C_NORMAL, or IMF_C_READ_ERR.
Optional entry points
A number of additional
entry points exist. If an optional entry point is not defined, a
default value is used. Some optional entry points are ignored unless
the feature is supported by your file format.
imageAccess
- Definition
-
- Description
-
This variable specifies
the reading and writing methods that your plug-in supports. The constants
described are bit fields:
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
-
- 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
-
- 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
-
- 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
-
- 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
-
- 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.
NoteDefinition 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
-
- 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
-
- Description
-
This variable defines
the maximum number of matte, or alpha, channels that your file format supports.
Normally, this is 1 if your format supports
matte, and 0 otherwise.
The default value is 0.
- Example
-
int
imageNumberOfMattes = 1;
imageNumberOfZChannels
- Definition
-
int
imageNumberOfZChannels
- Description
-
This variable defines
the maximum number of z, or depth, channels that your file format supports.
Normally, this is 1 if your format supports
z, and 0 otherwise.
The default value is 0.
- Example
-
int
imageNumberOfZChannels = 1;
imageSupportRemoteAccess
- Definition
-
BOOLEAN
imageSupportRemoteAccess
- Description
-
This variable defines
whether your plug-in supports remote file access. If so, set this
to TRUE. Otherwise,
Maya will perform remote file access where possible, and remove
any leading remotehost: from
filenames before passing them to your plug-in.
The default value is FALSE.
- Example
-
BOOLEAN
imageSupportRemoteAccess = TRUE;
imageSupportsActiveWindow
- Definition
-
int
imageSupportsActiveWindow
- Description
-
This variable indicates
whether your format supports the notion of an active window. The default
value is FALSE.
- Example
-
int
imageSupportsActiveWindow = FALSE;
Look-up table (LUT) reading
function
- Definition
-
int
your_lut_read_func
(
POINTER
data,
IMF_LUT
**imf_lut
)
Parameter |
Type |
Description |
data
|
input
|
The private data associated with
your image.
|
imf_lut
|
output |
A pointer to a newly allocated
look-up table.
|
Return Value |
|
TRUE if
the LUT was successfully
allocated and read; FALSE if an error occurred.
|
- Description
-
Maya calls this function
to read the image file's color look-up table. Since LUTs usually
use little space, it is recommended that they be read by imageReadOpen and stored in the private
data associated with the image. This way, your_lut_read_func only
needs to allocate a new IMF_LUT and
copy it to the stored LUT data.
- Allocate the LUT:
if ( ( *imf_lut = IMF_lut_alloc(
data->your_color_map_size ) ) == NULL )
{
return( FALSE );
}
- Set (*imf_lut)->imu_maximum to
the maximum value of each LUT entry. For example, if your file format
stores each LUT entry as 12 bits of red, 12 bits of green, and 12
bits of blue, use 4095 for imu_maximum.
- Set (*imf_lut)->imu_gamma to
be the gamma of the color look-up table if it is stored in the file,
or the default input gamma value using FMT_def_input_gamma.
This should be the gamma that was applied to the LUT entries when
they were written.
- Fill in each (*imf_lut)->imu_lut[i].ile_red,
(*imf_lut)->imu_lut[i].ile_green,
etc. entry. See IMF_LUT for a description
of the IMF_LUT structure.
Each LUT entry should range from 0 to the imu_maximum entry
set in step 2.
- Return TRUE if
successful, and FALSE if an error
occurred.
Library Functions
imf__build_handle
- Definition
-
char
*imf__build_handle
(
char
*path,
char
*handle,
char
*ext
)
Parameter |
Type |
Description |
path |
Input
|
The search path to use.
|
handle |
Input |
The filename.
|
ext |
Input |
The filename extension.
|
Return Value |
|
The completed filename.
|
- Description
-
This function constructs
a filename from path, handle, and ext.
Use the returned string when opening the file.
- Examples
-
char
*filename;
FILE
*fp = NULL;
...
*info
= &imf->info;
if
( info->handle_complete )
{
filename
= info->handle;
}
else
{
filename
= imf__build_handle( NULL, info->handle,
info->ext
);
if
( ( fp = fopen( filename, "rb" ) ) == NULL )
{
filename
= imf__build_handle( getenv(
"WF_IMG_DIR"
),
info->handle,
info->ext );
}
}
if
( fp == NULL )
{
fp
= fopen( filename, "rb" );
}
IMF_chan_alloc
- Definition
-
POINTER
*IMF_chan_alloc
(
IMF_IMAGE *image,
int res,
char *key,
int *size
)
Parameter |
Type |
Description |
image |
Input
|
Image information specifies the
number of channels that are allocated, e.g., the number of color
channels, the number of matte channels, and the number of Z channels.
|
res |
Input |
The width of a scanline,
in pixels.
|
key |
Input |
The plug-in's key; used
for error messages.
|
size |
Output |
Size of the allocated scanline.
|
Return Value |
|
NULL if insufficient
memory; otherwise, a pointer to scanline buffers.
|
- Description
-
This function allocates
a set of scanline buffers that are used to pass one scanline of
data between Maya and your scanline reading and writing functions.
The buffer is set up as an array of pointers to scanline buffers,
with the first rows containing color channel data (red, green, and
then blue), followed by a matte channel and a z channel (if defined
by your plug-in). Call this function from your imageReadOpen routine.
IMF_chan_alloc depends
on the imageBitsPerPaletteEntry, imageBitsPerChannel, imageBitsPerMatte, and imageBitsPerZChannel entry points that
you define at the top of your plug-in code. If your entry point
defines 1 to 8 bits per channel, then byte-sized pixels are allocated.
If 9 to 16 bits per channel are defined, then 16-bit short pixels are allocated. For 17
to 32 bits per channel, 32-bit long pixels
are allocated. All values are in unsigned form.
Your scanline reading and writing functions must know whether to interpret
channel data as 8-bit unsigned chars, 16-bit shorts, or 32-bit longs.
- Example
-
This sample code fragment
shows how to allocate and access a scanline buffer allocated by IMF_chan_alloc. There are 3 color channels with
8 bits per pixel, 1 matte channel with 12 bits per pixel, and 1
z channel with 32 bits per pixel. imf is
the IMF_OBJECT structure
passed into your imageReadOpen function.
Note that imageWriteOpen should
not call IMF_chan_alloc because
the Maya application allocates the scanline buffer passed into the scanline
writing function.
POINTER
*p_buffer;
p_buffer
= IMF_chan_alloc( imf->info.image,
image_width,
imf->info.key, NULL);
In your scanline reading
function, store data into the buffer as follows:
unsigned
char *p_red = p_buffer[0];
unsigned
char *p_blue = p_buffer[1];
unsigned
char *p_green = p_buffer[2];
unsigned
short *p_matte = p_buffer[3];
unsigned
long *p_z = p_buffer[4];
for
( i = 0; i < image_width; ++i )
{
p_red[i]
= red_values[i];
p_blue[i]
= blue_values[i];
p_green[i]
= green_values[i];
p_matte[i]
= matte_values[i];
p_z[i]
= z_values[i];
}
Your scanline writing
function should access the buffer in a similar way.
- Related Functions
-
IMF_chan_free
- Definition
-
int
IMF_chan_free
(
POINTER *chan_data
)
Parameter |
Type |
Description |
chan_data
|
Modified
|
The address of a pointer
to a scanline buffer allocated by IMF_chan_alloc.
|
Return Value |
|
Unused.
|
- Description
-
This function de-allocates
a set of scanline buffers that were previously allocated by IMF_chan_alloc.
- Example
-
If data->buffer points
to your scanline buffer, free the buffer using:
IMF_chan_free( data->buffer );
- Related Functions
-
imf__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
-
- Related Functions
-
imf__init_ifd
- Definition
-
int
imf__init_ifd
(
IMF_OBJECT
*imf
)
Parameter |
Type |
Description |
imf
|
Modified
|
Structure storing image characteristics
such as width and height.
|
Return Value |
|
Unused.
|
- Description
-
This function initializes
the image file descriptor structure pointed to by imf->info.image. This function should
be called in your imageReadOpen function.
Note that the imf->info.image field
must have been allocated by your function before invoking imf__init_ifd.
The following defines
the default values of the IMF_IMAGE structure:
- usage:
IMF_C_GENERIC
- curve.usage:
IMF_C_CORRECTION_GAMMA
- curve.gamma:
fmt_def_gamma
- curve.info.name:
NULL
- curve.info.count:
1
- curve.info.elems:
256
- curve.info.type:
IMF_C_INTEGER
- curve.info.bits:
LOG( fmt__gamma_tab_res ) / LOG( 2.0 )
- curve.response:
NULL
- aspect.name:
NULL
- chan_format:
NULL
- matte_format:
NULL
- aux_format:
NULL
- index_format:
NULL
- chan_config:
IMF_C_PLANAR_SEPARATE
- chan_orient:
IMF_C_BOT_LEFT
- chan_count:
0
- chan_type:
IMF_C_INTEGER
- chan_bits:
8
- matte_count:
0
- matte_type:
IMF_C_INTEGER
- matte_bits:
8
- aux_count:
0
- aux_type:
IMF_C_INTEGER
- aux_bits:
8
- index_count:
0
- index_type:
IMF_C_INTEGER
- index_bits:
8
- Example
-
- Related Functions
-
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:
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.