3ds Max C++ API Reference
Loading...
Searching...
No Matches
BitmapIO Class Referenceabstract

Base class for image IO plugins. More...

#include <bitmap.h>

+ 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)
 
BitmapIOPrev ()
 
BitmapIONext ()
 
virtual BMMExport BOOL ValidatePiData (BitmapInfo *pbi, ILoad *iload=nullptr)
 This is used to make sure plugin data on the BitmapInfo belongs to this plugin.
 
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 BitmapStorageStorage ()
 
BitmapMap ()
 
Filename Extensions
virtual BMMExport int ExtCount ()=0
 
virtual BMMExport const MCHARExt (int n)=0
 
Author/Desc/Copyright/Version
virtual BMMExport const MCHARLongDesc ()=0
 
virtual BMMExport const MCHARShortDesc ()=0
 
virtual BMMExport const MCHARAuthorName ()=0
 
virtual BMMExport const MCHARCopyrightMessage ()=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=nullptr)
 
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=nullptr)
 
virtual BMMExport BMMRES GetImageInfo (BitmapInfo *pbi)=0
 
virtual BMMExport BMMRES GetImageName (BitmapInfo *pbi, MCHAR *filename)
 
virtual BMMExport void EvalMatch (MSTR &matchString)
 
 __declspec (deprecated) virtual void EvalMatch(MCHAR *matchString) final
 
