Continues from Appendix E, Part 2.
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" );
}
Definition
POINTER *IMF_chan_alloc
(
IMF_IMAGE *image,
int res,
char *key,
int *size
)
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 |
---|---|---|
| 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
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
Definition
int imf__init_ifd
(
IMF_OBJECT *imf
)
Parameter | Type | Description |
---|---|---|
| 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
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.
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.
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