BitmapInfo Class Reference

Information about an image file or in-memory bitmap, including settings for loading/saving, gamma, etc. More...

#include <bitmap.h>

Inheritance diagram for BitmapInfo:

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 MaxSDK::Util::Path	GetPathEx () const
	Returns the currently set path of the image file.
BMMExport void	CopyImageInfo (const BitmapInfo *from)
BMMExport void	SetPath (const MaxSDK::Util::Path &path)
	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 void *	GetPiData ()
	Returns the plugin data stored on the BitmapInfo.
BMMExport void	SetPiData (void *ptr)
	Sets the plugin data stored on the BitmapInfo.
BMMExport DWORD	GetPiDataSize () const
	Returns the size of the plugin data stored on the BitmapInfo.
BMMExport void	SetPiDataSize (DWORD s)
	Sets the reported size of the plugin data stored on the BitmapInfo.
BMMExport void	ResetPiData ()
	Resets the plugin data stored on the BitmapInfo.
BMMExport BOOL	AllocPiData (DWORD size)
	Allocates the plugin data memory and set the plugin data 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 ()
BMMExport void	Copy (const BitmapInfo *from, BOOL copyProxySubject=TRUE)
	Assignment function. The data members of the specified BitmapInfo are copied to this BitmapInfo, with option to also copy the proxySubject info.
BMMExport IOResult	Save (ISave *isave)
BMMExport IOResult	Load (ILoad *iload)
BMMExport void	EnumAuxFiles (AssetEnumCallback &assetEnum, DWORD vflags)
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.
Flag Access
BMMExport DWORD	Flags () const
BMMExport DWORD	SetFlags (DWORD f)
BMMExport DWORD	ResetFlags (DWORD f)
BMMExport BOOL	TestFlags (DWORD f) const
Frame Ranges
BMMExport int	FirstFrame () const
BMMExport int	LastFrame () const
BMMExport int	NumberFrames () const
BMMExport int	CurrentFrame () const
BMMExport WORD	SequenceOutBound () const
BMMExport int	SetFirstFrame (int m)
BMMExport int	SetLastFrame (int s)
BMMExport int	SetCurrentFrame (int v)
BMMExport WORD	SetSequenceOutBound (WORD c)
Name/Device Access
BMMExport const MCHAR *	Name () const
	Returns the currently set path of the image file.
BMMExport const MCHAR *	Filename ()
BMMExport const MCHAR *	Device () const
BMMExport BOOL	CompareName (const BitmapInfo *bi) const
BMMExport const MCHAR *	SetName (const MCHAR *n)
	Set the path to the image file.
BMMExport const MCHAR *	SetDevice (const MCHAR *d)
	Sets the device name.
Custom Input Processing
BMMExport WORD	CustWidth () const
BMMExport WORD	CustHeight () const
BMMExport void	SetCustWidth (WORD w)
BMMExport void	SetCustHeight (WORD h)
BMMExport int	StartFrame () const
BMMExport int	EndFrame () const
BMMExport void	SetStartFrame (int s)
BMMExport void	SetEndFrame (int e)
BMMExport void	SetCustomX (int x)
BMMExport void	SetCustomY (int y)
BMMExport int	GetCustomX () const
BMMExport int	GetCustomY () const
BMMExport void	SetCustomGamma (float g)
BMMExport float	GetCustomGamma () const
BMMExport float	GetEffectiveGamma () const
BMMExport void	SetCustomStep (int s)
BMMExport int	GetCustomStep () const
BMMExport void	SetPresetAlignment (int p)
BMMExport int	GetPresetAlignment () const
Custom Input Flags
BMMExport DWORD	GetCustomFlags () const
BMMExport void	SetCustomFlag (DWORD f)
BMMExport void	ResetCustomFlag (DWORD f)
BMMExport BOOL	TestCustomFlags (DWORD f) const
Operators
BMMExport BitmapInfo &	operator= (const BitmapInfo &from)