Loading
virtual BMMExport BitmapStorageLoad (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.
 
virtual BMMExport BMMRES Write (int frame)
 
virtual BMMExport int Close (int flag)
 
- Public Member Functions inherited from BaseInterfaceServer
UtilExport BaseInterfaceGetInterface (Interface_ID id) override
 
virtual UtilExport int NumInterfaces () const
 
virtual UtilExport BaseInterfaceGetInterfaceAt (int i) const
 
virtual UtilExport ~BaseInterfaceServer ()
 
- Public Member Functions inherited from InterfaceServer
virtual UtilExport ~InterfaceServer ()
 Destructor.
 
virtual UtilExport BaseInterfaceGetInterface (Interface_ID id)
 
template<class InterfaceType >
InterfaceType * GetTypedInterface ()
 

Public Attributes

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

Protected Attributes

float gamma = 0.f
 The gamma setting.
 
Bitmapmap = nullptr
 The Bitmap using this OUTPUT handler.
 
BitmapStoragestorage = nullptr
 The BitmapStorage used by this INPUT handler.
 
int openMode = 0
 The mode that the IO module is open for - see Bitmap Open Mode Types.
 
BitmapIOprevIO = nullptr
 A linked list pointer to the previous IO module for multiple outputs of a single bitmap.
 
BitmapIOnextIO = nullptr
 A linked list pointer to the next IO module for multiple outputs of a single bitmap.
 
- Protected Attributes inherited from BaseInterfaceServer
Tab< BaseInterface * > interfaces
 

Additional Inherited Members

- Static Public Member Functions inherited from MaxHeapOperators
static UtilExport voidoperator new (size_t size)
 Standard new operator used to allocate objects If there is insufficient memory, an exception will be thrown.
 
static UtilExport voidoperator 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.
 
static UtilExport voidoperator 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.
 
static UtilExport voidoperator 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.
 
static UtilExport voidoperator 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.
 
static UtilExport voidoperator 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.
 
static UtilExport voidoperator 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.
 
static UtilExport voidoperator new[] (size_t size)
 New operator used to allocate arrays of objects If there is insufficient memory, an exception will be thrown.
 
static UtilExport voidoperator 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.
 
static UtilExport voidoperator 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.
 
static UtilExport voidoperator new[] (size_t size, int block_type, const char *filename, int line)
 New operator used to allocate arrays of objects.
 
static UtilExport voidoperator 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.
 
static UtilExport voidoperator 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.
 
static UtilExport voidoperator 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.
 
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.
 
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.
 
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.
 
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.
 
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.
 
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.
 
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.
 
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.
 
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.
 
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.
 
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.
 
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.
 
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.
 
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.
 
static UtilExport voidoperator new (size_t size, void *placement_ptr)
 Placement new operator.
 
static UtilExport void operator delete (void *ptr, void *placement_ptr)
 Placement delete operator.
 
static UtilExport voidaligned_malloc (size_t size, size_t alignment)
 Allocates memory on a specified alignment boundary.
 
static UtilExport voidaligned_realloc (void *ptr, size_t size, size_t alignment)
 Reallocates memory on a specified alignment boundary.
 
static UtilExport void aligned_free (void *ptr)
 Frees a block of memory that was allocated with aligned_malloc/aligned_realloc.
 

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

Constructor & Destructor Documentation

◆ BitmapIO()

◆ ~BitmapIO()

virtual BMMExport ~BitmapIO ( )
virtual

Member Function Documentation

◆ GetOutputPixels() [1/2]

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.

◆ GetDitheredOutputPixels()

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.

◆ GetOutputPixels() [2/2]

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

◆ GetOutputDib()

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.

◆ GetDitheredOutputDib()

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.

◆ OutputGamma()

BMMExport float OutputGamma ( )
Remarks
Implemented by the System.

Returns the output gamma setting.

◆ DitherTrueColor()

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.

◆ DitherPaletted()

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.

◆ CalcOutputPalette()

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.

◆ OpenMode()

int OpenMode ( )
inline
Remarks
Implemented by the System.

Returns the open mode setting. See Bitmap Open Mode Types
1804{ return (openMode); }
int openMode
The mode that the IO module is open for - see Bitmap Open Mode Types.
Definition: bitmap.h:1668

◆ SetPrev()

void SetPrev ( BitmapIO prev)
inline
Remarks
Implemented by the System.

This method is used internally.
1808{ prevIO = prev; };
BitmapIO * prevIO
A linked list pointer to the previous IO module for multiple outputs of a single bitmap.
Definition: bitmap.h:1672

◆ SetNext()

void SetNext ( BitmapIO next)
inline
Remarks
Implemented by the System.

This method is used internally.
1811{ nextIO = next; };
BitmapIO * nextIO
A linked list pointer to the next IO module for multiple outputs of a single bitmap.
Definition: bitmap.h:1673

◆ Prev()

BitmapIO * Prev ( )
inline
Remarks
Implemented by the System.

This method is used internally.
1814{ return prevIO; };

◆ Next()

BitmapIO * Next ( )
inline
Remarks
Implemented by the System.

This method is used internally.
1817{ return nextIO; };

◆ Storage()

BMMExport BitmapStorage * Storage ( )
Remarks
Implemented by the System.

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

◆ Map()

Bitmap * Map ( )
inline
Remarks
Implemented by the System.

Returns a pointer to the Bitmap using this output handler.
1826{ return map; };
Bitmap * map
The Bitmap using this OUTPUT handler.
Definition: bitmap.h:1665

◆ ExtCount()

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.

◆ Ext()

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.

◆ LongDesc()

virtual BMMExport const MCHAR * LongDesc ( )
pure virtual
Remarks
Returns a long ASCII description of the image format (i.e. "Targa 2.0 Image File").

◆ ShortDesc()

virtual BMMExport const MCHAR * ShortDesc ( )
pure virtual
Remarks
Returns a short ASCII description of the image format (i.e. "Targa").

◆ AuthorName()

virtual BMMExport const MCHAR * AuthorName ( )
pure virtual
Remarks
Returns the ASCII Author name of the IO module.

◆ CopyrightMessage()

virtual BMMExport const MCHAR * CopyrightMessage ( )
pure virtual
Remarks
Returns the ASCII Copyright message for the IO module.

◆ Version()

virtual BMMExport UINT Version ( )
pure virtual
Remarks
Returns the IO module version number * 100 (i.e. v3.01 = 301)

◆ Capability()

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.

◆ ShowAbout()

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.

◆ ShowImage()

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; }
1895{ return FALSE; }

◆ ShowControl()

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; }
1926{ return FALSE; }

◆ EvaluateConfigure()

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

◆ LoadConfigure()

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.

◆ SaveConfigure()

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.

◆ GetCfgFilename()

virtual BMMExport void GetCfgFilename ( MCHAR filename)
inlinevirtual
Remarks
This is the configuration file containing the default options.
2015{ filename[0]=0; }

◆ ReadCfg()

virtual BMMExport BOOL ReadCfg ( )
inlinevirtual
Remarks
Loads the defaults into BitmapIO's parameter block.
Returns
TRUE.
2018{ return TRUE; }

◆ WriteCfg()

virtual BMMExport void WriteCfg ( )
inlinevirtual
Remarks
Saves the parameter block as the new defaults.
2020{}

◆ ValidatePiData()

