This reference page is linked to from the following overview topics: Resolution / Palettes / Pixel Storage Topics, Data Import and Export Plug-ins, Error Reporting, New Classes and Methods, Automatic Gamma Correction Best Practices, SDK Changes for Automatic Gamma Correction, Plug-in Base Classes, Writing Image IO Plug-ins, Principal Bitmap Classes.

#include <bitmap.h>

Inheritance diagram for BitmapIO:

Class Description

Base class for image IO plugins.

See also:: Class Bitmap, Class BitmapStorage, Class BitmapInfo, Class BitmapIOMetaData, Working with Bitmaps.

Description:: This is the base class used by developers creating image loader / saver plug-ins. Developers implement pure virtual methods of this class to load the image, open it for output, write to it, close it, and to provide information about the image loader/saver they are creating. These are properties such as the author name, copyright, image format description, filename extension(s) used, and the capabilities of the image loader / saver.

When a BitmapIO derived image reader reads an image, it creates a storage class that makes sense to it. For example, a paletted 8 bit is perfect for loading GIF's but not for loading 32 bit Targas. The inverse is also true. There is no point in creating a TRUE_64 storage to load a GIF. Because this is how image buffers are managed, it is also important to note that if a developer writes an image loader that creates images from scratch (a gradient generator for instance), there is no need to have any real memory allocated. The plug-in would simply derive a new type of BitmapStorage and provide the pixels through the common methods (virtual buffer), creating them as they are requested.

Method Groups:: See Method Groups for Class BitmapIO.

Automatic gamma correction / BitmapIOMetaData: If a particular BitmapIO is intended to read/write floating point data, or in general does not want to have the data encoded with a gamma curve, it can choose to expose the BitmapIOMetaData interface. This is done by exposing an interface with the ID of BITMAPIOMETADATA_INTERFACE_ID (retreivable via BitmapIO::GetInterface(BITMAPIOMETADATA_INTERFACE_ID)). This returns a pointer to the BitmapIO's BitmapIOMetaData interface. This exposes a function BitmapIOMetaData::UseLinearStorage() that will return true if that BitmapIO would like to (by default) load and save data linearily (i.e. with a gamma of 1.0).

See BitmapIOMetaData for more information.

Public Member Functions
BMMExport int	GetOutputPixels (int x, int y, int pixels, BMM_Color_64 *ptr, BOOL preMultAlpha=TRUE)
BMMExport int	GetOutputPixels (int x, int y, int pixels, BMM_Color_fl *ptr, BOOL preMultAlpha=TRUE)
BMMExport int	GetDitheredOutputPixels (int x, int y, int pixels, BMM_Color_32 *ptr, BOOL preMultAlpha=TRUE)
BMMExport PBITMAPINFO	GetOutputDib (int depth=24)
BMMExport PBITMAPINFO	GetDitheredOutputDib (int depth=24)
BMMExport float	OutputGamma ()
BMMExport BOOL	DitherTrueColor ()
BMMExport BOOL	DitherPaletted ()
BMMExport int	CalcOutputPalette (int palsize, BMM_Color_48 *pal)
BMMExport	BitmapIO ()
virtual BMMExport	~BitmapIO ()
int	OpenMode ()
void	SetPrev (BitmapIO *prev)
void	SetNext (BitmapIO *next)
BitmapIO *	Prev ()
BitmapIO *	Next ()
BMMExport BitmapStorage *	Storage ()
Bitmap *	Map ()
virtual BMMExport int	ExtCount ()=0
virtual BMMExport const MCHAR *	Ext (int n)=0
virtual BMMExport const MCHAR *	LongDesc ()=0
virtual BMMExport const MCHAR *	ShortDesc ()=0
virtual BMMExport const MCHAR *	AuthorName ()=0
virtual BMMExport const MCHAR *	CopyrightMessage ()=0
virtual BMMExport UINT	Version ()=0
virtual BMMExport int	Capability ()=0
virtual BMMExport void	ShowAbout (HWND hWnd)=0
virtual BMMExport BOOL	ShowImage (HWND hWnd, BitmapInfo *bi)
virtual BMMExport BOOL	ShowControl (HWND hWnd, DWORD flag)
virtual BMMExport DWORD	EvaluateConfigure ()=0
virtual BMMExport BOOL	LoadConfigure (void *ptr, DWORD piDataSize)=0
virtual BMMExport BOOL	SaveConfigure (void *ptr)=0
virtual BMMExport void	GetCfgFilename (MCHAR *filename)
virtual BMMExport BOOL	ReadCfg ()
virtual BMMExport void	WriteCfg ()
virtual BMMExport BOOL	ValidatePiData (BitmapInfo bi, ILoad iload=NULL)
	This is used to make sure plugin data on the BitmapInfo belongs to this plugin.