Get/Set Bitmap Properties
enum class	OutputColorConversionType : uint8_t { NoConversion = 0u , ColorSpaceConversion , DisplayViewTransform , Automatic }
BMMExport WORD	Width () const
BMMExport WORD	Height () const
BMMExport float	Gamma () const
BMMExport MSTR	ColorSpace () const
	Returns the name of the color space that's assigned to the bitmap.
BMMExport MaxSDK::ColorManagement::ColSpaceSource	ColorSpaceSource () const
	Returns color space assignment source.
BMMExport MaxSDK::ColorManagement::ColSpaceStatus	ColorSpaceStatus () const
	Returns the status of the color space assignment.
BMMExport MSTR	ColorSpaceRule () const
	Returns the input rule that's used for color space assignment.
BMMExport OutputColorConversionType	OutputColorConversion () const
	Returns the color conversion specified for an Bitmap output.
BMMExport MaxSDK::ColorManagement::ColSpaceStatus	SetOutputColorConversion (OutputColorConversionType outputConversion, const MSTR &colorSpaceOrDisplayRequested=MSTR(), const MSTR &viewTransformRequested=MSTR())
	Sets the OutputColorConversion.
BMMExport MSTR	OutputColorSpace (MaxSDK::ColorManagement::ColSpaceStatus *status=nullptr, MSTR *colorSpaceRequested=nullptr) const
	Returns the assigned output color space.
BMMExport MSTR	OutputDisplay (MaxSDK::ColorManagement::ColSpaceStatus *status=nullptr, MSTR *displayRequested=nullptr) const
	Returns the assigned output display color space.
BMMExport MSTR	OutputViewTransform (MaxSDK::ColorManagement::ColSpaceStatus *status=nullptr, MSTR *viewTransformRequested=nullptr) const
	Returns the assigned output view transform.
BMMExport float	Aspect () const
BMMExport int	Type () const
BMMExport WORD	SetWidth (WORD s)
BMMExport WORD	SetHeight (WORD u)
BMMExport float	SetGamma (float c)
BMMExport MSTR	GetRequestedColorSpace () const
	Returns the requested color space.
BMMExport MaxSDK::ColorManagement::ColSpaceStatus	SetRequestedColorSpace (const MSTR &colorSpaceName, MaxSDK::ColorManagement::ColSpaceSource requestSource)
	Sets the requested color space.
BMMExport MaxSDK::ColorManagement::ColSpaceSource	GetRequestedColorSpaceSource () const
	Returns the source of the color space request.
BMMExport MaxSDK::ColorManagement::ColSpaceStatus	ValidateColorSpace ()
	Checks and validates the assigned color space against the currently available color spaces.
BMMExport void	ResetColorSpaceInfo ()
	Clears all the color space information (including the requested and assigned color space data) to uninitialized state.
BMMExport float	SetAspect (float k)
BMMExport int	SetType (int s)

Additional Inherited Members
Static Public Member Functions inherited from MaxHeapOperators
static UtilExport void *	operator new (size_t size)
	Standard new operator used to allocate objects If there is insufficient memory, an exception will be thrown.
static UtilExport void *	operator 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 void *	operator 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 void *	operator 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 void *	operator 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 void *	operator 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 void *	operator 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 void *	operator new[] (size_t size)
	New operator used to allocate arrays of objects If there is insufficient memory, an exception will be thrown.
static UtilExport void *	operator 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 void *	operator 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 void *	operator new[] (size_t size, int block_type, const char *filename, int line)
	New operator used to allocate arrays of objects.
static UtilExport void *	operator 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 void *	operator 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 void *	operator 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 void *	operator 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 void *	aligned_malloc (size_t size, size_t alignment)
	Allocates memory on a specified alignment boundary.
static UtilExport void *	aligned_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

Information about an image file or in-memory bitmap, including settings for loading/saving, gamma, etc.

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.

