Public Member Functions

BitmapInfo Class Reference

This reference page is linked to from the following overview topics: Principal Bitmap Classes, Creating Bitmaps, Loading Bitmaps, Saving Bitmaps, Multi-frame Files, Custom Bitmap Properties, Aspect Ratio, Error Reporting, Bitmap Gamma Overview, Changing Bitmap Texture Map Gamma.


Search for all occurrences

Detailed Description

See also:
Class Bitmap, Working with Bitmaps, Bitmap Error (result) Codes.

Description:
This class describes the properties of a bitmap such as its path name or device name, width, height, gamma, number of frames, etc. Methods are available to set and retrieve these properties. All methods are implemented by the system unless noted otherwise.
Method Groups:
See Method Groups for Class BitmapInfo.

#include <bitmap.h>

Inheritance diagram for BitmapInfo:
Inheritance graph
[legend]

List of all members.

Public Member Functions

BMMExport  BitmapInfo ()
BMMExport  BitmapInfo (const MCHAR *n)
BMMExport  BitmapInfo (const MaxSDK::AssetManagement::AssetUser &asset)
BMMExport  BitmapInfo (const BitmapInfo &bi)
BMMExport  ~BitmapInfo ()
BMMExport DWORD  Flags ()
BMMExport DWORD  SetFlags (DWORD f)
BMMExport DWORD  ResetFlags (DWORD f)
BMMExport BOOL  TestFlags (DWORD f)
BMMExport WORD  Width ()
BMMExport WORD  Height ()
BMMExport float  Gamma ()
BMMExport float  Aspect ()
BMMExport int  Type ()
BMMExport int  FirstFrame ()
BMMExport int  LastFrame ()
BMMExport int  NumberFrames ()
BMMExport int  CurrentFrame ()
BMMExport WORD  SequenceOutBound ()
BMMExport const MCHAR *  Name () const
  Returns the currently set path of the image file.
BMMExport MaxSDK::Util::Path  GetPathEx () const
  Returns the currently set path of the image file.
BMMExport const MCHAR *  Filename ()
BMMExport const MCHAR *  Device ()
BMMExport BOOL  CompareName (BitmapInfo *bi)
BMMExport void  CopyImageInfo (BitmapInfo *from)
BMMExport int  SetFirstFrame (int m)
BMMExport int  SetLastFrame (int s)
BMMExport int  SetCurrentFrame (int v)
BMMExport WORD  SetSequenceOutBound (WORD c)
BMMExport WORD  SetWidth (WORD s)
BMMExport WORD  SetHeight (WORD u)
BMMExport float  SetGamma (float c)
BMMExport float  SetAspect (float k)
BMMExport int  SetType (int s)
BMMExport void  SetPath (const MaxSDK::Util::Path &path)
  Set the path to the image file.
BMMExport const MCHAR *  SetName (const MCHAR *n)
  Set the path to the image file.
BMMExport const
MaxSDK::AssetManagement::AssetUser
GetAsset () const
  returns this bitmap's asset
BMMExport void  SetAsset (const MaxSDK::AssetManagement::AssetUser &assetUser)
  sets this bitmap's asset
BMMExport const MCHAR *  SetDevice (const MCHAR *d)
BMMExport WORD  CustWidth ()
BMMExport WORD  CustHeight ()
BMMExport void  SetCustWidth (WORD w)
BMMExport void  SetCustHeight (WORD h)
BMMExport int  StartFrame ()
BMMExport int  EndFrame ()
BMMExport void  SetStartFrame (int s)
BMMExport void  SetEndFrame (int e)
BMMExport void  SetCustomX (int x)
BMMExport void  SetCustomY (int y)
BMMExport int  GetCustomX ()
BMMExport int  GetCustomY ()
BMMExport void  SetCustomGamma (float g)
BMMExport float  GetCustomGamma ()
BMMExport float  GetEffectiveGamma ()
BMMExport void  SetCustomStep (int s)
BMMExport int  GetCustomStep ()
BMMExport void  SetPresetAlignment (int p)
BMMExport int  GetPresetAlignment ()
BMMExport DWORD  GetCustomFlags ()
BMMExport void  SetCustomFlag (DWORD f)
BMMExport void  ResetCustomFlag (DWORD f)
BMMExport BOOL  TestCustomFlags (DWORD f)
BMMExport void *  GetPiData ()
BMMExport void  SetPiData (void *ptr)
BMMExport DWORD  GetPiDataSize ()
BMMExport void  SetPiDataSize (DWORD s)
BMMExport void  ResetPiData ()
BMMExport BOOL  AllocPiData (DWORD size)
BMMExport BitmapInfo GetProxySubject (BOOL create=FALSE)
  Returns the subject info of the proxy. When create is TRUE, the subject info will be allocated if it was null.
