Class BitmapInfo
See Also: Class Bitmap, Working with Bitmaps, List of Bitmap Error Codes.
class BitmapInfo
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:
The following hyperlinks jump to the start of groups of methods within the class:
Get/Set Bitmap Properties (Type, Width, Height, etc.)
Get/Set Custom Bitmap Properties
Methods:
Prototype:
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;
Prototype:
BitmapInfo(TCHAR *n);
Remarks:
Constructor. The defaults are set as above excepting the bitmap name is set.
Parameters:
TCHAR *n
The bitmap file name is set.
Prototype:
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.
Prototype:
DWORD Flags()
Remarks:
Returns the flags of this BitmapInfo. See Bitmap Flags.
Prototype:
DWORD SetFlags(DWORD f)
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.
Return Value:
The revised flags are returned.
Prototype:
BOOL TestFlags(DWORD f)
Remarks:
Determines if a set of flag bits are set.
Parameters:
DWORD f
The flag bits to test. See Bitmap Flags.
Return Value:
TRUE if the bits are set; otherwise FALSE.
Prototype:
int Type()
Remarks:
Returns the type property of this BitmapInfo. See Bitmap Types.
Prototype:
int SetType(int t)
Remarks:
Sets the type property of this BitmapInfo to the specified value.
Parameters:
int t
Specifies the type of bitmap. See Bitmap Types.
Return Value:
The old (previous) type setting.
Prototype:
WORD Width()
Remarks:
Returns the width (horizontal dimension) property of this BitmapInfo.
Prototype:
WORD SetWidth(WORD w)
Remarks:
Sets the width (horizontal dimension) property of this BitmapInfo.
Parameters:
WORD w
Specifies the width setting in pixels.
Return Value:
The old (previously set) width of the bitmap.
Prototype:
WORD Height()
Remarks:
Returns the height (vertical dimension) setting of this BitmapInfo.
Prototype:
WORD SetHeight(WORD h)
Remarks:
Sets the height (vertical dimension) property of this BitmapInfo.
Parameters:
WORD h
Specifies the height setting in pixels.
Return Value:
The old (previous) height setting.
Prototype:
float Gamma()
Remarks:
Returns the gamma setting property of this BitmapInfo.
Prototype:
float SetGamma(float g)
Remarks:
Sets the gamma property of this BitmapInfo to the value passed.
Parameters:
float g
Specifies the gamma setting.
Return Value:
The old (previous) gamma setting.
Prototype:
float Aspect()
Remarks:
Returns the aspect ratio property of this BitmapInfo.
Prototype:
float SetAspect(float a)
Remarks:
Set the aspect ratio property of this BitmapInfo to the specified value.
Parameters:
float a
Specifies the aspect ratio setting.
Return Value:
The old (previous) aspect ratio of the bitmap.
Frame Ranges
Prototype:
int FirstFrame()
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.
Prototype:
int SetFirstFrame(int f)
Remarks:
Sets the first frame property of this BitmapInfo.
Parameters:
int f
Specifies the first frame setting.
Return Value:
The old (previous) first frame setting.
Prototype:
int LastFrame()
Remarks:
Returns the last frame property of this BitmapInfo.
Prototype:
int SetLastFrame(int f)
Remarks:
Sets the last frame property of this BitmapInfo.
Parameters:
int f
Specifies the last frame.
Return Value:
The old (previous) frame setting.
Prototype:
int NumberFrames()
Remarks:
Returns the total number of frames setting of this BitmapInfo.
Prototype:
int CurrentFrame()
Remarks:
Returns the current frame setting of this BitmapInfo.
Prototype:
int SetCurrentFrame(int v)
Remarks:
Sets the current frame setting of this BitmapInfo.
Parameters:
int v
Specifies the current frame.
Return Value:
The old (previous) current frame setting.
Prototype:
WORD SequenceOutBound()
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.
Return Value:
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.
Prototype:
WORD SetSequenceOutBound(WORD s)
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.
Return Value:
The old (previous) value that was set.
Prototype:
const TCHAR *Name()
Remarks:
Returns the name property of this BitmapInfo. This is the full path name. See TCHAR *Filename() for just the file name.
Prototype:
const TCHAR *SetName(const TCHAR *n);
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(_T(""));). 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 TCHAR *n
Specifies the name of the bitmap.
Return Value:
The old (previous) name that was set.
Prototype:
const TCHAR *Filename()
Remarks:
Returns just the file name of this BitmapInfo (not the entire path name).
Prototype:
const TCHAR *Device()
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.
Prototype:
const TCHAR *SetDevice(const TCHAR *d);
Remarks:
This method is used to set the device name.
Parameters:
const TCHAR *d
The name to set.
Return Value:
The device name that was set.
Prototype:
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.
Return Value:
TRUE if the BitmapInfos have the same name and device name; otherwise FALSE.
Prototype:
WORD CustWidth()
Remarks:
Returns the custom width setting of this BitmapInfo.
Prototype:
void SetCustWidth(WORD w)
Remarks:
Sets the custom width setting for this BitmapInfo.
Parameters:
WORD w
The new custom width setting.
Prototype:
WORD CustHeight()
Remarks:
Returns the custom height setting of this BitmapInfo.
Prototype:
void SetCustHeight(WORD h)
Remarks:
Sets the custom height property of this BitmapInfo.
Parameters:
WORD h
The new custom height setting.
Prototype:
int StartFrame()
Remarks:
Returns the custom start frame property of this BitmapInfo.
Prototype:
void SetStartFrame(int s)
Remarks:
Sets the custom start frame property to the specified value.
Parameters:
int s
Specifies the start frame setting.
Prototype:
int EndFrame()
Remarks:
Returns the custom end frame setting of this BitmapInfo..
Prototype:
void SetEndFrame(int e)
Remarks:
Sets the custom end frame property of this BitmapInfo.
Parameters:
int e
The new end frame setting.
Prototype:
WORD GetCustomX()
Remarks:
Returns the custom x offset setting of this BitmapInfo.
Prototype:
void SetCustomX(int x)
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.
Prototype:
WORD GetCustomY()
Remarks:
Returns the custom Y offset setting of this BitmapInfo.
Prototype:
void SetCustomY(int y)
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.
Prototype:
float GetCustomGamma()
Remarks:
Returns the custom gamma setting of this BitmapInfo.
Prototype:
void SetCustomGamma(float g)
Remarks:
Sets a custom gamma setting of this BitmapInfo to the specified value.
Parameters:
float g
Specifies the custom gamma setting.
Prototype:
int GetCustomStep()
Remarks:
Returns the custom frame step setting of this BitmapInfo.
Prototype:
void SetCustomStep(int s)
Remarks:
Sets the custom frame increment setting of this BitmapInfo.
Parameters:
int s
Specifies the frame increment to use.
Prototype:
int GetPresetAlignment()
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.
Return Value:
See List of Bitmap Alignment Positions.
Prototype:
void SetPresetAlignment(int p)
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 List of Bitmap Alignment Positions.
Prototype:
DWORD GetCustomFlags()
Remarks:
Retrieves the custom flags setting of this BitmapInfo . See List of Custom Bitmap Flags.
Prototype:
void SetCustomFlag(DWORD f)
Remarks:
Sets the custom flag(s) for this BitmapInfo.
Parameters:
DWORD f
Specifies the custom flags. See List of Custom Bitmap Flags.
Prototype:
void ResetCustomFlag(DWORD f)
Remarks:
Clears the specified flag(s) of this BitmapInfo. See List of Custom Bitmap Flags.
Parameters:
DWORD f
Specifies the flag bits to reset.
Prototype:
BOOL TestCustomFlags(DWORD f)
Remarks:
Tests the custom flags of this BitmapInfo. See List of Custom Bitmap Flags.
Parameters:
DWORD f
The flag bits to test.
Return Value:
Returns TRUE if the specified flags were set; otherwise FALSE.
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.
Prototype:
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
Return Value:
TRUE if the BitmapInfo's settings are valid ; otherwise FALSE.
Prototype:
HWND GetUpdateWindow()
Remarks:
Returns the window handle to send progress or check abort messages to.
Prototype:
void SetUpdateWindow(HWND hwnd)
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.
Prototype:
void *CreateFmtSpecBlock();
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.
Prototype:
virtual BitmapInfo &operator= (BitmapInfo &from);
Remarks:
Assignment operator. The data members of the specified BitmapInfo are copied to this BitmapInfo.
Parameters:
BitmapInfo &from
The source BitmapInfo.