IMG_Format Class Reference

#include <IMG_Format.h>

Inheritance diagram for IMG_Format:

Public Types
enum	AccessType { READ_ACCESS, WRITE_ACCESS }

Public Member Functions
	IMG_Format ()
	IMG_Format (bool addtolist)
virtual	~IMG_Format ()
IMG_File *	allocValidFile () const
virtual const char *	getFormatDescription () const
virtual bool	isPassThrough () const
virtual const char *	getDefaultExtension () const
virtual const char *	getFormatLocation () const
	Describes how the format was loaded (i.e. DSO or internal formats) More...
virtual int	checkDevice (const char *) const
virtual IMG_ImageType	getSupportedImageTypes () const
virtual IMG_DataType	getSupportedTypes () const =0
	Returns a bitfield of data types supported by this format. More...
virtual IMG_ColorModel	getSupportedColorModels () const =0
virtual void	getMaxResolution (unsigned &x, unsigned &y) const =0
virtual int	isTopFirst () const
virtual int	isLeftFirst () const
virtual const IMG_Format *	resolvePriority (const IMG_Format *format) const
virtual bool	formatStoresColorSpace () const
	Return true if the image format can store the colorspace. More...
virtual const char *	getFormatName () const =0
virtual const char *	getFormatLabel () const
virtual const char *	getMetadataKey () const
virtual int	checkExtension (const char *filename) const =0
virtual int	checkMagic (unsigned int) const
virtual int	checkMagicSeekable (UT_IStream &is) const
virtual int	isReadRandomAccess () const
virtual int	isWriteRandomAccess () const
virtual PXL_ColorSpace	formatColorSpace () const
virtual fpreal	formatColorSpaceGamma () const
fpreal	adjustGammaForFormat (PXL_ColorSpace src_color_space, fpreal src_color_space_gamma, bool src_data_is_8bit, bool *dest_data_is_8bit=NULL) const
fpreal	adjustGammaForFormat (PXL_ColorSpace *src_color_space, fpreal src_color_space_gamma, bool src_data_is_8bit, bool *dest_data_is_8bit) const

Static Public Member Functions
static const IMG_Format *	findFormatByName (const char *format_name)
static const IMG_Format *	findFormatByLabel (const char *format_label)
static const IMG_Format *	findFormatSeekable (UT_IStream &is)
static const IMG_Format *	findFormatNonSeekable (UT_IStream &is)
static const IMG_Format *	findFormatByExtension (const char *filename)
static const IMG_Format *	getStdoutFormat ()
static const IMG_Format *	metadataPrefix (const char *key)
static void	setGlobalOption (const char *name, const char *value)
	Set an option globally for all formats. Use with extreme care. More...
static void	getGlobalOption (const char *name, UT_String &value)
	Read the value of a global option. May return a NULL string. More...
static bool	setFormatOptionDefault (const char *format_name, const char *format_option, const char *defvalue)
static bool	getFormatOptionDefault (const char *format_name, const char *format_option, UT_String &defvalue)
static int	matchExtension (const char *filename, const char *ext)
	Matches a filename against a single extension. More...
static int	matchExtensions (const char *filename, const char *ext[])
static int	getNFormats ()
static const IMG_Format *	getFormat (int idx)
	Access to the list of currently installed image formats. More...
static const IMG_Format *	findFormatReadable (const char *filename, const IMG_Stat *stat=0)
static const IMG_Format *	findFormatWritable (const char *filename, const IMG_Stat *stat=0)
static void	findFormatReadable (UT_Array< const IMG_Format * > &formats, const char *filename, const IMG_Stat *stat=nullptr, const UT_Array< const IMG_Format * > *image_formats=nullptr)
static void	findFormatWritable (UT_Array< const IMG_Format * > &formats, const char *filename, const IMG_Stat *stat=nullptr, const UT_Array< const IMG_Format * > *image_formats=nullptr)

Protected Member Functions
virtual IMG_File *	createFile () const =0
virtual int	isFormatOk (const IMG_Stat &stat) const
void	removeFormatFromList ()
const IMG_Metadata *	getGlobalTags ()

