Class BitmapManager
See Also: Class BitmapInfo, Class Bitmap, Class BitmapIO, Class BitmapStorage, Working with Bitmaps, List of Bitmap Error Codes.
class BitmapManager : public InterfaceServer
Description:
This class is used to manage the use of bitmaps within 3ds max. There is a global instance of this class provided by 3ds max that developers may use to call these methods. It is called TheManager. This class provides methods for things such as creating and loading bitmaps, and access to the bitmap Map Path directories. There are also methods for displaying some general dialogs that let users select input and output files and devices, as well as dialogs for setting options for the bitmap such as its custom width, height and positioning.
Note: In the 3ds max release 3.0 SDK these methods were made virtual.
Data Members:
public:
BMMVfbPalette *pal;
This is used internally as the virtual framebuffer palette.
Method Groups:
The hyperlinks below jump to the start of groups of related methods within the class
New / Creating / Loading Methods
User Interface (Dialog Box) Methods
Host Access (Window handles, Map path directory access, etc.)
Methods:
Prototype:
BOOL SilentMode()
Remarks:
Determines if silent mode is on. Silent mode specifies if developers should display error messages. If this method returns FALSE, error messages should be displayed. If TRUE, error message dialogs should not be shown.
Return Value:
Returns TRUE if silent mode is on; FALSE otherwise.
Prototype:
void SysLog(int type, char *format, ...);
Remarks:
This is reserved for future use.
Prototype:
BOOL SetSilentMode(BOOL s);
Remarks:
This method is used internally.
Prototype:
void SetLogLevel(DWORD level);
Remarks:
This method is used internally.
Prototype:
DWORD GetLogLevel();
Remarks:
This method is used internally.
Prototype:
void RefreshAllVFBs();
Remarks:
This method is available in release 2.0 and later only.
This method refreshes the interior of all the virtual frame buffer windows with each bitmap's contents.
Prototype:
void DeleteAllAutonomousVFBMaps();
Remarks:
This method is available in release 2.0 and later only.
This method calls Bitmap::DeleteThis() on all the bitmaps whose virtual frame buffers are set to autonomous.
Prototype:
virtual INT_PTR Execute(int cmd, ULONG arg1=0, ULONG arg2=0, ULONG arg3=0)=0;
Remarks:
This method is available in release 2.0 and later only.
This is a general purpose function that allows the API to be extended in the future. The 3ds max development team can assign new cmd numbers and continue to add functionality to this class without having to 'break' the API.
Parameters:
int cmd
The index of the command to execute.
ULONG arg1=0
Optional argument 1. See the documentation where the cmd option is discussed for more details on these parameters.
ULONG arg2=0
Optional argument 2.
ULONG arg3=0
Optional argument 3.
Return Value:
An integer return value. See the documentation where the cmd option is discussed for more details on the meaning of this value.
Prototype:
virtual HINSTANCE AppInst();
Remarks:
Returns the application instance handle of 3ds max itself.
Prototype:
virtual HWND AppWnd();
Remarks:
Returns the window handle of 3ds max's main window.
Prototype:
virtual TCHAR *GetDir(int i);
Remarks:
Implemented by the System.
Retrieves the specified standard 3ds max directory name (fonts, scenes, images, etc.).
Parameters:
int i
Specifies the directory name to retrieve. See List of Directory Names.
Return Value:
The name of the specified directory.
Prototype:
virtual BOOL AddMapDir(TCHAR *dir,int update);
Remarks:
For internal use only - This is used to add a MAP PATH to the Map path list.
Prototype:
virtual int GetMapDirCount();
Remarks:
Returns the number of map paths (used in conjunction with the method below).
Return Value:
The number of map paths.
Prototype:
virtual TCHAR *GetMapDir(int i);
Remarks:
Map paths are accessed using a virtual array mechanism. This method returns the 'i-th' map path.
Parameters:
int i
Specifies the map path to retrieve.
Return Value:
The name of the 'i-th' map path.
Prototype:
virtual Interface *Max();
Remarks:
Implemented by the System.
Returns an interface pointer for calling methods provided by 3ds max. See Class Interface.
Prototype:
virtual Bitmap *NewBitmap();
Remarks:
This method is available in release 2.0 and later only.
This method is called to allocate and return a pointer to a new instance of the Bitmap class. The default constructor is used.
Prototype:
virtual Bitmap *Create(BitmapInfo *bi);
Remarks:
This method creates a new bitmap using the properties of the BitmapInfo passed. For more details on creating bitmaps, see the section Working with Bitmaps. Make sure you delete the Bitmap created when you are done using it.
Parameters:
BitmapInfo *bi
A pointer to an instance of the class BitmapInfo describing the bitmap to create.
Return Value:
A pointer to a newly created instance of class Bitmap.
Prototype:
virtual Bitmap *Create(PBITMAPINFO pbmi);
Remarks:
This method is used for creating a new bitmap from an existing Windows Device Independent Bitmap. Make sure you delete the Bitmap created when you are done using it.
Parameters:
PBITMAPINFO pbmi
An existing Windows DIB. For more details on creating bitmaps, see the section Working with Bitmaps.
Return Value:
Pointer to a new instance of class Bitmap created from the DIB.
See Also: To create a Windows DIB from a Bitmap see Bitmap::ToDib()
Prototype:
virtual Bitmap *Load(BitmapInfo *bi, BMMRES *status = NULL)
Remarks:
This method loads a bitmap using the parameters specified by the BitmapInfo pointer. Make sure you delete the Bitmap created when you are done using it.
Note: When several plug-ins call this method to load the same image, they all receive the same pointer to one instance of the BitmapStorage. So if one plug-in manipulates the image, the changes will get reflected everywhere. A developer may use BitmapManager::Create() followed by Bitmap::CopyImage() to create a unique instance of BitmapStorage.
Also Note: One of the methods in BitmapInfo returns a window handle to send progress report messages. If you want to receive these messages (for purposes of putting up a progress bar during the load), set the window handle (bi->SetUpdateWindow(hWnd)) and process BMM_PROGRESS and BMM_CHECKABORT messages.
Parameters:
BitmapInfo *bi
Specifies the properties of the bitmap to load.
BMMRES *status
The result of the bitmap load operation. See Bitmap Error Codes.
Return Value:
A pointer to a new instance of the class Bitmap.
Prototype:
virtual BMMRES LoadInto(BitmapInfo *bi, Bitmap **map, BOOL forceReload=FALSE);
Remarks:
This method loads the bitmap specified by bi into the bitmap pointed to by map. The normal Load() method creates a new bitmap. However, if you already have an existing bitmap and simply want to load in a new frame, this method may be used. Specify which bitmap to use using bi and the map to load into using map. For instance, if you have an AVI file and you want to load a new frame, you can simply update the frame number specified in the BitmapInfo and call this method passing the bitmap associates with the previous frame.
Parameters:
BitmapInfo *bi
Specifies the properties of the bitmap to load.
Bitmap **map
A pointer to a pointer to a bitmap. This is the bitmap that will be loaded into.
BOOL forceReload=FALSE
If an existing bitmap that matches bi is already loaded, then calling calling LoadInto() won't load from the disk or device. Rather it will just use the existing in memory version. If you want to force the bitmap to be reloaded from the file or device set this to TRUE.
Return Value:
The result of the bitmap load operation. See Bitmap Error Codes.
Prototype:
virtual BMMRES GetImageInfoDlg(HWND hWnd, BitmapInfo *bi, const TCHAR *filename = NULL);
Remarks:
This method will display information about the given bitmap in a dialog. The source of the information is either defined in bi->Name()/bi->Device() or explicitly in the filename passed). This method is an interface into BitmapIO::GetImageInfoDlg(). It is not normally called by developers.
The default implementation is within the Bitmap Manager. There is a generic Image Info dialog that is used unless the proper BitmapIO class implements it own dialog (and notifies the system through the BitmapIO::Capabilities() method).
Parameters:
HWND hWnd
The parent window handle calling the dialog.
BitmapInfo *bi
Defines the name of the bitmap or device (unless specified below). The image information fields of BitmapInfo *bi are set with the information loaded from the image.
const TCHAR *filename = NULL
Specifies the filename to use explicitly.
Return Value:
The result of the operation. See Bitmap Error Codes.
Prototype:
virtual BMMRES GetImageInfo(BitmapInfo *bi, const TCHAR *filename = NULL);
Remarks:
This method is used to get information about an image, ie things like image resolution (bi->Width()/bi->Height()), number of frames, etc. This is an interface into BitmapIO::GetImageInfo(). Given an image definition in bi.Name() / bi.Device() or explicitly in filename (this function will place filename, if not NULL, into bi.Name() before calling BitmapIO::GetImageInfo()), the proper device will fill the data members in BitmapInfo *bi with information about the image.
Parameters:
BitmapInfo *bi
Defines the name of the bitmap or device (unless specified below).
const TCHAR *filename = NULL
Specifies the filename to use explicitly.
Return Value:
The result of the operation. See Bitmap Error Codes.
Prototype:
virtual BOOL ImageInputOptions( BitmapInfo *bi, HWND hWnd );
Remarks:
This method brings up the standard 3ds max Image Input Options dialog box. If the users selects OK from the dialog, the appropriate data members of BitmapInfo *bi are filled specifying the user's choices. These are the 'Custom' fields accessed using methods such as GetCustomX(), GetCustomGamma(), GetCustomStep(), etc.
Parameters:
BitmapInfo *bi
The instance of BitmapInfo that is updated based on the users dialog selections.
HWND hWnd
The parent window handle for the dialog.
Return Value:
Returns TRUE if the users selects OK from the dialog; otherwise FALSE.
Prototype:
virtual BOOL SelectDeviceInput(BitmapInfo *bi, HWND hWnd);
Remarks:
Brings up the standard 3ds max Select Image Input Device dialog box. If the users selects OK from the dialog, then bi->Device() is set to the name of the users device choice.
Parameters:
BitmapInfo *bi
Points to the instance of BitmapInfo that is updated based on the users dialog selections.
HWND hWnd
The parent window handle for the dialog.
Return Value:
TRUE if the user exited the dialog using OK; otherwise FALSE.
Prototype:
virtual BOOL SelectDeviceOutput(BitmapInfo *bi, HWND hWnd);
Remarks:
Brings up the standard 3ds max Select Image Output Device dialog box. If the users selects OK from the dialog, then bi->Device() is set to the name of the users device choice.
Parameters:
BitmapInfo *bi
Points to the instance of BitmapInfo that is updated based on the users dialog selections.
HWND hWnd
The parent window handle for the dialog.
Return Value:
TRUE if the user exited the dialog using OK; otherwise FALSE.
Prototype:
virtual BOOL SelectFileOutput(BitmapInfo *bi, HWND hWnd, TCHAR *title = NULL, ULONG *pflags = NULL);
Remarks:
Brings up the standard 3ds max Browse Images for Output dialog box. If the users selects OK from the dialog, then bi->Name() is set to the name of the users file choice.
Parameters:
BitmapInfo *bi
Points to the instance of BitmapInfo that is updated based on the users dialog selections.
HWND hWnd
The parent window handle for the dialog.
TCHAR *title = NULL
The optional title string to display in the title bar of the dialog.
ULONG *pflags = NULL
This parameter is available in release 4.0 and later only.
One of the following:
BMM_ENABLE_SAVE_REGION
This flag will cause the "SaveRegion" check box to appear in the dialog.
BMM_DO_SAVE_REGION
This flag will return the state of the check box.
Return Value:
TRUE if the user exited the dialog using OK; otherwise FALSE.
virtual BOOL SelectFileOutput ( BitmapInfo *bi, HWND hWnd, TCHAR *title = NULL, ULONG *pflags = NULL)
Prototype:
virtual BOOL SelectFileInput(BitmapInfo *bi, HWND hWnd, TCHAR *title = NULL);
Remarks:
Brings up the standard 3ds max Browse Images for Input dialog box. If the users selects OK from the dialog, then bi->Name() is set to the name of the users file choice.
Parameters:
BitmapInfo *bi
The instance of BitmapInfo that is updated based on the users dialog selections.
HWND hWnd
The parent window handle for the dialog.
TCHAR *title = NULL
The optional title string to display in the title bar of the dialog.
Return Value:
TRUE if the user exited the dialog using OK; otherwise FALSE.
Prototype:
virtual BOOL SelectFileInputEx(BitmapInfo *bi, HWND hWnd, TCHAR *title = NULL, BOOL viewonly = FALSE);
Remarks:
This method brings up the standard 3ds max Browse Images for Input dialog box (the same as SelectFileInput()) but a "Devices" button is present so the user can select both image files and image devices.
Parameters:
BitmapInfo *bi
The instance of BitmapInfo that is updated based on the users dialog selections.
HWND hWnd
The parent window handle for the dialog.
TCHAR *title = NULL
The optional title string to display in the title bar of the dialog.
BOOL viewonly = FALSE
If viewonly is set to TRUE, the View button is hidden in the dialog.
Return Value:
TRUE if the user exited the dialog using OK; otherwise FALSE.
Prototype:
virtual INT_PTR Execute(int cmd, ULONG arg1=0, ULONG arg2=0, ULONG arg3=0)=0;
Remarks:
This method is available in release 2.0 and later only.
This is a general purpose function that allows the API to be extended in the future. The 3ds max development team can assign new cmd numbers and continue to add functionality to this class without having to 'break' the API.
Parameters:
int cmd
The index of the command to execute.
ULONG arg1=0
Optional argument 1. See the documentation where the cmd option is discussed for more details on these parameters.
ULONG arg2=0
Optional argument 2.
ULONG arg3=0
Optional argument 3.
Return Value:
An integer return value. See the documentation where the cmd option is discussed for more details on the meaning of this value.
Prototype:
virtual void BeginSavingLoadErrorFiles()=0;
Remarks:
This method is available in release 3.0 and later only.
This method is used for accumulating the names of bitmap files that didn't load. Instead of having the BitmapManager display the missing file dialog, it now just collects the names (which can be retrieved using GetLoadErrorFileList() below).
Prototype:
virtual NameTab &GetLoadErrorFileList()=0;
Remarks:
This method is available in release 3.0 and later only.
This method will return a list of names of bitmap files that were not found as discussed in the method above. See Class NameTab.
Prototype:
virtual void EndSavingLoadErrorFiles()=0;
Remarks:
This method is available in release 3.0 and later only.
This method ends the accumulation of a list of bitmap files that didn't load, and frees the list. See the two methods above.
Prototype:
virtual bool CanImport(const TCHAR* filename)=0;
Remarks:
This method is available in release 3.0 and later only.
Returns true if the extension of the specified file name is one of the supported types (i.e. there is a BitmapIO module for it); otherwise false.
Parameters:
const TCHAR* filename
The file name to check.