BMMExport BOOL	SilentMode ()
BMMExport BMMRES	GetFrame (BitmapInfo fbi, int frame)
BMMExport BMMRES	ProcessImageIOError (BitmapInfo bi, const MCHAR string=NULL)
BMMExport BMMRES	ProcessImageIOError (BitmapInfo *bi, int errorcode)
virtual BMMExport DWORD	ChannelsRequired ()
virtual BMMExport BMMRES	GetImageInfoDlg (HWND hWnd, BitmapInfo bi, const MCHAR filename=NULL)
virtual BMMExport BMMRES	GetImageInfo (BitmapInfo *bi)=0
virtual BMMExport BMMRES	GetImageName (BitmapInfo bi, MCHAR filename)
virtual BMMExport BitmapStorage *	Load (BitmapInfo bi, Bitmap map, BMMRES *status)=0
virtual BMMExport BMMRES	OpenOutput (BitmapInfo bi, Bitmap map)
	Opens the image for writing to file.
virtual BMMExport BMMRES	Write (int frame)
virtual BMMExport int	Close (int flag)
virtual BMMExport PAVIFILE	GetPaviFile ()
BMMExport void	InitOutputGammaTable (BitmapInfo *bi)
virtual BMMExport void	EvalMatch (MCHAR *matchString)
Public Attributes
BitmapInfo	bi
	Describes the properties of the bitmap being handled by the instance of this class.
Protected Attributes
float	gamma
	The gamma setting.
Bitmap *	map
	The Bitmap using this OUTPUT handler.
BitmapStorage *	storage
	The BitmapStorage used by this INPUT handler.
int	openMode
	The mode that the IO module is open for - see Bitmap Open Mode Types.
BitmapIO *	prevIO
	A linked list pointer to the previous IO module for multiple outputs of a single bitmap.
BitmapIO *	nextIO
	A linked list pointer to the next IO module for multiple outputs of a single bitmap.

Constructor & Destructor Documentation

BMMExport BitmapIO ( )

virtual BMMExport ~BitmapIO ( ) [virtual]

Member Function Documentation

BMMExport int GetOutputPixels	(	int	x,
		int	y,
		int	pixels,
		BMM_Color_64 *	ptr,
		BOOL	preMultAlpha = `TRUE`
	)

Search for all occurrences

Remarks:: Implemented by the System.

This method is used by the subclassed BitmapIO to get pixels for output with the appropriate output gamma correction.

Parameters:: int x

Source x location.

int y

Source y location.

int pixels

Number of pixels to retrieve.

BMM_Color_64 *ptr

Pointer to storage for the retrieved pixels. See Structure BMM_Color_64.

BOOL preMultAlpha=TRUE

This parameter is available in release 3.0 and later only.

Setting this parameter to FALSE will cause pixels with non-premultiplied alpha to be returned.

Returns:: Nonzero if the pixels were retrieved; otherwise zero.

BMMExport int GetOutputPixels	(	int	x,
		int	y,
		int	pixels,
		BMM_Color_fl *	ptr,
		BOOL	preMultAlpha = `TRUE`
	)