Static Protected Member Functions
static const IMG_Format *	findFormat (const char *filename, const IMG_Stat *stat, AccessType access)
static void	findFormat (UT_Array< const IMG_Format * > &list, const char *filename, const IMG_Stat *stat, AccessType access, const UT_Array< const IMG_Format * > *image_formats=nullptr)
virtual bool	isReadable () const
virtual bool	isWritable () const
virtual bool	isDataWindowSupported () const
	does this format support a data window or sub-area. More...
virtual bool	isDataWindowCropOnly () const
virtual bool	isDataWindowStreakSupported () const
virtual bool	isDeepRasterSupported () const
virtual IMG_DeepRasterColor	getDeepRasterRGBASupport () const
virtual bool	isDataInterleaved () const
virtual bool	canPlaneTypesDiffer () const
virtual const IMG_FileOptionList *	getOptions () const
virtual const IMG_MetadataOptions &	formatMetadata () const
	Returns list of well known metadata for the format. More...
static UT_StringHolder	artistDefault ()
static UT_StringHolder	hostnameDefault ()

Detailed Description

Description of a specific image file format, describing the characteristics and capabilities of a specific image file format. It can be used to query the capabilities of that format (resolution limits, data formats supported, image orientation, etc). Image file-specific data (such as resolution of a given file) can be found in IMG_Stat.
When writing a new data format, many of the virtuals will need to be overridden to properly describe its capabilities.

Examples:

IMG/IMG_Sample.C.

Definition at line 45 of file IMG_Format.h.

Member Enumeration Documentation

enum IMG_Format::AccessType

Enumerator
READ_ACCESS
WRITE_ACCESS

Definition at line 59 of file IMG_Format.h.

Constructor & Destructor Documentation

IMG_Format::IMG_Format

(

)

IMG_Format::IMG_Format ( bool  addtolist )

explicit

This is a version of the constructor that lets you avoid adding oneself to the list. This is used by the pass throug filter and must be used if you are in multithreaded code as the underlying list is not locked.

virtual IMG_Format::~IMG_Format ( )

virtual

Member Function Documentation

fpreal IMG_Format::adjustGammaForFormat ( PXL_ColorSpace  src_color_space, fpreal  src_color_space_gamma, bool  src_data_is_8bit, bool *  dest_data_is_8bit = NULL  ) const

inline

Returns a gamma correction factor when converting from a given color space to this image format's space. 'src_data_is_8bit' indicates whether data is fixed 8b, in which case it will often be converted to 2.2 gamma. If the dest_data_is_8bit is provided, it will use that flag for the destination 8bit type instead of the src_data_is_8bit.

Definition at line 302 of file IMG_Format.h.

fpreal IMG_Format::adjustGammaForFormat	(	PXL_ColorSpace *	src_color_space,
		fpreal	src_color_space_gamma,
		bool	src_data_is_8bit,
		bool *	dest_data_is_8bit
	)		const

Returns a gamma correction factor when converting from a given color space to this image format's space. 'src_data_is_8bit' indicates whether data is fixed 8b, in which case it will often be converted to 2.2 gamma. If the dest_data_is_8bit is provided, it will use that flag for the destination 8bit type instead of the src_data_is_8bit.

IMG_File* IMG_Format::allocValidFile

(

)

const

static UT_StringHolder IMG_Format::artistDefault ( )

static

Convenience methods to get common items for metadata

virtual bool IMG_Format::canPlaneTypesDiffer ( ) const

virtual

if true, planes can have different data formats & components. Otherwise, all planes must have the same data type and number of components.

Reimplemented in IMG_FormatPassThru.

virtual int IMG_Format::checkDevice ( const char *  ) const

virtual

The device method gives a higher priority to device checks. By default, this method returns 0 (no match). This is used to allow things like a60:3.pic (which uses the abekas device).

Reimplemented in IMG_FormatPassThru.

virtual int IMG_Format::checkExtension ( const char *  filename ) const

pure virtual

