Class Bitmap
See Also: Class BitmapManager, Class BitmapInfo, Class BitmapStorage, Class GBuffer, Working with Bitmaps.
class Bitmap : public BaseInterfaceServer
Description:
The Bitmap class is the bitmap itself. All image access is done through this class. The Bitmap class has methods to retrieve properties of the bitmap such as image width, height, whether it is dithered, has an alpha channel, etc. There are methods to retrieve and store pixels from the image. Additional methods allow a developer to copy bitmaps. This class also has methods to open outputs and write multi-frame files. All methods of this class are implemented by the system.
Data Members:
protected:
float gamma;
The gamma setting for the bitmap.
Bitmap *map;
The bitmap using this output handler.
BitmapStorage *storage;
The storage used by this INPUT handler
int openMode;
The mode the bitmap is open in.
BitmapIO *prevIO;
BitmapIO *nextIO;
Linked list pointers for multiple output of a single bitmap.
Method Groups:
These hyperlinks jump to the start of groups of related methods within the class.
Bitmap Properties (Size, Aspect, Gamma, etc.)
Copying / Cropping / Converting
Display (Virtual Frame Buffer) Methods
Execute -- Generic Expansion Method
Methods:
Prototype:
inline BitmapManager *Manager()
Remarks:
Returns a pointer to the bitmap manager being used.
Prototype:
void DeleteThis();
Remarks:
This method is available in release 2.0 and later only.
This method should be called to free the Bitmap. Note that you should not invoke ~Bitmap() directly by calling delete on the Bitmap as was done in 3ds max1.x. An assert will be raised if you call delete on a Bitmap directly. Instead use this method.
Prototype:
inline DWORD Flags()
Remarks:
Returns the state of the bitmap flags. These flags describe properties of the bitmap such as if the bitmap is flipped horizontally or inverted vertically, is paletted, is dithered, etc. See Bitmap Flags
Prototype:
inline void SetFlag(DWORD flag)
Remarks:
Sets the specified flag bit(s).
Parameters:
DWORD flag
The flag(s) to set. See Bitmap Flags.
Prototype:
inline void ToggleFlag(DWORD flag)
Remarks:
Toggles the specified flag bit(s) on/off.
Parameters:
DWORD flag
The flag(s) to toggle. See Bitmap Flags.
Prototype:
inline void ClearFlag(DWORD flag)
Remarks:
Clears the specified flag bit(s) (sets them to zero).
Parameters:
DWORD flag
The flag(s) to clear. See Bitmap Flags.
The following methods return properties of the bitmap. When these methods are called, they are passed through to the BitmapStorage instance maintained by the Bitmap. The BitmapStorage implements these methods by returning the properties of the BitmapInfo instance maintained by the storage. Therefore, the values returned from the methods represent what is returned from the BitmapInfo instance associated with the Bitmap.
Prototype:
inline int Width()
Remarks:
Returns the width of the bitmap (the horizontal dimension).
Return Value:
If storage has been allocated the width of the bitmap; otherwise 0.
Prototype:
inline int Height()
Remarks:
Returns the height (vertical dimension) of the bitmap.
Return Value:
If storage has been allocated the height of the bitmap; otherwise 0.
Prototype:
inline float Aspect()
Remarks:
Returns the aspect ratio of the bitmap.
Return Value:
If storage has been allocated the aspect ratio of the bitmap; otherwise 0.0f.
Prototype:
inline float Gamma()
Remarks:
Returns the gamma value for the bitmap.
Return Value:
If storage has been allocated the gamma of the bitmap; otherwise 0.0f.
Prototype:
inline int Paletted()
Remarks:
Returns whether the bitmap uses a palette (is not true color).
Return Value:
If storage has been allocated returns nonzero if the bitmap uses a palette (returns the number of palette slots used); otherwise 0.
Prototype:
inline int IsDithered()
Remarks:
Returns whether the bitmap is dithered or not.
Return Value:
If storage has been allocated returns nonzero if the bitmap is dithered; otherwise 0.
Prototype:
inline int PreMultipliedAlpha()
Remarks:
Returns whether the bitmap uses pre-multiplied alpha.
Return Value:
If storage has been allocated returns nonzero if the bitmap uses pre-multiplied alpha; otherwise 0.
Prototype:
inline int HasAlpha()
Remarks:
Returns whether the bitmap has an alpha channel.
Return Value:
If storage has been allocated returns nonzero if the bitmap has an alpha channel; otherwise 0.
Prototype:
inline int MaxRGBLevel()
Remarks:
This method returns the number of bits per pixel for each color component. For example a 24-bit TARGA has a MaxRGBLevel() of 8.
Prototype:
virtual int MaxAlphaLevel() = 0;
Remarks:
Implemented by the System.
Returns the number of bits per pixel in the alpha channel.
Return Value:
If storage has not been allocated returns 0.
Prototype:
virtual int IsHighDynamicRange() = 0;
Remarks:
This method is available in release 4.0 and later only.
Returns nonzero if this is a bitmap that supports high dynamic range data; zero if it doesn't.
Prototype:
BMMRES GoTo(BitmapInfo *bi);
Remarks:
This method is used with multi-frame bitmaps (FLI's, AVI's, DDR devices, etc.). It is used to load a frame to replace a previously saved image. To define the desired frame, use:
bi->SetCurrentFrame(frame);
Parameters:
BitmapInfo *bi
A pointer to the BitmapInfo. The frame number information is passed here.
Return Value:
If used with single frame drivers or if the driver doesn't support this function, it returns BMMRES_SINGLEFRAME. If the return value is BMMRES_SUCCESS, a new frame has been loaded into the given bitmap.
Standard Pixel Access Methods.
Note: The following methods access pixel data one scanline at a time. Thus x+pixels must be less than the bitmap width.
Prototype:
inline int Get16Gray(int x,int y,int pixels,float *ptr)
Remarks:
Retrieves the specified 16-bit pixel values from the bitmap. Note: This method provides access to pixel data one scanline at a time.
Parameters:
int x
Source x location.
int y
Source y location.
int pixels
Number of pixels to retrieve.
float *ptr
Pointer to storage for the retrieved pixel values.
Return Value:
Returns nonzero if pixels were retrieved; otherwise 0. If storage has not been allocated 0 is returned.
Prototype:
int Put16Gray(int x,int y,int pixels,float *ptr)
Remarks:
Stores the specified 16-bit pixel values into the bitmap. The pixel value pointer you pass to this method may be freed or reused as soon as the function returns. Note: This method provides access to pixel data one scanline at a time.
Parameters:
int x
Destination x location.
int y
Destination y location.
int pixels
Number of pixels to store.
float *ptr
Pixel values to store.
Return Value:
Returns nonzero if pixels were stored; otherwise 0. If storage has not been allocated 0 is returned.
Prototype:
inline int GetPixels(int x,int y,int pixels,BMM_Color_fl *ptr)
Remarks:
Retrieves the specified 64-bit pixel values from the bitmap. Note: This method provides access to pixel data one scanline at a time.
Parameters:
int x
Source x location.
int y
Source y location.
int pixels
Number of pixels to retrieve.
BMM_Color_fl *ptr
Pointer to storage for the retrieved pixel values. See Structure BMM_Color_fl.
Return Value:
Returns nonzero if pixels were retrieved; otherwise 0. If storage has not been allocated 0 is returned.
Prototype:
int PutPixels(int x,int y,int pixels,BMM_Color_fl *ptr)
Remarks:
Stores the specified 64-bit pixel values into the bitmap's own local storage. The pointer you pass to this method may be freed or reused as soon as the function returns. Note: This method provides access to pixel data one scanline at a time.
Parameters:
int x
Destination x location.
int y
Destination y location.
int pixels
Number of pixels to store.
BMM_Color_fl *ptr
Pixel values to store. See Structure BMM_Color_fl.
Return Value:
Returns nonzero if pixels were stored; otherwise 0. If storage has not been allocated 0 is returned.
Prototype:
inline int GetLinearPixels(int x,int y,int pixels,BMM_Color_64 *ptr)
Remarks:
Retrieves the specified 64-bit pixel values from the bitmap. These pixels are NOT gamma corrected (i.e. they have linear gamma - 1.0). Note: This method provides access to pixel data one scanline at a time.
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 pixel values. See Structure BMM_Color_64.
Return Value:
Returns nonzero if pixels were retrieved; otherwise 0. If storage has not been allocated 0 is returned.
Prototype:
inline int GetIndexPixels(int x,int y,int pixels,BYTE *ptr)
Remarks:
Retrieves the specified pixels from the paletted bitmap. The palette for the image may be accessed using GetPalette(). Note: This method provides access to pixel data one scanline at a time.
Parameters:
int x
Source x location.
int y
Source y location.
int pixels
Number of pixels to retrieve.
BYTE *ptr
Pointer to storage for the pixel values.
Return Value:
Returns nonzero if pixels were retrieved; otherwise 0. If storage has not been allocated 0 is returned.
Prototype:
inline int PutIndexPixels(int x,int y,int pixels,BYTE *ptr)
Remarks:
Stores the pixels into the specified location of the paletted bitmap. The pixel value pointer you pass to this method may be freed or reused as soon as the function returns. Note: This method provides access to pixel data one scanline at a time.
Parameters:
int x
Destination x location.
int y
Destination y location.
int pixels
Number of pixels to store.
BYTE *ptr
Pixels to store.
Return Value:
Returns nonzero if pixels were stored; otherwise 0. If storage has not been allocated 0 is returned.
Prototype:
inline int GetPalette(int start,int count,BMM_Color_48 *ptr)
Remarks:
Retrieves a portion of the palette from the bitmap.
Parameters:
int start
The index into the palette of where to begin retrieving palette entries.
int count
The number of palette entries to retrieve.
BMM_Color_48 *ptr
Storage for the palette entries. See Structure BMM_Color_48.
Return Value:
Nonzero if the palette entries were retrieved; otherwise 0.
Prototype:
inline int SetPalette(int start,int count,BMM_Color_48 *ptr)
Remarks:
Sets the specified portion of the palette of this bitmap.
Parameters:
int start
The index into the palette of where to begin storing palette entries.
int count
The number of palette entries to store.
BMM_Color_48 *ptr
The palette entries to store. See Structure BMM_Color_48.
Return Value:
Nonzero if the palette entries were stored; otherwise 0.
Prototype:
int GetFiltered(float u, float v, float du, float dv, BMM_Color_fl *ptr);
Remarks:
This method uses summed area table or pyramidal filtering to compute an averaged color over the specified area. You must have a filter plugged in for this to work. See SetFilter() below.
Parameters:
float u, float v
The location in the bitmap to filter. These values go from 0.0 to 1.0 across the size of the bitmap.
float du, float dv
The size of the rectangle to sample. These values go from 0.0 to 1.0 across the size of the bitmap.
BMM_Color_fl *ptr
The result is returned here -- the average over the specified area. See Structure BMM_Color_fl. **aztodo** link this
Prototype:
inline int CopyImage(Bitmap *from,int operation,BMM_Color_fl fillcolor, BitmapInfo *bi = NULL)
Remarks:
Copies the specified bitmap to this bitmap.
Parameters:
Bitmap *from
The source bitmap.
int operation
The type of copy to perform:
COPY_IMAGE_CROP
Copy image to current map size using cropping if necessary.
COPY_IMAGE_RESIZE_LO_QUALITY
Resize the source image to the destination map size (draft quality).
COPY_IMAGE_RESIZE_HI_QUALITY
Resize source image to the destination map size (final quality).
COPY_IMAGE_USE_CUSTOM
Resize based on the Image Input Options (BitmapInfo *).
BMM_Color_fl fillcolor
Vacant areas of the bitmap are filled with fillcolor pixels if the operation specified is COPY_IMAGE_CROP and one of the source bitmap dimensions is less than the size of this bitmap. See Structure BMM_Color_fl.
BitmapInfo *bi = NULL
When using custom options (resize to fit, positioning, etc.) this is how the flags are passed down to the Bitmap Manager. This is an optional argument -- for simple copy operations, *bi can default to NULL. If present, the code checks the option flags and acts accordingly.
Return Value:
Nonzero if the copy was performed; otherwise 0.
Prototype:
inline int CopyImage(Bitmap *from,int operation,int fillindex)
Remarks:
Copies the specified bitmap to this bitmap.
Parameters:
Bitmap *from
The source bitmap.
int operation
The type of copy to perform. See List of Copy Image Operations.
int fillindex
Vacant areas of the bitmap are filled with fillindex pixels if the operation specified is COPY_IMAGE_CROP and one of the source bitmap dimensions is less than the size of this bitmap.
Return Value:
Nonzero if the copy was performed; otherwise 0.
Prototype:
PBITMAPINFO ToDib(int depth = 24, UWORD *gam=NULL, BOOL dither=FALSE);
Remarks:
Creates a new Windows Device Independent Bitmap (DIB) and returns a pointer to it. The DIB bitmap is created from this Bitmap. The DIB is allocated using LocalAlloc(). The pseudo-code below show how one may be created and freed. Note that the DIB is never used or accessed inside 3ds max (the call to ToDib() is the first and last time that 3ds max sees this pointer):
PBITMAPINFO pDib;
pDib = bitmap->ToDib();
...
When you are done using the DIB call:
LocalFree(pDib);
Parameters:
int depth = 24
The bitmap depth; either 24 (BGR) or 32 (BGRO). If not specified the default is 24.
UWORD *gam=NULL
Specifies a pointer to an optional gamma table that is used to apply gamma correction to the color components as part of the conversion to a DIB. The table has RCOLN entries.
BOOL dither=FALSE
Specifies if a random dither is applied when reducing the color components from 16 bits per channel to 8 bits per channel (to reduce banding effects).
Prototype:
BOOL FromDib(PBITMAPINFO pbmi);
Remarks:
Converts the DIB to this bitmap's storage type. This bitmap's storage must already be allocated or the call will fail. The source must be 16, 24 or 32 bit. You cannot use an 8 bit DIB.
Parameters:
PBITMAPINFO pbmi
The source bitmap.
Return Value:
TRUE if the conversion was performed; otherwise FALSE.
Prototype:
inline int ResizeImage(int width,int height,int newpalette)
Remarks:
This method is not currently implemented.
Prototype:
inline void *GetChannel(ULONG channelID, ULONG& chanType)
Remarks:
Returns a pointer to the specified channel of the bitmap, and determines its type in terms of bits per pixel.
Parameters:
ULONG channelID
The channel to return a pointer to. See List of Image Channels.
ULONG& chanType
The type of the returned channel. One of the following values:
BMM_CHAN_TYPE_UNKNOWN
Channel not of a known type.
BMM_CHAN_TYPE_8
1 byte per pixel
BMM_CHAN_TYPE_16
1 word per pixel
BMM_CHAN_TYPE_32
2 words per pixel
BMM_CHAN_TYPE_48
3 words per pixel
BMM_CHAN_TYPE_64
4 words per pixel
BMM_CHAN_TYPE_96
6 words per pixel
Prototype:
GBuffer *GetGBuffer();
Remarks:
This method is available in release 3.0 and later only.
Returns a pointer to the GBuffer for the bitmap (or NULL if none).
Prototype:
inline ULONG CreateChannels(ULONG channelIDs)
Remarks:
This method creates the specified channels. After creation, these may be accessed using void *GetChannel().
Parameters:
ULONG channelIDs
Specifies the channels to create. See List of Image Channels.
Return Value:
The channels that are present.
Prototype:
inline void DeleteChannels(ULONG channelIDs)
Remarks:
Delete the specified channels.
Parameters:
ULONG channelIDs
Specifies the channels to delete. See List of Image Channels.
Prototype:
inline ULONG ChannelsPresent()
Remarks:
Returns the channels that are present. See List of Image Channels.
Prototype:
inline RenderInfo *GetRenderInfo()
Remarks:
This is used internally. It returns a pointer to the RenderInfo associated with the storage if available; otherwise NULL. See Class RenderInfo.
Prototype:
inline RenderInfo *AllocRenderInfo()
Remarks:
This is used internally. It returns a pointer to the RenderInfo instance allocated by the storage. If this could not be allocated NULL is returned. See Class RenderInfo.
Prototype:
BOOL PrepareGChannels(BitmapInfo *bi);
Remarks:
This method is used internally. This method will check with the plug-in (file or device) defined in the given BitmapInfo and prepare (create) the proper channels. If a given channel already exists, no new channel will be created. After creating a bitmap, use this function to define the optional channels that may be required by the given handler.
Parameters:
BitmapInfo *bi
Points to an instance of BitmapInfo that defines the properties of the image.
Return Value:
TRUE if the channels were created; otherwise FALSE.
Prototype:
int GetFiltered(float u, float v, float du, float dv, BMM_Color_fl *ptr);
Remarks:
This method uses summed area table or pyramidal filtering to compute an averaged color over the specified area. You must have a filter plugged in for this to work. See SetFilter() below.
Parameters:
float u, float v
The location in the bitmap to filter. These values go from 0.0 to 1.0 across the size of the bitmap.
float du, float dv
The size of the rectangle to sample. These values go from 0.0 to 1.0 across the size of the bitmap.
BMM_Color_fl *ptr
The result is returned here -- the average over the specified area.
Prototype:
int SetFilter(UINT filterType);
Remarks:
Establishes a filtering algorithm to be used by the bitmap.
Parameters:
UINT filterType
See List of Bitmap Filter Types.
Return Value:
Nonzero if the bitmap filtering was set; otherwise 0.
Prototype:
inline int HasFilter()
Remarks:
Determines if the bitmap has a filter.
Return Value:
Returns nonzero if the bitmap has a filter; otherwise 0.
Prototype:
int SetDither(UINT ditherType);
Remarks:
Sets the type of dithering used on the bitmap.
Parameters:
UINT ditherType
The type of dither to perform.
BMM_DITHER_NONE
Specifies no dithering is to be performed.
BMM_DITHER_FLOYD
Specifies the Floyd-Steinberg dithering algorithm.
Return Value:
Nonzero if the bitmap dithering was set; otherwise 0.
Prototype:
inline BitmapFilter *Filter()
Remarks:
This method is used internally. It returns a pointer to the bitmap filter used by the bitmap.
Prototype:
int SetStorage(BitmapStorage *storage);
Remarks:
Establishes a bitmap storage to manage this bitmap.
Parameters:
BitmapStorage *storage
The storage to manage the bitmap.
Return Value:
Nonzero if the storage was assigned; otherwise 0.
Prototype:
inline BitmapStorage *Storage()
Remarks:
Returns the storage that is managing this bitmap.
Return Value:
A pointer to the storage.
Prototype:
inline void NullStorage();
Remarks:
Sets the storage pointer to NULL.
Output / Writing / Closing Methods
Prototype:
BMMRES OpenOutput(BitmapInfo *bi);
Remarks:
This method will open the image for output. This allows the image to be written to. Note that you can pass a BitmapInfo to this method where you simply set the name 'by hand' (bi->SetName()). This will work and the correct driver wil be selected based on the filename extension. However you won't be able to set any driver specific settings (such as compression settings for JPEGs). The alternative way is to use the BitmapManger methods.
Parameters:
BitmapInfo *bi
Contains the name of the image or device to open for output.
Return Value:
BMMRES_SUCCESS
Indicates success.
BMMRES_ERRORTAKENCARE
Indicates that 3ds max could not find a device to handle the image.
BMMRES_INTERNALERROR
Indicates the IO module handling the image could not be opened for writing.
Prototype:
BMMRES Write(BitmapInfo *bi, DWORD frame = BMM_SINGLEFRAME)
Remarks:
Write the image from the BitmapStorage to disk. Note that you must pass the same BitmapInfo used when the file was first "Opened for Output". The main reason is that any device specific settings are kept in the BitmapInfo object. Also, the custom options such as gamma value, optional channels, etc (if any) are kept in this BitmapInfo instance. These are assigned when the bitmap is first opened (for either read or write).
Parameters:
BitmapInfo *bi
Contains the name of the file or device to write to.
DWORD frame = BMM_SINGLEFRAME
Specifies the frame number to write. If this is a single image, allow frame to default to single frame. This argument determines if the file will have the frame number appended to it. If you want the file to have a normal name (no frame number attached to it), you must set the frame argument to BMM_SINGLEFRAME. Any other value is considered to be a frame number and it will be appended to the given filename.
Return Value:
BMMRES_SUCCESS
Indicates success.
BMMRES_ERRORTAKENCARE
Indicates that 3ds max could not find a device to handle the image.
BMMRES_INTERNALERROR
Indicates the IO module handling the image could not be opened for writing.
Prototype:
BMMRES WriteAll(DWORD frame = BMM_SINGLEFRAME);
Remarks:
Write the image to all the open outputs.
Parameters:
DWORD frame = BMM_SINGLEFRAME
Specifies the frame number to write. If this is a single image, allow frame to default to single frame.
Return Value:
BMMRES_SUCCESS
Indicates success.
BMMRES_ERRORTAKENCARE
Indicates that 3ds max could not find a device to handle the image.
BMMRES_INTERNALERROR
Indicates the IO module handling the image could not be opened for writing.
Prototype:
int Close(BitmapInfo *bi, int flag = BMM_CLOSE_COMPLETE)
Remarks:
Close the bitmap. This means the bitmap is no longer open for writing.
Parameters:
BitmapInfo *bi
Identifies the bitmap to close.
int flag = BMM_CLOSE_COMPLETE
See List of Bitmap Close Types.
Return Value:
Nonzero if the image output was closed without error; otherwise 0.
Prototype:
int CloseAll(int flag = BMM_CLOSE_COMPLETE)
Remarks:
Closes all the open outputs.
Parameters:
int flag = BMM_CLOSE_COMPLETE
See List of Bitmap Close Types.
Return Value:
Nonzero if the image outputs were closed without error; otherwise 0.
Prototype:
inline void UseScaleColors(int on);
Remarks:
This method is available in release 4.0 and later only.
Implemented by the System.
Set whether colors are scaled (on) or clamped (off) when converting from BMM_Color_fl to BMM_Color_64. If storage is not allocated, does nothing.
Prototype:
inline int ScaleColors();
Remarks:
This method is available in release 4.0 and later only.
Implemented by the System.
Returns the last value set by UseScaleColors. If storage is not allocated, returns 0.
Prototype:
inline static void ClampColor(BMM_Color_64& out, const BMM_Color_fl& in);
Remarks:
This method is available in release 4.0 and later only.
Implemented by the System.
Converts in to out clamping the RGB components to 0 to 65535. The alpha component is not copied.
Parameters:
BMM_Color_64& out
The result of the conversion.
BMM_Color_fl& in
The value to convert.
Prototype:
inline static void ClampColorA(BMM_Color_64& out, const BMM_Color_fl& in);
Remarks:
This method is available in release 4.0 and later only.
Implemented by the System.
Converts in to out clamping the RGB components to 0 to 65535.
Parameters:
BMM_Color_64& out
The result of the conversion.
BMM_Color_fl& in
The value to convert.
Prototype:
inline void ScaleColor (BMM_Color_64& out, BMM_Color_fl in);
Remarks:
This method is available in release 4.0 and later only.
Implemented by the System.
Converts in to out clamping the RGB components to 0 to 65535. The alpha component is not copied.
Parameters:
BMM_Color_64& out
The result of the conversion.
BMM_Color_fl& in
The value to convert.
Prototype:
inline void ScaleColorA(BMM_Color_64& out, const BMM_Color_fl& in);
Remarks:
This method is available in release 4.0 and later only.
Implemented by the System.
Converts in to out clamping the RGB components to 0 to 65535.
Parameters:
BMM_Color_64& out
The result of the conversion.
BMM_Color_fl& in
The value to convert.
Prototype:
inline void ClampScaleColor (BMM_Color_64& out, const BMM_Color_fl& in);
Remarks:
This method is available in release 4.0 and later only.
Implemented by the System.
Converts in to out, using the value of ScaleColors() to determine the clamping or scaling. The alpha component is not copied. If the storage is not allocated, the clamping is performed.
Parameters:
BMM_Color_64& out
The result of the conversion.
BMM_Color_fl& in
The value to convert.
Prototype:
inline void ClampScaleColorA (BMM_Color_64& out, const BMM_Color_fl& in);
Remarks:
This method is available in release 4.0 and later only.
Implemented by the System.
Converts in to out, using the value of ScaleColors() to determine the clamping or scaling. If the storage is not allocated, the clamping is performed.
Parameters:
BMM_Color_64& out
The result of the conversion.
BMM_Color_fl& in
The value to convert.
Display (Virtual Frame Buffer) Methods
Prototype:
int Display(TCHAR *title=NULL, int position=BMM_CN, BOOL autonomous=FALSE, BOOL savebutton=TRUE, CropCallback *crop=NULL, Bitmap *cloneMyVFB = NULL)
Remarks:
This method creates a window for the display of this bitmap and displays it.
Parameters:
TCHAR *title = NULL
The title to display in the title bar of the window.
int position = BMM_CN
Specifies how the bitmap should be positioned. One of the following values:
BMM_UL - Upper Left
BMM_LL - Lower Left
BMM_UR - Upper Right
BMM_LR - Lower Right
BMM_CN - Center
BMM_RND - Used internally. Renderer location.
BMM_VPP - Used internally. Video Post Primary location.
BMM_VPS - Used internally. Video Post Secondary location.
BOOL autonomous = FALSE
This is reserved for internal use, always let it default to FALSE.
BOOL savebutton = TRUE
This is reserved for internal use, always let it default to TRUE.
CropCallback *crop=NULL
This parameter is available in release 2.0 and later only.
When non-NULL this will cause the VFB to display, instead of its normal toolbar, a set of sliders for adjusting cropping and also will allow interactive adjustment of the cropping rectangle in the image window. See Class CropCallback.
Bitmap *cloneMyVFB = NULL
This parameter is available in release 4.0 and later only.
A pointer to a bitmap to clone the VFB to.
Return Value:
Nonzero if the bitmap was displayed; otherwise 0.
Prototype:
int UnDisplay();
Remarks:
Close the display window associated with this bitmap (if any).
Return Value:
Always returns nonzero.
Prototype:
BOOL IsAutonomousVFB();
Remarks:
This method is available in release 2.0 and later only.
Returns TRUE if the virtual frame buffer (VFB) is autoomous; otherwise FALSE. For instance, Video Post has an associated VFB. When Video Post is closed so is its VFB since it belongs to it. In that case the VFB is not autonomous. If the user does a View File command, that VFB is autonomous.
Prototype:
HWND GetWindow();
Remarks:
Get the window handle for the displayed bitmap.
Return Value:
Returns the window handle, or NULL if it's not displayed in a window.
Prototype:
void RefreshWindow(RECT *rect = NULL);
Remarks:
Refreshes the interior of the display window with the bitmap contents. In release 3.0 and later this method respects the Bitmap::ShowProgressLine() setting. See that method for more details.
Parameters:
RECT *rect = NULL
The region of the display window to refresh (specified in image coordinates). If the pointer is NULL the entire window is refreshed.
Prototype:
void SetCroppingValues(float u, float v, float w, float h, BOOL placeImage);
Remarks:
This method is available in release 2.0 and later only.
This method is used when the VFB is being displayed and you want to change the cropping rectangle from your plug-in. An example of this is available in \MAXSDK\SAMPLES\MATERIALS\BMTEX.CPP.
Parameters:
float u
The U value to set.
float v
The U value to set.
float w
The U value to set.
float h
The U value to set.
BOOL placeImage
TRUE for place mode; FALSE for crop.
Prototype:
void SetWindowTitle(TCHAR *title);
Remarks:
Sets the title displayed in the display window's title bar.
Parameters:
TCHAR *title
The title to display.
Prototype:
void SetNotify(BitmapNotify *bmnot=NULL);
Remarks:
This method is available in release 2.0 and later only.
This method is used to set a callback to allow the developer to get notified if the storage for the Bitmap has changed.
Parameters:
BitmapNotify *bmnot=NULL
The pointer to the callback object implemented by the developer used to provide notification when the Bitmap's storage changes. See Class BitmapNotify.
Prototype:
BitmapNotify *GetNotify();
Remarks:
This method is available in release 2.0 and later only.
Returns a pointer to the callback used to notify a developer when the Bitmap's storage changes.
Default Implementation:
{ return bmNotify; };
Execute -- Generic Expansion Method
Prototype:
INT_PTR Execute(int cmd, ULONG arg1=0, ULONG arg2=0, ULONG arg3=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.
Handy built-in functions
Prototype:
int Fill(int r,int g,int b,int alpha);
Remarks:
Sets every pixel of the bitmap to the specified color and alpha value.
Parameters:
int r
Specifies the red value to fill with.
int g
Specifies the green value to fill with.
int b
Specifies the blue value to fill with.
int alpha
Specifies the alpha value to fill with.
Return Value:
Nonzero if the operation succeeded; otherwise FALSE.
Prototype:
void Print(bool silent = false);
Remarks:
This method is available in release 3.0 and later only.
This method is only supported in 3D Studio VIZ.
Prototype:
void ShowProgressLine(int y);
Remarks:
This method is available in release 3.0 and later only.
This method is used for showing a moving scanline in a virtual frame buffer displaying this bitmap. Here's how it works. If you call ShowProgressLine(y), it clears any previously set white line, and sets an internal counter: you have to call Bitmap::RefreshWindow() to get the new white line to show up. From then that line will be displayed as white. To Clear it call ShowProgressLine(-1).
Parameters:
int y
The scanline to display as white (the count begins at zero). Use a value of -1 to hide the line.