BitmapIO Class Reference

#include <bitmap.h>

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.

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 (retrievable 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 linearly (i.e. with a gamma of 1.0).

See BitmapIOMetaData for more information.

Inheritance diagram for BitmapIO:

Public Member Functions
BMMExport int	GetOutputPixels (int x, int y, int pixels, BMM_Color_fl *ptr, BOOL preMultAlpha=TRUE)
BMMExport	BitmapIO ()
virtual BMMExport	~BitmapIO ()
void	SetPrev (BitmapIO *prev)
void	SetNext (BitmapIO *next)
BitmapIO *	Prev ()
BitmapIO *	Next ()
virtual BMMExport BOOL	ValidatePiData (BitmapInfo *pbi, ILoad *iload=NULL)
	This is used to make sure plugin data on the BitmapInfo belongs to this plugin. More...
virtual BMMExport PAVIFILE	GetPaviFile ()
BMMExport void	InitOutputGammaTable (BitmapInfo *pbi)
Output Pixels
BMMExport int	GetOutputPixels (int x, int y, int pixels, BMM_Color_64 *ptr, BOOL preMultAlpha=TRUE)
BMMExport int	GetDitheredOutputPixels (int x, int y, int pixels, BMM_Color_32 *ptr, BOOL preMultAlpha=TRUE)
DIB Access
BMMExport PBITMAPINFO	GetOutputDib (int depth=24)
BMMExport PBITMAPINFO	GetDitheredOutputDib (int depth=24)
Output Gamma Setting
BMMExport float	OutputGamma ()
Dithering
BMMExport BOOL	DitherTrueColor ()
BMMExport BOOL	DitherPaletted ()
Palette Computation
BMMExport int	CalcOutputPalette (int palsize, BMM_Color_48 *pal)
Open Mode Setting
int	OpenMode ()
Storage / Bitmap Access
BMMExport BitmapStorage *	Storage ()
Bitmap *	Map ()
Filename Extensions
virtual BMMExport int	ExtCount ()=0
virtual BMMExport const MCHAR *	Ext (int n)=0
Author/Desc/Copyright/Version
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
Capabilities
virtual BMMExport int	Capability ()=0
ShowAbout / ShowImage / ShowControl
virtual BMMExport void	ShowAbout (HWND hWnd)=0
virtual BMMExport BOOL	ShowImage (HWND hWnd, BitmapInfo *pbi)
virtual BMMExport BOOL	ShowControl (HWND hWnd, DWORD flag)
BitmapIO Methods
The following methods (EvaluateConfigure(), LoadConfigure(), and SaveConfigure()) deal with BitmapIO loading and saving. See the sample code below to know how the EPS BitmapIO plug-in uses these methods. typedef struct userSettable { int units; // Inches or MM int binary; // Whether want binary image data or not int preview; // Whether want TIFF preview in file int orientation; // Options are portrait or landscape int colorType; // Whether image is output as rgb or gray float paperHeight; // Height of output (for centering image) float paperWidth; // Width of output (for centering image) float xResolution; // In dots per inch float yResolution; // In dots per inch } UserSettable; DWORD BitmapIO_EPS::EvaluateConfigure () { return sizeof (UserSettable); } BOOL BitmapIO_EPS::LoadConfigure (void *ptr) { UserSettable *buf = (UserSettable *) ptr; memcpy (&userSettings, ptr, sizeof(UserSettable)); return TRUE; } BOOL BitmapIO_EPS::SaveConfigure (void *ptr) { if (ptr) { memcpy (ptr, &userSettings, sizeof(UserSettable)); return TRUE; } else return FALSE; }
virtual BMMExport DWORD	EvaluateConfigure ()=0
virtual BMMExport BOOL	LoadConfigure (void *ptr, DWORD piDataSize)=0
virtual BMMExport BOOL	SaveConfigure (void *ptr)=0
Default Options
These Cfg methods provide access to the default options of BitmapIO, as saved in its .cfg file. The options control how files are saved to disk (JPEG compression and smoothing, for example). Formerly, most BitmapIO types implemented these methods, yet they were not derived from any superclass. The method definitions are now moved to the BitmapIO superclass, so they can easily be called on any subclass. Note: Introduced in 3ds Max 6 SDK.
virtual BMMExport void	GetCfgFilename (MCHAR *filename)
virtual BMMExport BOOL	ReadCfg ()
virtual BMMExport void	WriteCfg ()
Silent Mode Setting
BMMExport BOOL	SilentMode ()
BMMExport BMMRES	GetFrame (BitmapInfo *fbi, int *frame)
Critical Error Handling
BMMExport BMMRES	ProcessImageIOError (BitmapInfo *pbi, const MCHAR *string=NULL)
BMMExport BMMRES	ProcessImageIOError (BitmapInfo *pbi, int errorcode)
G-Buffer Channels Required
virtual BMMExport DWORD	ChannelsRequired ()
Image Information
virtual BMMExport BMMRES	GetImageInfoDlg (HWND hWnd, BitmapInfo *pbi, const MCHAR *filename=NULL)
virtual BMMExport BMMRES	GetImageInfo (BitmapInfo *pbi)=0
virtual BMMExport BMMRES	GetImageName (BitmapInfo *pbi, MCHAR *filename)
virtual BMMExport void	EvalMatch (MCHAR *matchString)
Loading
virtual BMMExport BitmapStorage *	Load (BitmapInfo *pbi, Bitmap *pmap, BMMRES *status)=0
Output / Write / Close
virtual BMMExport BMMRES	OpenOutput (BitmapInfo *pbi, Bitmap *pmap)
	Opens the image for writing to file. More...
virtual BMMExport BMMRES	Write (int frame)
virtual BMMExport int	Close (int flag)
Public Member Functions inherited from BaseInterfaceServer
virtual UtilExport BaseInterface *	GetInterface (Interface_ID id)
virtual UtilExport int	NumInterfaces () const
virtual UtilExport BaseInterface *	GetInterfaceAt (int i) const
virtual UtilExport	~BaseInterfaceServer ()
Public Member Functions inherited from InterfaceServer
virtual UtilExport	~InterfaceServer ()
	Destructor. More...

Public Attributes
BitmapInfo	bi
	Describes the properties of the bitmap being handled by the instance of this class. More...

Protected Attributes
float	gamma
	The gamma setting. More...
Bitmap *	map
	The Bitmap using this OUTPUT handler. More...
BitmapStorage *	storage
	The BitmapStorage used by this INPUT handler. More...
int	openMode
	The mode that the IO module is open for - see Bitmap Open Mode Types. More...
BitmapIO *	prevIO
	A linked list pointer to the previous IO module for multiple outputs of a single bitmap. More...
BitmapIO *	nextIO
	A linked list pointer to the next IO module for multiple outputs of a single bitmap. More...
Protected Attributes inherited from BaseInterfaceServer
Tab< BaseInterface * >	interfaces

Additional Inherited Members
Static Public Member Functions inherited from MaxHeapOperators
static UtilExport void *	operator new (size_t size)
	Standard new operator used to allocate objects If there is insufficient memory, an exception will be thrown. More...
static UtilExport void *	operator new (size_t size, const std::nothrow_t &e)
	Standard new operator used to allocate objects if there is insufficient memory, NULL will be returned. More...
static UtilExport void *	operator new (size_t size, const char *filename, int line)
	New operator used to allocate objects that takes the filename and line number where the new was called If there is insufficient memory, an exception will be thrown. More...
static UtilExport void *	operator new (size_t size, int block_type, const char *filename, int line)
	New operator used to allocate objects that takes the type of memory, filename and line number where the new was called If there is insufficient memory, an exception will be thrown. More...
static UtilExport void *	operator new (size_t size, const std::nothrow_t &e, const char *filename, int line)
	New operator used to allocate objects that takes the filename and line number where the new was called If there is insufficient memory, NULL will be returned. More...
static UtilExport void *	operator new (size_t size, unsigned long flags)
	New operator used to allocate objects that takes extra flags to specify special operations If there is insufficient memory, an exception will be thrown. More...
static UtilExport void *	operator new (size_t size, const std::nothrow_t &e, unsigned long flags)
	New operator used to allocate objects that takes extra flags to specify special operations If there is insufficient memory, NULL will be returned. More...
static UtilExport void *	operator new[] (size_t size)
	New operator used to allocate arrays of objects If there is insufficient memory, an exception will be thrown. More...
static UtilExport void *	operator new[] (size_t size, const std::nothrow_t &e)
	New operator used to allocate arrays of objects If there is insufficient memory, NULL will be returned. More...
static UtilExport void *	operator new[] (size_t size, const char *filename, int line)
	New operator used to allocate arrays of objects If there is insufficient memory, an exception will be thrown. More...
static UtilExport void *	operator new[] (size_t size, int block_type, const char *filename, int line)
	New operator used to allocate arrays of objects. More...
static UtilExport void *	operator new[] (size_t size, const std::nothrow_t &e, const char *filename, int line)
	New operator used to allocate arrays of objects If there is insufficient memory, NULL will be returned. More...
static UtilExport void *	operator new[] (size_t size, unsigned long flags)
	New operator used to allocate arrays of objects If there is insufficient memory, an exception will be thrown. More...
static UtilExport void *	operator new[] (size_t size, const std::nothrow_t &e, unsigned long flags)
	New operator used to allocate arrays of objects If there is insufficient memory, NULL will be returned. More...
static UtilExport void	operator delete (void *ptr)
	Standard delete operator used to deallocate an object If the pointer is invalid, an exception will be thrown. More...
static UtilExport void	operator delete (void *ptr, const std::nothrow_t &e)
	Standard delete operator used to deallocate an object If the pointer is invalid, nothing will happen. More...
static UtilExport void	operator delete (void *ptr, const char *filename, int line)
	Delete operator used to deallocate an object that takes the filename and line number where the delete was called If the pointer is invalid, an exception will be thrown. More...
static UtilExport void	operator delete (void *ptr, int block_type, const char *filename, int line)
	Delete operator used to deallocate an object that takes the type of memory, filename and line number where the delete was called If the pointer is invalid, an exception will be thrown. More...
static UtilExport void	operator delete (void *ptr, const std::nothrow_t &e, const char *filename, int line)
	Delete operator used to deallocate an object that takes the filename and line number where the delete was called If the pointer is invalid, nothing will happen. More...
static UtilExport void	operator delete (void *ptr, unsigned long flags)
	Delete operator used to deallocate an object that takes extra flags to specify special operations If the pointer is invalid, an exception will be thrown. More...
static UtilExport void	operator delete (void *ptr, const std::nothrow_t &e, unsigned long flags)
	Delete operator used to deallocate an object that takes extra flags to specify special operations If the pointer is invalid, nothing will happen. More...
static UtilExport void	operator delete[] (void *ptr)
	Standard delete operator used to deallocate an array of objects If the pointer is invalid, an exception will be thrown. More...
static UtilExport void	operator delete[] (void *ptr, const std::nothrow_t &e)
	Standard delete operator used to deallocate an array of objects If the pointer is invalid, nothing will happen. More...
static UtilExport void	operator delete[] (void *ptr, const char *filename, int line)
	Delete operator used to deallocate an array of objects that takes the filename and line number where the delete was called If the pointer is invalid, an exception will be thrown. More...
static UtilExport void	operator delete[] (void *ptr, int block_type, const char *filename, int line)
	Delete operator used to deallocate an array of objects that takes the type of memory, filename and line number where the delete was called If the pointer is invalid, an exception will be thrown. More...
static UtilExport void	operator delete[] (void *ptr, const std::nothrow_t &e, const char *filename, int line)
	Delete operator used to deallocate an array of objects that takes the filename and line number where the delete was called If the pointer is invalid, nothing will happen. More...
static UtilExport void	operator delete[] (void *ptr, unsigned long flags)
	Delete operator used to deallocate an array of objects that takes extra flags to specify special operations If the pointer is invalid, an exception will be thrown. More...
static UtilExport void	operator delete[] (void *ptr, const std::nothrow_t &e, unsigned long flags)
	Delete operator used to deallocate an array of objects that takes extra flags to specify special operations If the pointer is invalid, an exception will be thrown. More...
static UtilExport void *	operator new (size_t size, void *placement_ptr)
	Placement new operator. More...
static UtilExport void	operator delete (void *ptr, void *placement_ptr)
	Placement delete operator. More...

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
	)

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-pre-multiplied alpha to be returned.

Returns

Nonzero if the pixels were retrieved; otherwise zero.

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

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-pre-multiplied 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
	)