Search for all occurrences

BMMExport int GetDitheredOutputPixels	(	int	x,
		int	y,
		int	pixels,
		BMM_Color_32 *	ptr,
		BOOL	preMultAlpha = `TRUE`
	)

Search for all occurrences

Remarks:: Implemented by the System.

This method is used by the subclassed BitmapIO to get 32 bit pixels for output with the appropriate output gamma correction and dither. Note that this method works on only a single scanline of pixels at a time.

Parameters:: int x

Source x location.

int y

Source y location.

int pixels

Number of pixels to retrieve.

BMM_Color_32 *ptr

Pointer to storage for the retrieved pixels. See Structure BMM_Color_32.

BOOL preMultAlpha=TRUE

This parameter is available in release 3.0 and later only.

Setting this parameter to FALSE will cause pixels with non-premultiplied alpha to be returned.

Returns:: Nonzero if the pixels were retrieved; otherwise zero.

BMMExport PBITMAPINFO GetOutputDib ( int depth = 24 )

Search for all occurrences

Remarks:: Implemented by the System.

This method is used by the subclassed BitmapIO to get a DIB for output with the appropriate output gamma correction.

Parameters:: int depth = 24

Specifies the depth of the DIB. This may be either 24 or 32.

BMMExport PBITMAPINFO GetDitheredOutputDib ( int depth = 24 )

Search for all occurrences

Remarks:: Implemented by the System.

This methods is used by the subclassed BitmapIO to get a DIB for output with the appropriate output gamma correction and dither.

Parameters:: int depth = 24

Specifies the depth of the DIB. This may be either 24 or 32.

BMMExport float OutputGamma ( )

Search for all occurrences

Remarks:: Implemented by the System.

Returns the output gamma setting.

BMMExport BOOL DitherTrueColor ( )

Search for all occurrences

Remarks:: Implemented by the System.

If a BitmapIO wants to do its own dithering, it should call this method to find out if dithering is wanted for true color images. If it is a 24 bit or 32 bit format, it would usually just call GetDitheredOutputPixels() instead.

Returns:: TRUE if dithering is desired; otherwise FALSE.

BMMExport BOOL DitherPaletted ( )

Search for all occurrences

Remarks:: Implemented by the System.

If a BitmapIO wants to do its own dithering, it should call this method to find out if dithering is wanted for paletted images.

Returns:: TRUE if dithering is desired; otherwise FALSE.

BMMExport int CalcOutputPalette	(	int	palsize,
		BMM_Color_48 *	pal
	)

Search for all occurrences

Remarks:: Calculate a color palette for output color packing for the map that is using this output handler (this is the map pointed at by the protected data member Bitmap *map). This method performs gamma correction. See Class ColorPacker, Class Quantizer.

Parameters:: int palsize

The size of the palette to compute.

BMM_Color_48 *pal

Storage for the palette.

Returns:: Nonzero if the palette was computed; otherwise zero.

int OpenMode ( ) [inline]

Search for all occurrences

Remarks:: Implemented by the System.

Returns the open mode setting. See Bitmap Open Mode Types.

{ return (openMode); }

void SetPrev ( BitmapIO * prev ) [inline]

Search for all occurrences

Remarks:: Implemented by the System.

This method is used internally.

{ prevIO = prev; };

void SetNext ( BitmapIO * next ) [inline]

Search for all occurrences

Remarks:: Implemented by the System.

This method is used internally.

{ nextIO = next; };

BitmapIO* Prev ( ) [inline]

Search for all occurrences

Remarks:: Implemented by the System.

This method is used internally.

{ return prevIO; };

BitmapIO* Next ( ) [inline]

Search for all occurrences

Remarks:: Implemented by the System.

This method is used internally.

{ return nextIO; };

BMMExport BitmapStorage* Storage ( )

Search for all occurrences