In general, BitmapInfo should be used and saved for user-defined files rather than filenames, because the BitmapInfo encodes information beyond the filename, including file-format specific settings (e.g. compression on .JPG files) and so on.

The file dialog functions (such as BitmapManager::SelectFileInput() or BitmapManager::SelectFileOutput()) can be seen as "BitmapInfo editors", since they allow the user to edit its content.

Member Enumeration Documentation

OutputColorConversionType

enum class OutputColorConversionType : uint8_t

strong

Remarks

Returns the width (horizontal dimension) property of this BitmapInfo.

Enumerator
NoConversion
ColorSpaceConversion
DisplayViewTransform
Automatic

        {
            NoConversion = 0u,
            ColorSpaceConversion,
            DisplayViewTransform,
            Automatic,
        };

Constructor & Destructor Documentation

BitmapInfo() [1/4]

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;

BitmapInfo() [2/4]

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.

BitmapInfo() [3/4]

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.

BitmapInfo() [4/4]

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.

~BitmapInfo()

BMMExport ~BitmapInfo

(

)

Member Function Documentation

Flags()

BMMExport DWORD Flags ( ) const

inline

Remarks

Returns the flags of this BitmapInfo. See Bitmap Flags

{ return (flags); }

SetFlags()

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); }

ResetFlags()

BMMExport DWORD ResetFlags ( DWORD  f )

inline

Remarks

Returns the flags of this BitmapInfo. See Bitmap Flags

{ flags &= ~f; return (flags); }

TestFlags()

BMMExport BOOL TestFlags ( DWORD  f ) const

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); }

Width()

BMMExport WORD Width ( ) const

inline

Remarks

Returns the width (horizontal dimension) property of this BitmapInfo.

{ return (width); }

Height()

BMMExport WORD Height ( ) const

inline

Remarks

Returns the height (vertical dimension) setting of this BitmapInfo.

{ return (height); }

Gamma()

BMMExport float Gamma ( ) const

inline

Remarks

Returns the gamma setting property of this BitmapInfo.

{ return (gamma); }

ColorSpace()

BMMExport MSTR ColorSpace

(

)

const

Returns the name of the color space that's assigned to the bitmap.

You can not directly set the color space of a bitmap, but you can request a color space via the SetRequestedColorSpace function. The system will assign a color space based on the available and requested color spaces. Based on the color space availability the assigned color space may be different from the requested color space. If no color space is requested, system will use input rules and/or other system heuristics to assign a suitable color space.

Returns

Name of the currently assigned color space.

See also

ColorSpaceStatus, SetRequestedColorSpace, GetRequestedColorSpace, ColorSpaceSource, IModeSettings::GetFileIORule

ColorSpaceSource()

BMMExport MaxSDK::ColorManagement::ColSpaceSource ColorSpaceSource

(

)

const

Returns color space assignment source.

This value indicates how the current color space is assigned to this bitmap (user request, rules etc).

Returns

ColSpaceSource enum for the current source of the assigned color space.

See also

ColorSpace, SetRequestedColorSpace, GetRequestedColorSpaceSource, ColorSpaceStatus

ColorSpaceStatus()

BMMExport MaxSDK::ColorManagement::ColSpaceStatus ColorSpaceStatus

(

)

const

Returns the status of the color space assignment.

Note

You can ValidateColorSpace() or SetRequestedColorSpace to re-assign color space and update the status.

Returns

ColSpaceStatus enum for the current status of the assigned color space.

See also

ColorSpace, SetRequestedColorSpace, ValidateColorSpace

ColorSpaceRule()

BMMExport MSTR ColorSpaceRule

(

)

const

Returns the input rule that's used for color space assignment.

Returns

If the ColorSpaceSource is ColSpaceSource::InputRules, this will return the name of the rule that's used for assigning the color space. Otherwise it will return an empty string.

See also

ColorSpaceSource, ColSpaceSource, IModeSettings::GetFileIORule