virtual BMMExport BOOL ValidatePiData ( BitmapInfo pbi,
ILoad iload = nullptr 
)
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;
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))
}
}
return TRUE;
}
#define NULL
Definition: autoptr.h:18
BitmapInfo bi
Describes the properties of the bitmap being handled by the instance of this class.
Definition: bitmap.h:1797
virtual BMMExport BOOL SaveConfigure(void *ptr)=0
virtual BMMExport BOOL ValidatePiData(BitmapInfo *pbi, ILoad *iload=nullptr)
This is used to make sure plugin data on the BitmapInfo belongs to this plugin.
virtual BMMExport DWORD EvaluateConfigure()=0
Information about an image file or in-memory bitmap, including settings for loading/saving,...
Definition: bitmap.h:707
BMMExport void * GetPiData()
Returns the plugin data stored on the BitmapInfo.
Definition: bitmap.h:1481
BMMExport DWORD GetPiDataSize() const
Returns the size of the plugin data stored on the BitmapInfo.
Definition: bitmap.h:1493
BMMExport BOOL AllocPiData(DWORD size)
Allocates the plugin data memory and set the plugin data size.
Definition: ioapi.h:650
Parameters
[in]pbiThe BitmapInfo holding the plugin data
[in]iloadThe ILoad* if called when loading the BitmapInfo from a scene file, NULL otherwise.

◆ SilentMode()

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.

◆ GetFrame()

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

◆ ProcessImageIOError() [1/2]

BMMExport BMMRES ProcessImageIOError ( BitmapInfo pbi,
const MCHAR string = nullptr 
)
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.

◆ ProcessImageIOError() [2/2]

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
//-- Resolve Filename --------------------------------
TCHAR filename[MAX_PATH];
if (frame == BMM_SINGLEFRAME) {
_tcscpy(filename,bi.Name());
} else {
if (!BMMCreateNumberedFilename(bi.Name(),frame,filename)) {
}
}
#define BMM_SINGLEFRAME
Definition: bitmap.h:3935
unsigned short BMMRES
Traps the use of int or BOOL.
Definition: bitmap.h:191
BMMExport int BMMCreateNumberedFilename(const MCHAR *namein, int frame, MCHAR *nameout)
Create a filename appended by the specified frame number.
#define BMMRES_NUMBEREDFILENAMEERROR
This can be passed as an error code to BitmapIO::ProcessImageIOError().
Definition: bitmap.h:206
#define BMMRES_INTERNALERROR
An internal error occurred.
Definition: bitmap.h:207
BMMExport BMMRES ProcessImageIOError(BitmapInfo *pbi, const MCHAR *string=nullptr)
BMMExport const MCHAR * Name() const
Returns the currently set path of the image file.
#define BMM_OPEN_W
Write-only.
Definition: bitmap.h:183

◆ ChannelsRequired()

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; }
2189{ return BMM_CHAN_NONE; }
#define BMM_CHAN_NONE
Definition: gbuf.h:85

◆ GetImageInfoDlg()

virtual BMMExport BMMRES GetImageInfoDlg ( HWND  hWnd,
BitmapInfo pbi,
const MCHAR filename = nullptr 
)
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
2212{return BMMRES_NODRIVER;}
#define BMMRES_NODRIVER
Device driver responsible for image not present.
Definition: bitmap.h:197

◆ GetImageInfo()

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;
#define BMM_TRUE_24
24-bit color: 8 bits each for Red, Green, and Blue.
Definition: bitmap.h:145

◆ GetImageName()

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
2250{filename[0]=0; return (BMMRES_SUCCESS);}
#define BMMRES_SUCCESS
Success - No error occurred.
Definition: bitmap.h:193

◆ EvalMatch()

virtual BMMExport void EvalMatch ( MSTR 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.
2293{ matchString = _T(""); }

◆ __declspec()

__declspec ( deprecated  )
inlinefinal
Deprecated:
This has been deprecated as of 3ds Max 2024, please use MSTR& overload instead
2295{ matchString[0] = 0; }

◆ Load()

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.

◆ OpenOutput()

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.

◆ Write()

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.

◆ Close()

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 ) {
return 1;
}
#define BMM_NOT_OPEN
Not opened yet.
Definition: bitmap.h:181

◆ GetPaviFile()

virtual BMMExport PAVIFILE GetPaviFile ( )
inlinevirtual
Remarks
Implemented by the System.

This method is used internally.
Default Implementation:
{ return NULL; }
2365{ return nullptr; }

◆ InitOutputGammaTable()

BMMExport void InitOutputGammaTable ( BitmapInfo pbi)
Remarks
Implemented by the System.

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

Member Data Documentation

◆ gamma

float gamma = 0.f
protected

The gamma setting.

◆ map

Bitmap* map = nullptr
protected

The Bitmap using this OUTPUT handler.

◆ storage

BitmapStorage* storage = nullptr
protected

The BitmapStorage used by this INPUT handler.

◆ openMode

int openMode = 0
protected

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

◆ prevIO

BitmapIO* prevIO = nullptr
protected

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

◆ nextIO

BitmapIO* nextIO = nullptr
protected

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

◆ bi

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