Remarks:: Implemented by the System.

Returns a pointer to the BitmapStorage for this image input handler.

Bitmap* Map ( ) [inline]

Search for all occurrences

Remarks:: Implemented by the System.

Returns a pointer to the Bitmap using this output handler.

{ return map; };

virtual BMMExport int ExtCount ( ) [pure virtual]

Search for all occurrences

Remarks:: Returns the number of filename extensions supported by this IO module. For example the EPS plug-in supports "EPS" and "PS", and thus returns 2.

virtual BMMExport const MCHAR* Ext ( int n ) [pure virtual]

Search for all occurrences

Remarks:: The extensions are accessed using a virtual array. This method returns the 'i-th' filename extension supported by the IO module, (i.e. "EPS").

Parameters:: int i

Specifies which filename extension to return.

virtual BMMExport const MCHAR* LongDesc ( ) [pure virtual]

Search for all occurrences

Remarks:: Returns a long ASCII description of the image format (i.e. "Targa 2.0 Image File").

virtual BMMExport const MCHAR* ShortDesc ( ) [pure virtual]

Search for all occurrences

Remarks:: Returns a short ASCII description of the image format (i.e. "Targa").

virtual BMMExport const MCHAR* AuthorName ( ) [pure virtual]

Search for all occurrences

Remarks:: Returns the ASCII Author name of the IO module.

virtual BMMExport const MCHAR* CopyrightMessage ( ) [pure virtual]

Search for all occurrences

Remarks:: Returns the ASCII Copyright message for the IO module.

virtual BMMExport UINT Version ( ) [pure virtual]

Search for all occurrences

Remarks:: Returns the IO module version number * 100 (i.e. v3.01 = 301)

virtual BMMExport int Capability ( ) [pure virtual]

Search for all occurrences

Remarks:: Returns the IO module capability flags. These describe the capabilities of the plug-in such as if it supports reading images, writing images, multiple files, and whether it has its own information and control dialog boxes. See BitmapIO Capability Flags.

virtual BMMExport void ShowAbout ( HWND hWnd ) [pure virtual]

Search for all occurrences

Remarks:: This method is called to show the plug-in's "About" box. This is called, for example, from the About button of the Add Image Input Event dialog in Video Post.

Parameters:: HWND hWnd

The handle of the owner window.

virtual BMMExport BOOL ShowImage	(	HWND	hWnd,
		BitmapInfo *	bi
	)		`[inline, virtual]`

Search for all occurrences

Remarks:: If the BMMIO_OWN_VIEWER flag is set in the flags returned from the Capability() method, this method will be called whenever the user wants to view an image for this device. This is for devices which can "play" image sequences such as AVIs, FLCs, etc.

Parameters:: HWND hWnd

The handle of the owner window.

BitmapInfo *bi

The bitmap to view.

Returns:: TRUE if the viewing the image was successful; otherwise FALSE.

Default Implementation:: { return FALSE; }

{ return FALSE; }

virtual BMMExport BOOL ShowControl	(	HWND	hWnd,
		DWORD	flag
	)		`[inline, virtual]`

Search for all occurrences

Remarks:: Displays the Control Panel of the IO module. This function is only called if the plug-in has defined it supports it (through the Capability flag returned from Capability(), ie. BMMIO_CONTROLREAD, etc.). See BitmapIO Capability Flags.

Parameters:: HWND hWnd

The handle of the owner window.

DWORD flag

Indicates to the plug-in what operation the control is for (read, write, or generic). See BitmapIO Capability Flags.

Returns:: If the user exits the box through an OK, this function should return TRUE. If the user cancels out, it will should FALSE. FALSE indicates nothing has changed so the system won't bother asking the plug-in if it wants to save data.

Default Implementation:: { return FALSE; }

{ return FALSE; }

virtual BMMExport DWORD EvaluateConfigure ( ) [pure virtual]

Search for all occurrences