OutputColorConversion()

BMMExport OutputColorConversionType OutputColorConversion

(

)

const

Returns the color conversion specified for an Bitmap output.

SetOutputColorConversion()

BMMExport MaxSDK::ColorManagement::ColSpaceStatus SetOutputColorConversion	(	OutputColorConversionType	outputConversion,
		const MSTR &	colorSpaceOrDisplayRequested = MSTR(),
		const MSTR &	viewTransformRequested = MSTR()
	)

Sets the OutputColorConversion.

Parameters

[in]	outputConversion	The OutputConversion to be used. If set to Automatic or NoConversion, no other parameter has to be present.
[in]	colorSpaceOrDisplayRequested	If outputConversion is set to ColorSpaceConversion, pass the requested color space in here. If outputConversion is set to DisplayViewTransform, pass the requested Display in here.
[in]	viewTransformRequested	If outputConversion is set to DisplayViewTransform, an optional view transform can be passed in here.

Returns

The status indicating if the requested color space or display view transform could be assigned.

See also

ColSpaceStatus, OutputColorConversion, OutputColorSpace, OutputDisplay, OutputViewTransform

OutputColorSpace()

BMMExport MSTR OutputColorSpace	(	MaxSDK::ColorManagement::ColSpaceStatus *	status = nullptr,
		MSTR *	colorSpaceRequested = nullptr
	)		const

Returns the assigned output color space.

If OutputColorConversion is set to ColorSpaceConversion, this function returns the assigned output color space, into that the image is converted during saving. Note that this can be different than what was requested, as not all color spaces may be available in the currently used OCIO config.

Parameters

[out]	status	If this is passed in by the caller, it will receive the status of the output color space.
[out]	colorSpaceRequested	If present, this will receive the output color space that was originally requested.

Returns

The output color spaces that is being used to save this bitmap, if the ColorConversion is set to ColorSpaceConversion.

See also

OutputColorConversion

OutputDisplay()

BMMExport MSTR OutputDisplay	(	MaxSDK::ColorManagement::ColSpaceStatus *	status = nullptr,
		MSTR *	displayRequested = nullptr
	)		const

Returns the assigned output display color space.

If OutputColorConversion is set to DisplayViewTransform, this function returns the assigned display color space, into that the image is converted during saving, along with some optional view transform. Note that this can be different than what was requested, as not all display color spaces may be available in the currently used OCIO config.

Parameters

[out]	status	If this is passed in by the caller, it will receive the status of the output display color space.
[out]	displayRequested	If present, this will receive the output display that was originally requested.

Returns

The output display used to save this bitmap along with some optional view transform, if ColorConversion is set to DisplayViewTransform.

See also

OutputColorConversion, OutputViewTransform

OutputViewTransform()

BMMExport MSTR OutputViewTransform	(	MaxSDK::ColorManagement::ColSpaceStatus *	status = nullptr,
		MSTR *	viewTransformRequested = nullptr
	)		const

Returns the assigned output view transform.

If OutputColorConversion is set to DisplayViewTransform, this function returns the assigned view transform, that is applied to the image during saving along with the conversion into the assigned display color space. Note that this can be different than what was requested, as not all view transforms may be available for the assigned display in the currently used OCIO config.

Parameters

[out]	status	If this is passed in by the caller, it will receive the status of the output view transform.
[out]	viewTransformRequested	If present, this will receive the output view transform that was originally requested.

Returns

The output view transform applied to the image during saving along with the conversion into the assigned display color space, if ColorConversion is set to DisplayViewTransform.

See also

OutputColorConversion, OutputViewTransform

Aspect()

BMMExport float Aspect ( ) const

inline

Remarks

Returns the aspect ratio property of this BitmapInfo.

{ return (aspect);}

Type()

BMMExport int Type ( ) const

inline

Remarks

Returns the type property of this BitmapInfo. See Bitmap Types