Methods to determine if this is one of our recognized files. The extension is the first try. If there are multiple matches, then we resort to the magic number (when reading)

Implemented in HDK_Sample::IMG_SampleFormat, and IMG_FormatPassThru.

virtual int IMG_Format::checkMagic ( unsigned  int ) const

virtual

If possible, this magic numver checker will be called. This is used if the file is "seekable" (i.e. that we can rewind after checking)

Reimplemented in HDK_Sample::IMG_SampleFormat, and IMG_FormatPassThru.

virtual int IMG_Format::checkMagicSeekable ( UT_IStream &  is ) const

virtual

If possible, this second magic number checker will be called. This is used if the file is "seekable" (i.e. that we can rewind after checking)

Reimplemented in IMG_FormatPassThru.

virtual IMG_File* IMG_Format::createFile ( ) const

protectedpure virtual

Implemented in IMG_FormatPassThru, and HDK_Sample::IMG_SampleFormat.

static const IMG_Format* IMG_Format::findFormat ( const char *  filename, const IMG_Stat *  stat, AccessType  access  )

staticprotected

static void IMG_Format::findFormat ( UT_Array< const IMG_Format * > &  list, const char *  filename, const IMG_Stat *  stat, AccessType  access, const UT_Array< const IMG_Format * > *  image_formats = nullptr  )

staticprotected

static const IMG_Format* IMG_Format::findFormatByExtension ( const char *  filename )

static

static const IMG_Format* IMG_Format::findFormatByLabel ( const char *  format_label )

static

static const IMG_Format* IMG_Format::findFormatByName ( const char *  format_name )

static

static const IMG_Format* IMG_Format::findFormatNonSeekable ( UT_IStream &  is )

static

static const IMG_Format* IMG_Format::findFormatReadable ( const char *  filename, const IMG_Stat *  stat = 0  )

static

Find a format given a filename and a stat - only extension matching. Will only return formats that can read files (isReadable()).

static void IMG_Format::findFormatReadable ( UT_Array< const IMG_Format * > &  formats, const char *  filename, const IMG_Stat *  stat = nullptr, const UT_Array< const IMG_Format * > *  image_formats = nullptr  )

static

Find a format given a filename and a stat - only extension matching. Will only return formats that can read files (isReadable()).

static const IMG_Format* IMG_Format::findFormatSeekable ( UT_IStream &  is )

static

static const IMG_Format* IMG_Format::findFormatWritable ( const char *  filename, const IMG_Stat *  stat = 0  )

static

Find a format given a filename and a stat - only extension matching. Will only return formats that can write files (isWritable()).

static void IMG_Format::findFormatWritable ( UT_Array< const IMG_Format * > &  formats, const char *  filename, const IMG_Stat *  stat = nullptr, const UT_Array< const IMG_Format * > *  image_formats = nullptr  )

static

Find a format given a filename and a stat - only extension matching. Will only return formats that can read files (isReadable()).

virtual PXL_ColorSpace IMG_Format::formatColorSpace ( ) const

virtual

Some image formats have fixed color spaces, like JPEG (sRGB). The default is PXL_CS_UNKNOWN. For formats that can have colorspaces per plane, return PXL_CS_UNKNOWN and query the colorspace from IMG_Plane. formatColorSpaceGamma() is ignored unless the color space is PXL_CS_CUSTOM_GAMMA.

Reimplemented in IMG_FormatPassThru.

virtual fpreal IMG_Format::formatColorSpaceGamma ( ) const

virtual

Some image formats have fixed color spaces, like JPEG (sRGB). The default is PXL_CS_UNKNOWN. For formats that can have colorspaces per plane, return PXL_CS_UNKNOWN and query the colorspace from IMG_Plane. formatColorSpaceGamma() is ignored unless the color space is PXL_CS_CUSTOM_GAMMA.

Reimplemented in IMG_FormatPassThru.

virtual const IMG_MetadataOptions& IMG_Format::formatMetadata ( ) const

virtual

Returns list of well known metadata for the format.

Reimplemented in IMG_FormatPassThru.