BMMExport PBITMAPINFO GetOutputDib

(

int

depth = 24

)

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

)

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

(

)

Remarks

Implemented by the System.

Returns the output gamma setting.

BMMExport BOOL DitherTrueColor

(

)

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

(

)

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
	)

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

Remarks

Implemented by the System.

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

{ return (openMode); }

void SetPrev ( BitmapIO *  prev )

inline

Remarks

Implemented by the System.

This method is used internally.

{ prevIO = prev; };

void SetNext ( BitmapIO *  next )

inline

Remarks

Implemented by the System.

This method is used internally.

{ nextIO = next; };

BitmapIO* Prev ( )

inline

Remarks

Implemented by the System.

This method is used internally.

{ return prevIO; };

BitmapIO* Next ( )

inline

Remarks

Implemented by the System.

This method is used internally.

{ return nextIO; };

BMMExport BitmapStorage* Storage

(

)

Remarks

Implemented by the System.

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

Bitmap* Map ( )

inline

Remarks

Implemented by the System.

Returns a pointer to the Bitmap using this output handler.

{ return map; };

virtual BMMExport int ExtCount ( )

pure virtual

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

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

Remarks

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

virtual BMMExport const MCHAR* ShortDesc ( )

pure virtual

Remarks

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

virtual BMMExport const MCHAR* AuthorName ( )