Remarks:: This method is called by 3ds Max to determine the buffer size required by the plug-in. The plug-in implements this method and returns the number of bytes of configuration data it needs to save.

Returns:: The buffer size required by the plug-in (in bytes).

virtual BMMExport BOOL LoadConfigure	(	void *	ptr,
		DWORD	piDataSize
	)		`[pure virtual]`

Search for all occurrences

Remarks:: This method is called by 3ds Max to allow the plug-in to load any configuration data.

Parameters:: void *ptr

Pointer initialized to point to the previously saved configuration data. DWORD piDataSize

The size of the previously saved configuration data.

Returns:: Returns TRUE if the data was loaded properly; otherwise FALSE.

virtual BMMExport BOOL SaveConfigure ( void * ptr ) [pure virtual]

Search for all occurrences

Remarks:: This method is called by 3ds Max to allow the plug-in to save any configuration data.

Parameters:: void *ptr

Pointer initialized to a pre-allocated buffer where the plug-in may save data.

Returns:: Returns TRUE if the data was saved; otherwise FALSE.

virtual BMMExport void GetCfgFilename ( MCHAR * filename ) [inline, virtual]

Search for all occurrences

Remarks:: This is the configuration file containing the default options.

{ filename[0]=0; }

virtual BMMExport BOOL ReadCfg ( ) [inline, virtual]

Search for all occurrences

Remarks:: Loads the defaults into BitmapIO's parameter block.

Returns:: TRUE.

{ return TRUE; }

virtual BMMExport void WriteCfg ( ) [inline, virtual]

Search for all occurrences

Remarks:: Saves the parameter block as the new defaults.

{}

virtual BMMExport BOOL ValidatePiData	(	BitmapInfo *	bi,
		ILoad *	iload = `NULL`
	)		`[virtual]`

Search for all occurrences

This is used to make sure plugin data on the BitmapInfo belongs to this plugin.

It is also called on file load to allow the plugin to version the plugin data. In this case, the iload parameter will be non-NULL. If a plugin implements this method, it must first call the method on BitmapIO and immediately return false if that implementation returns false.

 BOOL BitmapIO_DS::ValidatePiData( BitmapInfo *bi, ILoad *iload )
 {
        if (bi == NULL)
                return FALSE;
        if (!BitmapIO::ValidatePiData(bi) )
                return FALSE;
 
        void* ptr = bi->GetPiData();
        DWORD piDataSize = bi->GetPiDataSize();
 
        if ((piDataSize == sizeof(AVIDATA_old_x32) + ((AVIDATA_old_x32*)ptr)->codec_data_size) ||
                (piDataSize == sizeof(AVIDATA_old_x64) + ((AVIDATA_old_x64*)ptr)->codec_data_size))
        {
                // old data format - update to new format
                if (BitmapIO_DS::LoadConfigure(ptr, piDataSize))
                {
                        DWORD newSize = EvaluateConfigure();
                        if (bi->AllocPiData(newSize))
                                SaveConfigure(bi->GetPiData());
                }
        }
        return TRUE;
 }

Parameters:

[in]	bi	The BitmapInfo holding the plugin data
[in]	iload	The ILoad* if called when loading the BitmapInfo from a scene file, NULL otherwise.

BMMExport BOOL SilentMode ( )

Search for all occurrences

Remarks:: Implemented by the System.

Returns the state of the silent mode flag. If this flag is TRUE the plug-in should NOT post a dialog displaying any error messages.

BMMExport BMMRES GetFrame	(	BitmapInfo *	fbi,
		int *	frame
	)

Search for all occurrences

Remarks:: Implemented by the System.

This method is for use with multi-frame sequences. It processes the desired frame based on the user options. For example the user can tell the system to hold on the last frame of the sequence, loop back to the beginning, or return an error. This method does all the checking automatically based on the BitmapInfo object passed and computes the proper frame number.

Parameters:: BitmapInfo *fbi