virtual bool IMG_Format::formatStoresColorSpace ( ) const

virtual

Return true if the image format can store the colorspace.

Reimplemented in IMG_FormatPassThru.

virtual IMG_DeepRasterColor IMG_Format::getDeepRasterRGBASupport ( ) const

virtual

does this deep raster allow RGBA in one plane (true) or split into 2 planes (RGB, A). (default false)

virtual const char* IMG_Format::getDefaultExtension ( ) const

virtual

The default extension is used to determine whether the format should appear in the device/format menus. It should not contain the '.' (i.e. "tif" not ".tif")

Reimplemented in HDK_Sample::IMG_SampleFormat, and IMG_FormatPassThru.

static const IMG_Format* IMG_Format::getFormat ( int  idx )

static

Access to the list of currently installed image formats.

virtual const char* IMG_Format::getFormatDescription ( ) const

virtual

This can be optionally overridden to return a short description of the format. By default, no description is given.

Reimplemented in HDK_Sample::IMG_SampleFormat, and IMG_FormatPassThru.

virtual const char* IMG_Format::getFormatLabel ( ) const

virtual

If getFormatLabel() is not overridden, the label will be the same as the name.

Reimplemented in HDK_Sample::IMG_SampleFormat, and IMG_FormatPassThru.

virtual const char* IMG_Format::getFormatLocation ( ) const

inlinevirtual

Describes how the format was loaded (i.e. DSO or internal formats)

Reimplemented in IMG_FormatPassThru.

Definition at line 134 of file IMG_Format.h.

virtual const char* IMG_Format::getFormatName ( ) const

pure virtual

All formats must have a unique name (like "JPEG").

Implemented in HDK_Sample::IMG_SampleFormat, and IMG_FormatPassThru.

static bool IMG_Format::getFormatOptionDefault ( const char *  format_name, const char *  format_option, UT_String &  defvalue  )

static

Returns the value of a format-specific option. Returns false if the format or option does not exist.

static void IMG_Format::getGlobalOption ( const char *  name, UT_String &  value  )

static

Read the value of a global option. May return a NULL string.

const IMG_Metadata* IMG_Format::getGlobalTags ( )

protected

virtual void IMG_Format::getMaxResolution ( unsigned &  x, unsigned &  y  ) const

pure virtual

Maximum allowable resolution for the file. If a user attempts to write an image larger than this, the image will be scaled to this resolution.

Implemented in HDK_Sample::IMG_SampleFormat, and IMG_FormatPassThru.

virtual const char* IMG_Format::getMetadataKey ( ) const

virtual

When looking up metadata, this is the key to identify format specific metadata. This method defaults to returning getFormatName().

static int IMG_Format::getNFormats ( )

static

number of currently installed image formats

virtual const IMG_FileOptionList* IMG_Format::getOptions ( ) const

virtual

Returns a list of options that can be set on the format when reading or writing (like 'compression' or 'comment').

Reimplemented in IMG_FormatPassThru.

static const IMG_Format* IMG_Format::getStdoutFormat ( )

static

virtual IMG_ColorModel IMG_Format::getSupportedColorModels ( ) const

pure virtual

Returns a bitfield of supported color models. If IMG_CM_REVERSED is set, this format stores data in BGR/ABGR format.

Implemented in HDK_Sample::IMG_SampleFormat, and IMG_FormatPassThru.

virtual IMG_ImageType IMG_Format::getSupportedImageTypes ( ) const

virtual

Returns a bitfield of image types supported by this format. By default IMG_TYPE_2D is returned.

virtual IMG_DataType IMG_Format::getSupportedTypes ( ) const

pure virtual

Returns a bitfield of data types supported by this format.

Implemented in HDK_Sample::IMG_SampleFormat, and IMG_FormatPassThru.

static UT_StringHolder IMG_Format::hostnameDefault ( )

static

Specifies if this format can read an image file. One of isReadable() or isWritable() (or both) must return true.

virtual bool IMG_Format::isDataInterleaved ( ) const

virtual