pure virtual

Remarks

Returns the ASCII Author name of the IO module.

virtual BMMExport const MCHAR* CopyrightMessage ( )

pure virtual

Remarks

Returns the ASCII Copyright message for the IO module.

virtual BMMExport UINT Version ( )

pure virtual

Remarks

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

virtual BMMExport int Capability ( )

pure virtual

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

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 *  pbi  )

inlinevirtual

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 *pbi

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  )

inlinevirtual

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

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

Remarks

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

Parameters

ptr	- Pointer initialized to point to the previously saved configuration data.
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

Remarks

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

Parameters

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 )

inlinevirtual

Remarks

This is the configuration file containing the default options.

{ filename[0]=0; }

virtual BMMExport BOOL ReadCfg ( )

inlinevirtual

Remarks

Loads the defaults into BitmapIO's parameter block.

Returns

TRUE.

{ return TRUE; }

virtual BMMExport void WriteCfg ( )

inlinevirtual

Remarks

Saves the parameter block as the new defaults.

{}

virtual BMMExport BOOL ValidatePiData ( BitmapInfo *  pbi, ILoad *  iload = NULL  )

virtual

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]	pbi	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

(

)

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
	)

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 *	pbi,
		const MCHAR *	string = NULL
	)

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 *pbi

A pointer to the BitmapInfo. This is used to retrieve the file or device name (using pbi->Name() or pbi->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 *	pbi,
		int	errorcode
	)

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 *pbi