A pointer to the BitmapInfo that contains the user options. This is the instance passed to Load().

int *frame

A pointer to an integer to receive the frame number

Returns:: One of the following values:

BMMRES_SUCCESS

BMMRES_BADFRAME

BMMExport BMMRES ProcessImageIOError	(	BitmapInfo *	bi,
		const MCHAR *	string = `NULL`
	)

Search for all occurrences

Remarks:: Implemented by the System.

This method may be called to present the user with the 3ds Max Image IO Error dialog box. The dialog displays the bitmap file name or device name, and the specified error message. The user may choose Cancel or Retry from the dialog. An appropriate value is returned based on the users selection.

This method is used to handle hardware I/O errors automatically or display the given string.

In this method, if Silent Mode is on (for example network rendering is being done), no dialog is presented and BMMRES_ERRORTAKENCARE is returned.

Parameters:: BitmapInfo *bi

A pointer to the BitmapInfo. This is used to retrieve the file or device name (using bi->Name() or bi->Device()).

MCHAR *string = NULL

The error message to present in the dialog. If NULL this method will query the operating system for the last I/O error and give its own interpretation of the error. This will work for all "File Not Found", "Permission Denied", etc. type errors.

Returns:: One of the following values:

BMMRES_ERRORTAKENCARE

Returned if the user selected OK from the dialog or the error was taken care of (silent mode was on).

BMMRES_ERRORRETRY

The user has selected Retry from the dialog.

BMMExport BMMRES ProcessImageIOError	(	BitmapInfo *	bi,
		int	errorcode
	)

Search for all occurrences

Remarks:: Implemented by the System.

This method may be called to present the user with the 3ds Max Image IO Error dialog box displaying the specified error message based on the error code passed. The user may choose Cancel or Retry from the dialog. An appropriate value is returned based on the users selection. If Silent Mode is on (for example network rendering is being done) no dialog is presented and BMMRES_ERRORTAKENCARE is returned.

Parameters:: BitmapInfo *bi

A pointer to the BitmapInfo. This is used to retrieve the file or device name (using bi->Name() or bi->Device()).

int errorcode

The error code. Pass one of the following values and the string shown to its right will be presented.

BMMRES_INTERNALERROR - Internal Error

BMMRES_NUMBEREDFILENAMEERROR - Error Creating Numbered File Name.

BMMRES_BADFILEHEADER - Invalid Image File Header

BMMRES_CANTSTORAGE - Error Creating Image Storage

BMMRES_MEMORYERROR - Memory Error

BMMRES_BADFRAME - Invalid Frame Requested

Any other values produce - Unknown Error

Returns:: One of the following values:

BMMRES_ERRORTAKENCARE

Returned if the user selected Cancel from the dialog or the error was taken care of (silent mode was on).

BMMRES_ERRORRETRY

The user has selected Retry from the dialog.