{ return (type); }

SetWidth()

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);}

SetHeight()

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);}

SetGamma()

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);}

GetRequestedColorSpace()

BMMExport MSTR GetRequestedColorSpace

(

)

const

Returns the requested color space.

Color space of a bitmap can not be directly set but can be requested either by the user or by the input rules. The system will assign a color space based on this request and the currently available color space. This function will return the requested color space. See ColorSpace for the currently assigned space.

Returns

Name of the requested color space.

See also

ColorSpace, ColorSpaceStatus, SetRequestedColorSpace, ColorSpaceSource, GetRequestedColorSpaceSource

SetRequestedColorSpace()

BMMExport MaxSDK::ColorManagement::ColSpaceStatus SetRequestedColorSpace	(	const MSTR &	colorSpaceName,
		MaxSDK::ColorManagement::ColSpaceSource	requestSource
	)

Sets the requested color space.

The actual color space assigned may differ if the requested color space is not available. This function internally calls ValidateColorSpace to assign a color space based on the availability of the requested color space. Actually assigned color space may differ from the requested color space.

Parameters

colorSpaceName	Name of the requested color space that's being requested. This is either based on the user selection or input rules. See IModSettings::GetNumFileIOColorSpaces for list of currently available spaces.
requestSource	one of the ColSpaceSource enum values indicating why this color space is being requested.

Returns

Status of the current color space assignment.

GetRequestedColorSpaceSource()

BMMExport MaxSDK::ColorManagement::ColSpaceSource GetRequestedColorSpaceSource

(

)

const

Returns the source of the color space request.

Returns

Source of the requested color space, this may be the parameter passed to the SetRequestedColorSpace if the color space was requested explicitly or an internally assinged value if no request is made yet.

ValidateColorSpace()

BMMExport MaxSDK::ColorManagement::ColSpaceStatus ValidateColorSpace

(

)

Checks and validates the assigned color space against the currently available color spaces.

If the assigned color space is missing or not available in the current setup, then it assigns a valid color space based on the requested color space, file input rules and other settings and/or heuristics.

Returns

Status of the assigned color space after the validation an potential assignment.

See also

ColorSpace, ColorSpaceStatus, GetRequestedColorSpace, ColorSpaceSource, SetRequestedColorSpace

ResetColorSpaceInfo()

BMMExport void ResetColorSpaceInfo

(

)

Clears all the color space information (including the requested and assigned color space data) to uninitialized state.

After this function is called, the bitmap won't have any color space assigned to it before ValidateColorSpace or SetRequestedColorSpace is called. Various functions of the Bitmap class or other internal functions working on bitmaps may validate and auto assign a color space if the color space is in unassigned state.

See also

ColorSpace, ColorSpaceStatus, GetRequestedColorSpace, ColorSpaceSource, SetRequestedColorSpace, ValidateColorSpace

SetAspect()

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);}

SetType()

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);}

FirstFrame()

BMMExport int FirstFrame ( ) const

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); }

LastFrame()

BMMExport int LastFrame ( ) const

inline

Remarks

Returns the last frame property of this BitmapInfo.

{ return (fend); }

NumberFrames()

BMMExport int NumberFrames ( ) const

inline

Remarks

Returns the total number of frames setting of this BitmapInfo.

{ return (fend - fstart + 1); }

CurrentFrame()

BMMExport int CurrentFrame ( ) const

inline

Remarks

Returns the current frame setting of this BitmapInfo.

{ return (fnumber); }

SequenceOutBound()

BMMExport WORD SequenceOutBound ( ) const

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); }

SetFirstFrame()

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);}

SetLastFrame()

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);}

SetCurrentFrame()

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);}

SetSequenceOutBound()

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);}

Name()

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.

Filename()

BMMExport const MCHAR * Filename

(

)

Remarks

Returns just the file name of this BitmapInfo (not the entire path name).

Device()