Specifies whether this format stores its data interleaved (RGBRGBRGB) or non-interleaved (RRRGGGBBB). If your format supports both, pick one.

Reimplemented in IMG_FormatPassThru.

virtual bool IMG_Format::isDataWindowCropOnly ( ) const

virtual

if true, this format only supports data windows contained within the image resolution (a crop region).

virtual bool IMG_Format::isDataWindowStreakSupported ( ) const

virtual

does this format support saving whether the data outside the window is streaked from the window edges?

Reimplemented in IMG_FormatPassThru.

virtual bool IMG_Format::isDataWindowSupported ( ) const

virtual

does this format support a data window or sub-area.

Reimplemented in IMG_FormatPassThru.

virtual bool IMG_Format::isDeepRasterSupported ( ) const

virtual

does this format support deep rasters or multiple images? If not, only one plane of the color models that this format supports is allowed.

Reimplemented in IMG_FormatPassThru.

virtual int IMG_Format::isFormatOk ( const IMG_Stat &  stat ) const

protectedvirtual

Reimplemented in IMG_FormatPassThru.

virtual int IMG_Format::isLeftFirst ( ) const

virtual

horizontal data orientation. Where (0,0) lies in the image (top-left by default).

Reimplemented in IMG_FormatPassThru.

virtual bool IMG_Format::isPassThrough ( ) const

inlinevirtual

Flags whether the format is a pass through format like Flip or Scale. Specific image formats (like JPEG) are never pass-through.

Reimplemented in IMG_FormatPassThru.

Definition at line 126 of file IMG_Format.h.

virtual bool IMG_Format::isReadable ( ) const

virtual

Specifies if this format can read an image file. One of isReadable() or isWritable() (or both) must return true.

virtual int IMG_Format::isReadRandomAccess ( ) const

virtual

Some formats can be read and written in random order. Others require strict sequential order. If these methods return false, you should read and write scanlines in ascending order. When writing, they will be cached until they can be written sequentially.

Reimplemented in HDK_Sample::IMG_SampleFormat, and IMG_FormatPassThru.

virtual int IMG_Format::isTopFirst ( ) const

virtual

vertical data orientation. Where (0,0) lies in the image (top-left by default).

Reimplemented in IMG_FormatPassThru.

virtual bool IMG_Format::isWritable ( ) const

virtual

Specifies if this format can write an image file. One of isReadable() or isWritable() (or both) must return true.

virtual int IMG_Format::isWriteRandomAccess ( ) const

virtual

If 0 is returned, the scanlines must be written in sequential order or they will be cached until all scanlines can be written sequentially.

Reimplemented in HDK_Sample::IMG_SampleFormat, and IMG_FormatPassThru.

static int IMG_Format::matchExtension ( const char *  filename, const char *  ext  )

static

Matches a filename against a single extension.

static int IMG_Format::matchExtensions ( const char *  filename, const char *  ext[]  )

static

Matches a filename against a list of extensions (the last entry must be NULL)

Examples:

IMG/IMG_Sample.C.

static const IMG_Format* IMG_Format::metadataPrefix ( const char *  key )

static

Find the format which has the metdata specific prefix. For example passing "OpenEXR:compression" will return the IMG_Format used for OpenEXR images. Returns nullptr if there's no format prefix.

void IMG_Format::removeFormatFromList ( )

protected

virtual const IMG_Format* IMG_Format::resolvePriority ( const IMG_Format *  format ) const

virtual

Between these two formats, which should be preferred? returns either this or the format parameter. This method is used to resolve conflicts between formats when files are being created.

static bool IMG_Format::setFormatOptionDefault ( const char *  format_name, const char *  format_option, const char *  defvalue  )

static

Allows you to change an option on a specific format. This will change the option for all formats from this point on, whereas setGlobalOption would not. Returns false if the format or the option couldn't be found.

static void IMG_Format::setGlobalOption ( const char *  name, const char *  value  )

static

Set an option globally for all formats. Use with extreme care.

---

The documentation for this class was generated from the following file:

• IMG/IMG_Format.h