BMMExport void  ResetProxySubject ()
  Deletes the subject info and sets it to null.
BMMExport BOOL  AllocProxySubject ()
  Creates the subject info.
BMMExport void *  CreateFmtSpecBlock (void)
BMMExport void  Copy (const BitmapInfo *from, BOOL copyProxySubject)
  Assignment function. The data members of the specified BitmapInfo are copied to this BitmapInfo, with option to also copy the proxySubject info.
BMMExport void  Copy (const BitmapInfo *from)
BMMExport BitmapInfo operator= (const BitmapInfo &from)
BMMExport IOResult  Save (ISave *isave)
BMMExport IOResult  Load (ILoad *iload)
BMMExport void  EnumAuxFiles (AssetEnumCallback &assetEnum, DWORD flags)
BMMExport BOOL  Validate ()
BMMExport HWND  GetUpdateWindow ()
BMMExport void  SetUpdateWindow (HWND hwnd)
BMMExport DWORD  GetGChannels ()
BMMExport DWORD  GetDeviceFlags ()
BMMExport BOOL  FixDeviceName ()
  Sets the appropriate device name, as derived from the filename.

Constructor & Destructor Documentation

BMMExport BitmapInfo ( )
Remarks:
Constructor. The following defaults are set by this constructor.

The width = 640;

The height = 480;

The custom width = 320;

The custom height = 200;

The custom flags = BMM_CUSTOM_RESFIT | BMM_CUSTOM_FILEGAMMA;

The custom gamma = 1.0f;

The frame number = 0;

The aspect ratio = 1.0f;

The gamma setting = 1.0f;

The name and device name are set to NULL.

The looping flag = BMM_SEQ_WRAP;
BMMExport BitmapInfo ( const MCHAR *  n )
Remarks:
Constructor. The defaults are set as above excepting the bitmap name is set.
Parameters:
MCHAR *n

The bitmap file name is set.
BMMExport BitmapInfo ( const MaxSDK::AssetManagement::AssetUser asset )
Remarks:
Constructor. The defaults are set as above excepting the bitmap asset is set.
Parameters:
AssetUser &asset

The bitmap file asset is set.
BMMExport BitmapInfo ( const BitmapInfo bi )
Remarks:
This method is available in release 3.0 and later only.

Copy Constructor.
Parameters:
const BitmapInfo &bi

The BitmapInfo to copy from.
BMMExport ~BitmapInfo ( )

Member Function Documentation

BMMExport DWORD Flags ( ) [inline]
Remarks:
Returns the flags of this BitmapInfo. See Bitmap Flags.
{ return (flags); }
BMMExport DWORD SetFlags ( DWORD  f ) [inline]
Remarks:
Sets the flags for this BitmapInfo. These are bitwise OR-ed into the current flags.
Parameters:
DWORD f

The flag bits to set. See Bitmap Flags.
Returns:
The revised flags are returned.
{ flags |=  f; return (flags); }
BMMExport DWORD ResetFlags ( DWORD  f ) [inline]
{ flags &= ~f; return (flags); }
BMMExport BOOL TestFlags ( DWORD  f ) [inline]
Remarks:
Determines if a set of flag bits are set.
Parameters:
DWORD f