BMMExport const MCHAR * Device ( ) const

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 m_device.data(); }

CompareName()

BMMExport BOOL CompareName

(

const BitmapInfo *

bi

)

const

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.

SetName()

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.

SetDevice()

BMMExport const MCHAR * SetDevice

(

const MCHAR *

d

)

Sets the device name.

Remarks

This copies the supplied string into the member variable device. The string corresponds with the long description of a BitmapIO plugin: BitmapIO::LongDesc(). However it is not necessary to call this as the system will do it automatically when Bitmap::OpenOutput is called. Or as alternative, it can properly be set in a localized environment by calling BitmapInfo::FixDeviceName().

Parameters

d	- The name to set.

Returns

The device name that was set.

GetPathEx()

BMMExport MaxSDK::Util::Path GetPathEx

(

)

const

Returns the currently set path of the image file.

Returns

The currently set path of the image file.

CopyImageInfo()

BMMExport void CopyImageInfo

(

const BitmapInfo *

from

)

Remarks

Copies the image information of the from BitmapInfo to this bitmap. Only the name, device, image characteristics and color management related data 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(), from->GetColorSpace(), from->ColorSpaceSource(), from->ColorSpaceStatus(), from->ColorSpaceRule(), from->OutputColorConversion(), from->OutputColorSpace(), from->OutputDisplay(), from->OutputViewTransform()

Parameters

from	The bitmap whose information will be copied.

SetPath()

BMMExport void SetPath

(

const MaxSDK::Util::Path &

path

)

Set the path to the image file.

Parameters

path	New path for the bitmap.

GetAsset()

BMMExport const MaxSDK::AssetManagement::AssetUser & GetAsset

(

)

const

returns this bitmap's asset

SetAsset()

BMMExport void SetAsset

(

const MaxSDK::AssetManagement::AssetUser &

assetUser

)

sets this bitmap's asset

param[in] assetUser the new asset

CustWidth()

BMMExport WORD CustWidth ( ) const

inline

Remarks

Returns the custom width setting of this BitmapInfo.

{ return (cwidth); };

CustHeight()

BMMExport WORD CustHeight ( ) const

inline

Remarks

Returns the custom height setting of this BitmapInfo.

{ return (cheight); }

SetCustWidth()

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;     }

SetCustHeight()

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;     }

StartFrame()

BMMExport int StartFrame ( ) const

inline

Remarks

Returns the custom start frame property of this BitmapInfo.

{ return (start); }

EndFrame()

BMMExport int EndFrame ( ) const

inline

Remarks

Returns the custom end frame setting of this BitmapInfo.

{ return (end); }

SetStartFrame()

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;      }

SetEndFrame()

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;      }

SetCustomX()

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;    }

SetCustomY()

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;    }

GetCustomX()

BMMExport int GetCustomX ( ) const

inline

Remarks

Returns the custom x offset setting of this BitmapInfo.

{ return custxpos; }

GetCustomY()

BMMExport int GetCustomY ( ) const

inline

Remarks

Returns the custom Y offset setting of this BitmapInfo.

{ return custypos; }

SetCustomGamma()

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;  }

GetCustomGamma()

BMMExport float GetCustomGamma ( ) const

inline

Remarks

Returns the custom gamma setting of this BitmapInfo.

{ return custgamma; }

GetEffectiveGamma()

BMMExport float GetEffectiveGamma

(

)

const

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.

SetCustomStep()

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;         }

GetCustomStep()

BMMExport int GetCustomStep ( ) const

inline

Remarks

Returns the custom frame step setting of this BitmapInfo.

{ return step; }

SetPresetAlignment()

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;    }

GetPresetAlignment()

BMMExport int GetPresetAlignment ( ) const

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; }

GetCustomFlags()

BMMExport DWORD GetCustomFlags ( ) const

inline

Remarks

Retrieves the custom flags setting of this BitmapInfo . See Custom Bitmap Flags

{ return (customflags); }

