Continues from Appendix E: Adding Image Plug-ins.
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;
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;
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;
Definition
void imageCapability
(
IMF_CAPABILITY **capabilities,
int *num_input,
int *num_output,
int *total
)
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 );
}
}
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";
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.
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";
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";
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;
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.
Definition
BOOLEAN imageIsFile(
char *fn,
FILE *fp
}
| Parameter | Type | Description |
|---|---|---|
| char | Filename, used only if fp is NULL. |
| 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 )
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 fileExt, which represents the extension#, which represents the frame numberThese 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";
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;
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;
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;
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;
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;
Definition
int your_lut_read_func
(
POINTER data,
IMF_LUT **imf_lut
)
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.
(*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.(*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.TRUE if successful, and FALSE if an error occurred.Information on adding image plug-ins continues in part three of Appendix E