The flag bits to test. See Bitmap Flags.
Returns:
TRUE if the bits are set; otherwise FALSE.
{ return (flags & f); }
BMMExport WORD Width ( ) [inline]
Remarks:
Returns the width (horizontal dimension) property of this BitmapInfo.
{ return (width); }
BMMExport WORD Height ( ) [inline]
Remarks:
Returns the height (vertical dimension) setting of this BitmapInfo.
{ return (height); }
BMMExport float Gamma ( ) [inline]
Remarks:
Returns the gamma setting property of this BitmapInfo.
{ return (gamma); }
BMMExport float Aspect ( ) [inline]
Remarks:
Returns the aspect ratio property of this BitmapInfo.
{ return (aspect);}
BMMExport int Type ( ) [inline]
Remarks:
Returns the type property of this BitmapInfo. See Bitmap Types.
{ return (type); }
BMMExport int FirstFrame ( ) [inline]
Remarks:
Returns the first frame property of this BitmapInfo. Note that for a multi-frame bitmap some sequences may start with something other than 0.
{ return (fstart); }
BMMExport int LastFrame ( ) [inline]
Remarks:
Returns the last frame property of this BitmapInfo.
{ return (fend); }
BMMExport int NumberFrames ( ) [inline]
Remarks:
Returns the total number of frames setting of this BitmapInfo.
{ return (fend - fstart + 1); }
BMMExport int CurrentFrame ( ) [inline]
Remarks:
Returns the current frame setting of this BitmapInfo.
{ return (fnumber); }
BMMExport WORD SequenceOutBound ( ) [inline]
Remarks:
When multi-frame BitmapIO loaders are reading a sequence of frames, this method is called to indicate what to do when reading beyond the end of available frames. The defaults is BMM_SEQ_WRAP.
Returns:
One of the following values:

BMM_SEQ_WRAP

Wraps around back to start point.

BMM_SEQ_ERROR

Generates an error if reading goes beyond the end.

BMM_SEQ_PINGPONG

This causes the sequence to turn around and goes the other direction, back and forth.

BMM_SEQ_HOLD

When the last frame is reached it is held and used over and over.
{ return (loopflag); }
BMMExport const MCHAR* Name ( ) const

Returns the currently set path of the image file.

Returns:
The currently set path of the image file.
Remarks:
Returns the name property of this BitmapInfo. This is the full path name. See MCHAR *Filename() for just the file name.
BMMExport MaxSDK::Util::Path GetPathEx ( ) const

Returns the currently set path of the image file.

Returns:
The currently set path of the image file.
BMMExport const MCHAR* Filename ( )
Remarks:
Returns just the file name of this BitmapInfo (not the entire path name).
BMMExport const MCHAR* Device ( ) [inline]
Remarks:
Returns the device name responsible for producing this image. For file types, this is just informative. For non-file types (devices) this is the way this image is identified. Therefore, it is important to save both name and device in order to properly identify an image.
{ return (const MCHAR *)device; }
BMMExport BOOL CompareName ( BitmapInfo bi )
Remarks:
This method will compare names taking in consideration both file names and device names. As devices don't have a file name, this method will first determine what type of image this is, and then perform a proper comparison.
Parameters:
BitmapInfo *bi

The other BitmapInfo with which to compare names.
Returns:
TRUE if the BitmapInfos have the same name and device name; otherwise FALSE.
BMMExport void CopyImageInfo ( BitmapInfo from )
Remarks:
Copies the image information of the from BitmapInfo to this bitmap. Only the name, device and image characteristics are copied. User info, such as Custom Width, etc. is not copied.

The following properties of the from BitmapInfo are copied:

from->Name(),from->Device(),from->Width(), from->Height(), from->Aspect(), from->Gamma(),from->Type(), from->Flags(), from->FirstFrame(), from->LastFrame(), from->CurrentFrame(), from->GetCustomFlags()
Parameters:
BitmapInfo *from

The bitmap whose information will be copied.
BMMExport int SetFirstFrame ( int  m ) [inline]
Remarks:
Sets the first frame property of this BitmapInfo.
Parameters:
int f

Specifies the first frame setting.
Returns:
The old (previous) first frame setting.
{ int o = fstart;   fstart   = m; return (o);}
BMMExport int SetLastFrame ( int  s ) [inline]
Remarks:
Sets the last frame property of this BitmapInfo.
Parameters:
int f

Specifies the last frame.
Returns:
The old (previous) frame setting.
{ int o = fend;     fend     = s; return (o);}
BMMExport int SetCurrentFrame ( int  v ) [inline]
Remarks:
Sets the current frame setting of this BitmapInfo.
Parameters:
int v