A pointer to the BitmapInfo. This is used to retrieve the file or device name (using pbi->Name() or pbi->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:

From: MAXSDK/samples/images/jpeg/jpeg.cpp

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 --------------------------------

    TCHAR 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 ( )

inlinevirtual

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 *  pbi, const MCHAR *  filename = NULL  )

inlinevirtual

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 *pbi

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 *  pbi )

pure virtual

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 *pbi

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:

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

virtual BMMExport BMMRES GetImageName ( BitmapInfo *  pbi, MCHAR *  filename  )

inlinevirtual

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 *pbi

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 void EvalMatch ( MCHAR *  matchString )

inlinevirtual

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.

{ matchString[0] = 0; }

virtual BMMExport BitmapStorage* Load ( BitmapInfo *  pbi, Bitmap *  pmap, BMMRES *  status  )

pure virtual

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 *pbi

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

Bitmap *pmap

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/images/jpeg/jpeg.cpp.

virtual BMMExport BMMRES OpenOutput ( BitmapInfo *  pbi, Bitmap *  pmap  )

virtual

Opens the image for writing to file.

Remarks

This method opens the image for output and prepares 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

pbi	- The image information.
pmap	- Points to the bitmap to save.

Returns

Returns nonzero if everything was OK; otherwise 0.

Sample Code:

See the OpenOutput() method of /MAXSDK/samples/images/jpeg/jpeg.cpp.

virtual BMMExport BMMRES Write ( int  frame )

virtual

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/images/jpeg/jpeg.cpp.

virtual BMMExport int Close ( int  flag )

virtual

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:

From MAXSDK/samples/images/gif/gif.cpp

int  BitmapIO_GIF::Close( int flag ) {
     openMode = BMM_NOT_OPEN;
     return 1;
}

virtual BMMExport PAVIFILE GetPaviFile ( )

inlinevirtual

Remarks

Implemented by the System.

This method is used internally.

Default Implementation:

{ return NULL; }

{ return NULL; }

BMMExport void InitOutputGammaTable

(

BitmapInfo *

pbi

)

Remarks

Implemented by the System.

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

Member Data Documentation

float gamma

protected

The gamma setting.

Bitmap* map

protected

The Bitmap using this OUTPUT handler.

BitmapStorage* storage

protected

The BitmapStorage used by this INPUT handler.

int openMode

protected

The mode that the IO module is open for - see Bitmap Open Mode Types.

BitmapIO* prevIO

protected

A linked list pointer to the previous IO module for multiple outputs of a single bitmap.

BitmapIO* nextIO

protected

A linked list pointer to the next IO module for multiple outputs of a single bitmap.

BitmapInfo bi

Describes the properties of the bitmap being handled by the instance of this class.