SetCustomFlag()

BMMExport void SetCustomFlag ( DWORD  f )

inline

Remarks

Sets the custom flag(s) for this BitmapInfo.

Parameters:

DWORD f

Specifies the custom flags. See Custom Bitmap Flags

{ customflags |=  f;        }

ResetCustomFlag()

BMMExport void ResetCustomFlag ( DWORD  f )

inline

Remarks

Clears the specified flag(s) of this BitmapInfo. See Custom Bitmap Flags

Parameters:

DWORD f

Specifies the flag bits to reset.

{ customflags &= ~f;        }

TestCustomFlags()

BMMExport BOOL TestCustomFlags ( DWORD  f ) const

inline

Remarks

Tests the custom flags of this BitmapInfo. See Custom Bitmap Flags

Parameters:

DWORD f

The flag bits to test.

Returns

Returns TRUE if the specified flags were set; otherwise FALSE.

{ return (customflags & f); }

GetPiData()

BMMExport void * GetPiData ( )

inline

Returns the plugin data stored on the BitmapInfo.

The plugin data is set by BitmapIO class responsible for producing this image. The BitmapIO class stores its image specific data in the plugin data. For example, the avi BitmapIO class stores the compressor name, quality, and keyframe in the plugin data. The BitmapInfo owns the memory associated with the plugin data and will free the memory when deleted.

Returns

Pointer to the plugin data.

{ return pidata;          }

SetPiData()

BMMExport void SetPiData ( void *  ptr )

inline

Sets the plugin data stored on the BitmapInfo.

This method is not normally called, rather a BitmapIO instance will call AllocPiData(), which will allocate the plugin data memory and set the plugin data size. The BitmapIO will then acquire the pointer to the plugin data memory via GetPiData()

Parameters

[in]

ptr

Pointer to the plugin data.

{ pidata = ptr; }

GetPiDataSize()

BMMExport DWORD GetPiDataSize ( ) const

inline

Returns the size of the plugin data stored on the BitmapInfo.

Returns

Size of the plugin data.

{ return pisize; }

SetPiDataSize()

BMMExport void SetPiDataSize ( DWORD  s )

inline

Sets the reported size of the plugin data stored on the BitmapInfo.

This method is not normally called, rather a BitmapIO instance will call AllocPiData(), which will allocate the plugin data memory and set the plugin data size. The BitmapIO will then acquire the pointer to the plugin data memory via GetPiData()

Parameters

[in]

s

Reported size of the plugin data.

{ pisize = s;     }

ResetPiData()

BMMExport void ResetPiData

(

)

Resets the plugin data stored on the BitmapInfo.

Frees existing plugin data memory and sets plugin data size to zero.

AllocPiData()

BMMExport BOOL AllocPiData

(

DWORD

size

)

Allocates the plugin data memory and set the plugin data size.

Acquire the pointer to the plugin data memory via GetPiData()

Parameters

[in]

size

Requested size of the plugin data.

CreateFmtSpecBlock()

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

Copy()

BMMExport void Copy	(	const BitmapInfo *	from,
		BOOL	copyProxySubject = TRUE
	)

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

operator=()

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.

Save()

BMMExport IOResult Save

(

ISave *

isave

)

Load()

BMMExport IOResult Load

(

ILoad *

iload

)

EnumAuxFiles()

BMMExport void EnumAuxFiles	(	AssetEnumCallback &	assetEnum,
		DWORD	vflags
	)

Validate()

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.

GetUpdateWindow()

BMMExport HWND GetUpdateWindow ( )

inline

Remarks

Returns the window handle to send progress or check abort messages to.

{ return hWnd; }

SetUpdateWindow()

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; }

GetGChannels()

BMMExport DWORD GetGChannels

(

)

GetDeviceFlags()

BMMExport DWORD GetDeviceFlags

(

)

FixDeviceName()

BMMExport BOOL FixDeviceName

(

)

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