Specifies the current frame.
Returns:
The old (previous) current frame setting.
{ int o = fnumber;  fnumber  = v; return (o);}
BMMExport WORD SetSequenceOutBound ( WORD  c ) [inline]
Remarks:
Sets the sequence out of bounds property of this BitmapInfo. When reading a sequence of frames, this specifies what to do when reading beyond the end of available frames.
Parameters:
WORD s

One of the following values:

BMM_SEQ_WRAP

Wraps around back to start point.

BMM_SEQ_ERROR

Generates an error if reading goes beyond the end.

BMM_SEQ_PINGPONG

This causes the sequence to turn around and goes the other direction, back and forth.

BMM_SEQ_HOLD

When the last frame is reached it is held and used over and over.
Returns:
The old (previous) value that was set.
{ WORD  o = loopflag; loopflag = c; return (o);}
BMMExport WORD SetWidth ( WORD  s ) [inline]
Remarks:
Sets the width (horizontal dimension) property of this BitmapInfo.
Parameters:
WORD w

Specifies the width setting in pixels.
Returns:
The old (previously set) width of the bitmap.
{ WORD  o = width;    width    = s; return (o);}
BMMExport WORD SetHeight ( WORD  u ) [inline]
Remarks:
Sets the height (vertical dimension) property of this BitmapInfo.
Parameters:
WORD h

Specifies the height setting in pixels.
Returns:
The old (previous) height setting.
{ WORD  o = height;   height   = u; return (o);}
BMMExport float SetGamma ( float  c ) [inline]
Remarks:
Sets the gamma property of this BitmapInfo to the value passed.
Parameters:
float g

Specifies the gamma setting.
Returns:
The old (previous) gamma setting.
{ float o = gamma;    gamma    = c; return (o);}
BMMExport float SetAspect ( float  k ) [inline]
Remarks:
Set the aspect ratio property of this BitmapInfo to the specified value.
Parameters:
float a

Specifies the aspect ratio setting.
Returns:
The old (previous) aspect ratio of the bitmap.
{ float o = aspect;   aspect   = k; return (o);}
BMMExport int SetType ( int  s ) [inline]
Remarks:
Sets the type property of this BitmapInfo to the specified value.
Parameters:
int t

Specifies the type of bitmap. See Bitmap Types.
Returns:
The old (previous) type setting.
{ int   o = type;     type     = s; return (o);}
BMMExport void SetPath ( const MaxSDK::Util::Path path )

Set the path to the image file.

Parameters:
path New path for the bitmap.
BMMExport const MCHAR* SetName ( const MCHAR *  n )

Set the path to the image file.

This is a convenience method and calls SetPath under the hood.

Parameters:
n New path for the bitmap.
Remarks:
Sets the name property of this BitmapInfo. When writing n should have a fully qualified filename. When reading, it only matters if the image is not in the MAP path. Note that a "feature" of the MAP path system is that if an image with same name is found more than once (in different paths), only the first one is seen.

Note: If loading an image from a device, make sure the name is empty (bi.SetName(_M(""));). This is automatic if you use BitmapManager::SelectDeviceInput(). If you just create a BitmapInfo instance and set the device name by hand (bi.SetDevice()), this is also automatic as both name and device names are by default set to NULL (""). This is only a concern if you reuse a BitmapInfo class previously used for image files.
Parameters:
const MCHAR *n

Specifies the name of the bitmap.
Returns:
The old (previous) name that was set.
BMMExport const MaxSDK::AssetManagement::AssetUser& GetAsset ( ) const

returns this bitmap's asset

BMMExport void SetAsset ( const MaxSDK::AssetManagement::AssetUser assetUser )

sets this bitmap's asset

param[in] assetUser the new asset

BMMExport const MCHAR* SetDevice ( const MCHAR *  d )
Remarks:
This method is used to set the device name.
Parameters:
const MCHAR *d