Sample Code:

                BMMRES BitmapIO_JPEG::Write(int frame)          
                {               
                //-- If we haven't gone through an OpenOutput(), leave          
                        if (openMode != BMM_OPEN_W)             
                                return          
                                        (ProcessImageIOError(&bi,BMMRES_INTERNALERROR));                
                //-- Resolve Filename --------------------------------          
                        MCHAR filename[MAX_PATH];               
                        if (frame == BMM_SINGLEFRAME) {         
                                _tcscpy(filename,bi.Name());            
                        }               
                        else {          
                                if (!BMMCreateNumberedFilename(bi.Name(),frame,filename)) {             
                                        return          
                                                (ProcessImageIOError(&bi,BMMRES_NUMBEREDFILENAMEERROR));                
                                }               
                        }

virtual BMMExport DWORD ChannelsRequired ( ) [inline, virtual]

Search for all occurrences

Remarks:: These are the channels required for output. By setting this flag, the plug-in can request that 3ds Max generate the given channels. Prior to rendering, 3ds Max will scan the plug-ins in the chain of events and list all types of channels being requested. The plug-in, at the time of the Write() method, will have access to these channels through the channel interface described in BitmapStorage.

Returns:: See Image (G-Buffer) Channels.

Default Implementation:: { return BMM_CHAN_NONE; }

{ return BMM_CHAN_NONE; }

virtual BMMExport BMMRES GetImageInfoDlg	(	HWND	hWnd,
		BitmapInfo *	bi,
		const MCHAR *	filename = `NULL`
	)		`[inline, virtual]`

Search for all occurrences

Remarks:: This method will display a dialog with information about the given bitmap (either defined in bi.Name()/bi.Device() or explicitly in the filename passed). The default method will retrieve image information using the mandatory GetImageInfo() and display a generic information dialog. If an image loader / writer wants to show its own info dialog, perhaps showing an image property not found in the generic dialog, it can implement its own function (and notify the system using the BMM_INFODLG flag in the capabilities flag).

Parameters:: HWND hWnd

The parent window handle calling the dialog.

BitmapInfo *bi

Defines the name of the bitmap or device (unless specified below).

const MCHAR *filename = NULL

Specifies the filename to use explicitly.

Returns:: The result of the operation. See Bitmap Error (result) Codes.

{return BMMRES_NODRIVER;}

virtual BMMExport BMMRES GetImageInfo ( BitmapInfo * bi ) [pure virtual]

Search for all occurrences

Remarks:: The BitmapIO module implements this method to initialize the BitmapInfo instance passed in with information about the image. This information might be obtained from read the image header for example. The BitmapInfo passed contains the name of the image to get the information about.

Parameters:: BitmapInfo *bi

A pointer to an instance of the class BitmapInfo.

Returns:: If an error occurs, the plug-in should process the error (display a message if appropriate) and return BMMRES_ERRORTAKENCARE. If everything went OK, the plug-in should return BMMRES_SUCCESS.

Sample Code:

                bi->SetWidth(640);
                bi->SetHeight(480);
                bi->SetType(BMM_TRUE_24);
                bi->SetAspect(1.0f);
                bi->SetGamma(1.0f);
                bi->SetFirstFrame(0);
                bi->SetLastFrame(0);
                return BMM_SUCCESS;

virtual BMMExport BMMRES GetImageName	(	BitmapInfo *	bi,
		MCHAR *	filename
	)		`[inline, virtual]`

Search for all occurrences

Remarks:: This method is implemented by image file loaders (IFL handlers). It is called to update the filename passed based on the properties of the BitmapInfo passed. See the implementation of this method in /MAXSDK/SAMPLES/IO/IFL.CPP.

Parameters:: BitmapInfo *bi

Specifies the properties of the IFL sequence.

MCHAR *filename

The filename to update based on the properties of bi.

Returns:: See Bitmap Error (result) Codes.

{filename[0]=0; return (BMMRES_SUCCESS);}

virtual BMMExport BitmapStorage* Load	(	BitmapInfo *	bi,
		Bitmap *	map,
		BMMRES *	status
	)		`[pure virtual]`

Search for all occurrences

Remarks:: This is the method that is called to actually load and store the image. This method usually creates the storage for the image data, allocates storage space, and puts the image to the storage one scanline at a time. If the image header contains known gamma information, it can call SetGamma() with the relevant value. This method also usually sets the BitmapIO::openMode flag to BMM_OPEN_R to indicate the image is loaded and open for reading.

Parameters:: BitmapInfo *bi

Points to an instance of class BitmapInfo. This has the name of the bitmap / device to load.

Bitmap *map

This points to the bitmap to be loaded.

BMMRES *status

The result of the bitmap load operation. See Bitmap Error (result) Codes.

Returns:: The BitmapStorage created to manages this bitmap.

Sample Code:: See the Load() method of /MAXSDK/SAMPLES/IO/JPEG/JPEG.CPP.

virtual BMMExport BMMRES OpenOutput	(	BitmapInfo *	bi,
		Bitmap *	map
	)		`[virtual]`

Search for all occurrences

Opens the image for writing to file.

Remarks:: This method opens the image for output and prepare to write to it. This is the time that the plug-in receives the information about what to write, the flags, etc. The only thing to call after this the Write() method which takes just a frame number.

Parameters:

bi	- The image information.
map	- Points to the bitmap to save.

Returns:: Returns nonzero if everything was OK; otherwise 0.

Sample Code:: See the OpenOutput() method of /MAXSDK/SAMPLES/IO/JPEG/JPEG.CPP.

virtual BMMExport BMMRES Write ( int frame ) [virtual]

Search for all occurrences

Remarks:: This method is called to write the image from the BitmapStorage to disk. The data member bi contains the relevant information (for example bi.Name() contains the name of the file to write).

Parameters:: int frame

Specifies the frame to write. For single image formats this will be BMM_SINGLEFRAME.

Returns:: Returns nonzero if everything was OK; otherwise 0.

Sample Code:: See the Write() method of /MAXSDK/SAMPLES/IO/JPEG/JPEG.CPP.

virtual BMMExport int Close ( int flag ) [virtual]

Search for all occurrences

Remarks:: Closes the output file and saves or discards the changes based on the flag passed.

Parameters:: int flag

See Bitmap Close Types.

Returns:: Returns nonzero if output was closed successfully; otherwise 0.

Sample Code:: See the Close() method of /MAXSDK/SAMPLES/IO/WSD/WSD.CPP.

virtual BMMExport PAVIFILE GetPaviFile ( ) [inline, virtual]

Search for all occurrences

Remarks:: Implemented by the System.

This method is used internally.

Default Implementation:: { return NULL; }

{ return NULL; }

BMMExport void InitOutputGammaTable ( BitmapInfo * bi )

Search for all occurrences

Remarks:: Implemented by the System.

This method is used internally to build the output gamma table.

virtual BMMExport void EvalMatch ( MCHAR * matchString ) [inline, virtual]

Search for all occurrences

Remarks:: The bitmap manager caches images in order to speed its process. When a new image is requested, if it's

already loaded, a pointer to it is passed around as opposed to loading an entire new copy of it. It does so by comparing the image name and the frame number requested (in case of multiframe files and/or devices).

This works fine in most cases, however consider the following scenario. The Accom device generates images just as if you were loading Targa files. The comparison explained above works fine. The problem however, is that within the Accom private setup, you can determine where in the Accom to start reading frames. In other words, you may have a sequence of images recorded in the Accom starting at frame 300 for instance. Once in the Accom setup, you define your starting frame at 300 and whenever 3ds Max requests a frame, the Accom driver offsets the requested frame number by 300. For example, when 3ds Max is rendering its 10th frame and requests a frame from the Accom (for a Map or for a background, etc.), the Accom will see that 3ds Max wants frame 10 and the user had setup the starting frame at 300. After computing the offset the Accom driver returns frame 310. Now, if two or more maps are used in a scene, the cache match mechanism explained above fails as it does not take in consideration the "starting frame" parameter of the Accom driver. For it, the name matches (Accom) and the frame number matches (frame 10 in the example above). If two or more maps start at different positions within the Accom, the first one defined will be used as it satisfies the match.

To handle this condition this new method saves extra information (driver private information) about a frame. Basically, part of the match process is now handled by those drivers that implement this method.

If a driver has some private data (handled by its own setup dialogue) that defines anything in how images are returned (in other words, if different images are returned because of those private settings being different), it must define the BMMIO_EVALMATCH return flag and must also implement this method. The flag is necessary to avoid wasting time setting up instances of the driver just to call the (possibly unimplemented) method.

Parameters:: MCHAR *matchString

The match string. The driver simply builds a string made of its own "per frame" parameters and returns it so 3ds Max can compare it with another instance of the driver.