The name to set.
Returns:
The device name that was set.
BMMExport WORD CustWidth ( ) [inline]
Remarks:
Returns the custom width setting of this BitmapInfo.
{ return (cwidth);        }
BMMExport WORD CustHeight ( ) [inline]
Remarks:
Returns the custom height setting of this BitmapInfo.
{ return (cheight);       }
BMMExport void SetCustWidth ( WORD  w ) [inline]
Remarks:
Sets the custom width setting for this BitmapInfo.
Parameters:
WORD w

The new custom width setting.
{ cwidth  = w;     }
BMMExport void SetCustHeight ( WORD  h ) [inline]
Remarks:
Sets the custom height property of this BitmapInfo.
Parameters:
WORD h

The new custom height setting.
{ cheight = h;     }
BMMExport int StartFrame ( ) [inline]
Remarks:
Returns the custom start frame property of this BitmapInfo.
{ return (start);         }
BMMExport int EndFrame ( ) [inline]
Remarks:
Returns the custom end frame setting of this BitmapInfo..
{ return (end);           }
BMMExport void SetStartFrame ( int  s ) [inline]
Remarks:
Sets the custom start frame property to the specified value.
Parameters:
int s

Specifies the start frame setting.
{ start = s;      }
BMMExport void SetEndFrame ( int  e ) [inline]
Remarks:
Sets the custom end frame property of this BitmapInfo.
Parameters:
int e

The new end frame setting.
{ end   = e;      }
BMMExport void SetCustomX ( int  x ) [inline]
Remarks:
Specifies the optional X coordinate (offset) property of this BitmapInfo. This specifies where to place the image if the image being copied from one Bitmap to another is smaller.
Parameters:
int x

Specifies the custom X offset.
{ custxpos = x;    }
BMMExport void SetCustomY ( int  y ) [inline]
Remarks:
Sets the optional Y coordinate (offset) property of this BitmapInfo. This specifies where to place the image if the image being copied from one Bitmap to another is smaller.
Parameters:
int y

Specifies the custom y offset.
{ custypos = y;    }
BMMExport int GetCustomX ( ) [inline]
Remarks:
Returns the custom x offset setting of this BitmapInfo.
{ return custxpos;        }
BMMExport int GetCustomY ( ) [inline]
Remarks:
Returns the custom Y offset setting of this BitmapInfo.
{ return custypos;        }
BMMExport void SetCustomGamma ( float  g ) [inline]
Remarks:
Sets a custom gamma setting of this BitmapInfo to the specified value.
Parameters:
float g

Specifies the custom gamma setting.
{ custgamma = g;  }
BMMExport float GetCustomGamma ( ) [inline]
Remarks:
Returns the custom gamma setting of this BitmapInfo.
{ return custgamma;       }
BMMExport float GetEffectiveGamma ( )
Remarks:
Returns the bitmap's currently used input gamma value. This is taken from either the image file's gamma, the system defaults, or the user override, according to the custom flags.
BMMExport void SetCustomStep ( int  s ) [inline]
Remarks:
Sets the custom frame increment setting of this BitmapInfo.
Parameters:
int s

Specifies the frame increment to use.
{ step = s;         }
BMMExport int GetCustomStep ( ) [inline]
Remarks:
Returns the custom frame step setting of this BitmapInfo.
{ return step;            }
BMMExport void SetPresetAlignment ( int  p ) [inline]
Remarks:
Establishes the optional alignment setting of this BitmapInfo. This specifies where to place the image if the image being copied from one Bitmap to another is smaller.
Parameters:
int p

Specifies one of the following nine values that define the position of the bitmap:

See Bitmap Alignment Positions.
{ preset_al = p;    }
BMMExport int GetPresetAlignment ( ) [inline]
Remarks:
Returns the optional alignment setting of this BitmapInfo. This indicates where to place the image if the image being copied from one Bitmap to another is smaller.
Returns:
See Bitmap Alignment Positions.
{ return preset_al;       }
BMMExport DWORD GetCustomFlags ( ) [inline]
Remarks:
Retrieves the custom flags setting of this BitmapInfo . See Bitmap Flags.
{ return (customflags);             }
BMMExport void SetCustomFlag ( DWORD  f ) [inline]
Remarks:
Sets the custom flag(s) for this BitmapInfo.
Parameters:
DWORD f

Specifies the custom flags. See Bitmap Flags.
{ customflags |=  f;        }
BMMExport void ResetCustomFlag ( DWORD  f ) [inline]
Remarks:
Clears the specified flag(s) of this BitmapInfo. See Bitmap Flags.
Parameters:
DWORD f

Specifies the flag bits to reset.
{ customflags &= ~f;        }
BMMExport BOOL TestCustomFlags ( DWORD  f ) [inline]
Remarks:
Tests the custom flags of this BitmapInfo. See Bitmap Flags.
Parameters:
DWORD f

The flag bits to test.
Returns:
Returns TRUE if the specified flags were set; otherwise FALSE.
{ return (customflags & f); }
BMMExport void* GetPiData ( ) [inline]
{ return pidata;          }
BMMExport void SetPiData ( void *  ptr ) [inline]
{ pidata = ptr; }
BMMExport DWORD GetPiDataSize ( ) [inline]
{ return pisize;          }
BMMExport void SetPiDataSize ( DWORD  s ) [inline]
{ pisize = s;     }
BMMExport void ResetPiData ( )
BMMExport BOOL AllocPiData ( DWORD  size )
BMMExport void* CreateFmtSpecBlock ( void  )
Remarks:
This method is available in release 2.0 and later only.

This method provides some access to device specific data (for instance the compression ratio in a JPEG file). This method will return a buffer containing a given device specific data (or NULL if the device referenced is unknown or doesn't have "specific data"). The buffer structure will depend on the device. For all drivers shipped with the SDK, this structure is defined in their header files (which must be included in the project for which this method is used). Internally, this method validates the driver, calls its EvaluateConfigure() method to define the buffer size, creates this buffer and, if the returned size is greater than zero, calls the driver's SaveConfigure() method in order to set default values. The developer may then change whatever they want, create and write a file using this BitmapInfo which includes the device's specific data.

There is no need to free this buffer as this is handled by the BitmapInfo destructor.

Note: The name and/or device properties must be defined before using this method.
BMMExport void Copy ( const BitmapInfo from,
BOOL  copyProxySubject 
)

Assignment function. The data members of the specified BitmapInfo are copied to this BitmapInfo, with option to also copy the proxySubject info.

BMMExport void Copy ( const BitmapInfo from )
BMMExport BitmapInfo& operator= ( const BitmapInfo from )
Remarks:
Assignment operator. The data members of the specified BitmapInfo are copied to this BitmapInfo.
Parameters:
BitmapInfo &from

The source BitmapInfo.
BMMExport IOResult Save ( ISave isave )
BMMExport IOResult Load ( ILoad iload )
BMMExport void EnumAuxFiles ( AssetEnumCallback assetEnum,
DWORD  flags 
)
BMMExport BOOL Validate ( )
Remarks:
Implemented by the System.

This method is used to check the width, height, aspect ratio, and gamma settings to make sure they are within an acceptable range of values. The comparison is as follows:

if (width < 1 ||

height < 1 ||

aspect <= 0.0 ||

gamma < MINGAMMA ||

gamma > MAXGAMMA)

return (FALSE);

else

return (TRUE);

Where:

#define MINGAMMA 0.2f

#define MAXGAMMA 5.0f
Returns:
TRUE if the BitmapInfo's settings are valid ; otherwise FALSE.
BMMExport HWND GetUpdateWindow ( ) [inline]
Remarks:
Returns the window handle to send progress or check abort messages to.
{ return hWnd; }
BMMExport void SetUpdateWindow ( HWND  hwnd ) [inline]
Remarks:
This is used internally - the system calls this method. This is how a window handle is sent down to device drivers and filters so they can send progress reports and check for cancel.
{ hWnd = hwnd; }
BMMExport DWORD GetGChannels ( )
BMMExport DWORD GetDeviceFlags ( )
BMMExport BOOL FixDeviceName ( )

Sets the appropriate device name, as derived from the filename.


BitmapInfo BitmapInfo BitmapInfo BitmapInfo BitmapInfo BitmapInfo BitmapInfo BitmapInfo BitmapInfo BitmapInfo
BitmapInfo BitmapInfo BitmapInfo BitmapInfo BitmapInfo BitmapInfo BitmapInfo BitmapInfo BitmapInfo BitmapInfo