IMG_File Class Reference

Generic interface for reading and writing image files. This class handles the reading and writing of all image formats that Houdini supports. Use the static open() or create() methods to get an IMG_File instance to read to or write from. Deleting this instance will close the file. More...

#include <IMG_File.h>

Inheritance diagram for IMG_File:

List of all members.

Public Member Functions

virtual ~IMG_File ()

virtual const char * className () const

int close ()

int getReadMode () const

Returns 1 if we are reading, 0 if writing.

virtual void getAdditionalInfo (UT_String &text)

const char * getOption (const char *name)

const void * read (int scan, const IMG_Plane *from_plane=0)

read a single scannline. read() returns a pointer to the scanline data in an internal buffer. Do not delete it.

bool readIntoBuffer (int scan, void *buffer, const IMG_Plane *from_plane=0)

Reads the scanline into a buffer that you supply. The buffer passed must be big enough to fit the plane passed. getStat().bytesPerPlaneScan() will return the proper size. Returns 0 on failure.

bool write (int scan, const void *data, const IMG_Plane *to_plane=0)

Write a scanline to the file. You don't need to write scanlines in order, nor do you need to write planes in order; the data may be cached however. Returns 0 if there was an error during the write. You should immediately stop writing if a failure occured (many formats will behave unpredicably otherwise).

void * allocScanlineBuffer () const

bool readImages (UT_PtrArray< PXL_Raster * > &images, const char *scope=0)

Reads all the image data into a list of PXL_Rasters. reads the image data into a a series of rasters. The array should be empty, as this method creates and fills the rasters for you.

bool writeImages (UT_PtrArray< PXL_Raster * > &images, bool freerasters=false)

Writes all PXL_Rasters to the image format. This method takes a raster per IMG_Plane in the stat. The data format, colormodel and res of the raster must match the corresponding IMG_Plane. If the format is not a deep raster format, not all images may be written. if 'freerasters' is true, it will free the rasters for you.

virtual bool jumpToFrame (int frame)

virtual void abortWrite ()

virtual void randomReadAccessRequired ()

virtual void checkpoint ()

bool hasError () const

virtual IMG_FileAlphaInfo getAlphaInfo (float &) const

IMG_File * getUnfilteredFile ()

returns the raw file at the top of the filter stack.

const IMG_File * getUnfilteredFile () const

virtual IMG_File * getBaseFile () const

bool copyImageTextureOptions (const IMG_File &src, bool clear_existing)

Copy the texture image options from another IMG_File.

virtual UT_SharedPtr< UT_Options > imageTextureOptions () const

virtual SYS_DEPRECATED const
UT_Options * getImageTextureOptions () const

This method is deprecated. Please implement imageTextureOptions().

virtual void clearImageTextureOptions ()

virtual bool setImageTextureOptions (const UT_Options &options)

virtual void setWriteTag (const char *tagname, int num_values, const char **values)

const IMG_Format * getFormat () const

void setFormat (const IMG_Format *f)

const IMG_Stat & getStat () const

IMG_Stat & getStat ()

int getNumOptions () const

const char * getOptionName (int i) const

const char * getOptionValue (int i) const

bool readImage (void *data, int flip=0, int scaninc=0)

bool writeImage (void *data, int flip=0, int scaninc=0)

virtual int isTopFirst () const

virtual int isLeftFirst () const

If 0, scanlines are right-to-left. Default is 1 (left-to-right).

virtual bool readTile (const UT_InclusiveRect &tile, void *data, const IMG_Plane *plane=0)

virtual bool writeTile (const UT_InclusiveRect &tile, const void *data, const IMG_Plane *plane=0)

Static Public Member Functions

static IMG_File * open (const char *filename, const IMG_FileParms *options=0, const IMG_Format *fmt=0)

Open an image file using a filename Open an image file for reading by specifying the filename and path of the file. An optional IMG_FileParms class may be passed to convert it into a specific image type (8bit, specific resoltion, etc). An optional format may also be passed, which forces the library to assume the image file is of that particular format. This method returns a new IMG_File object which you read the image data from, or NULL if an error occurred.

static IMG_File * open (UT_IStream &is, const IMG_FileParms *options=0, const IMG_Format *fmt=0, int steal_stream=0, bool streamIsSeekable=true)

Open an image file from a stream Open an image file for reading given a stream. This is useful for embedded images in a file. An optional IMG_FileParms class may be passed to convert it into a specific image type (8bit, specific resoltion, etc). An optional format may also be passed, which forces the library to assume the image file is of that particular format. If 'steal_stream' is true, the image library assumes ownership of the stream and closes it when it's finished reading the file. If the stream is not seekable (cannot jump around in the file, such as with a pipe), set 'streamIsSeekable' to false. This method returns a new IMG_File object which you read the image data from, or NULL if an error occurred.

static IMG_File * create (const char *filename, const IMG_Stat &stat, const IMG_FileParms *options=0, const IMG_Format *fmt=0)

Create a new image file Create a new image file with the pathname 'filename' according to the parameters specified in 'stat'. You can supply an optional 'options' class to translate the image before being written (scale, flip, etc). You can also specify an optional 'format' parameter to force the file to be written as a specific image format (regardless of the extension found in 'filename'). NULL may be returned if the file could not be created for any reason.

static IMG_File * create (ostream &os, const IMG_Stat &stat, const IMG_FileParms *options=0, const IMG_Format *fmt=0, int steal_stream=0, bool streamIsSeekable=true)

Write an image file to an existing stream Writes a new image file to the stream 'os' according to the parameters specified in 'stat'. You can supply an optional 'options' class to translate the image before being written (scale, flip, etc). You can also specify an optional 'format' parameter to force the file to be written as a specific image format (regardless of the extension found in 'filename'). If 'steal_stream' is true, the image library assumes ownership of the stream and closes it when it's finished writing the file. If the stream is not seekable (cannot jump around in the file, such as with a pipe), set 'streamIsSeekable' to false. NULL may be returned if the file could not be created in the stream.

static bool saveRasterAsFile (const char *filename, PXL_Raster *raster)

Writes a PXL_Raster to an image file. Convenience method to write an image stored in a PXL_Raster to a disk file.

static bool copyToFile (const char *sourcename, const char *destname, const IMG_FileParms *options=0)

Copies an existing image file to another image file. Convenience method to copy an image file from one file to another. The image date may be altered if the formats of the two files are not the same (based on filename extension), or if an optional 'options' class is passed.

static bool copyToStream (const char *sourcename, ostream &deststream, const IMG_FileParms *options=0, const IMG_Format *format=0)

Copies an exsting image file to a stream Convenience method to copy an image file to a stream. The image data may be altered if an optional 'options' class is passed, or if the optional image 'format' parameter does not match the format of the source image file.

static IMG_DataType mapStorageOption (const char *option, bool *denormalize_flag=0)

static int doErrors (int newDoErrors)

Protected Member Functions

IMG_File ()

virtual int open ()

Only called by format class.

virtual int openPostMagic ()

virtual int openFile (const char *filename)

void selectPlanesToRead ()

bool isPlaneSelected (const IMG_Plane &plane) const

virtual int readScanline (int scanline, void *data)=0

virtual const void * readPlaneScanline (int y, const IMG_Plane &pi)

virtual int createFile (const char *filename, const IMG_Stat &stat)

virtual int create (const IMG_Stat &stat)

virtual int writeScanline (int scanline, const void *data)=0

virtual int writePlaneScanline (const void *data, int y, const IMG_Plane &pi)

virtual int closeFile ()=0

virtual bool isPassThrough () const

IMG_File * makeReadFilters (const IMG_FileParms &parms)

IMG_File * makeWriteFilters (const IMG_FileParms &parms)

virtual void computeCommonData ()

void * getScanlineBuffer (int y)

void * getPlaneBuffer (int y, const IMG_Plane &pi)

virtual void finishedScanline (int scan)

int setOption (const char *token, const char *value)

bool canWriteStatWithoutConversion () const

int peekByte ()

int readSomeBytes (void *buffer, int size)

int writeSomeBytes (const void *buffer, int size)

bool flushBytes ()

bool readBytes (void *buffer, int size)

bool writeBytes (const void *buffer, int size)

bool readAsciiLine (UT_WorkBuffer &wbuf)

bool seekFromBeginning (int64 offset)

bool seekFromCurrent (int64 offset)

bool seekFromEnd (int64 offset)

int64 tellCurrentPosition ()

void copyInputToStream (ostream &os)

void deleteStream ()

UT_IStream * getUTIStream ()

void setIStream (UT_IStream *is)

Static Protected Member Functions

static void imgError (int code, const char *msg=0)

static void imgWarning (int code, const char *msg=0)

static void setOptions (const IMG_FileParms *options, IMG_File *file)

Protected Attributes

IMG_Stat myStat

bool myReadMode

ostream * myOS

int64 myStreamStartPos

int64 myStreamLength

unsigned myCreateIStream:1

unsigned myCreateOStream:1

unsigned myForceRandomReads:1

unsigned myHasRandomReads:1

unsigned myFileOpen:1

unsigned myErrorFlag:1

unsigned myContinueOnErrorFlag:1

Friends

class IMG_Format

class IMG_FileFilter

class IMG_GZip

class IMG_FileBuffer

class MV_ReadPRISMS

Detailed Description

Generic interface for reading and writing image files. This class handles the reading and writing of all image formats that Houdini supports. Use the static open() or create() methods to get an IMG_File instance to read to or write from. Deleting this instance will close the file.

Examples:: IMG/IMG_Raw.C, and IMG/IMG_Raw.h.

Definition at line 54 of file IMG_File.h.

Constructor & Destructor Documentation

virtual IMG_File::~IMG_File ( ) [virtual]

IMG_File::IMG_File ( ) [protected]

Member Function Documentation

virtual void IMG_File::abortWrite ( ) [virtual]

When writing an image, call if interruptted or you encounter an non-image-file error and cannot complete the file write.

void* IMG_File::allocScanlineBuffer ( ) const

allocates a buffer large enough to hold the biggest plane's scanline in the file. Free this buffer with free(). (This will not hold all the planes' scanlines, only one at a time!)

bool IMG_File::canWriteStatWithoutConversion ( ) const [protected]

virtual void IMG_File::checkpoint ( ) [virtual]

When writing an image, the checkpoint() method can be used to checkpoint data (see TIFFCheckpointDirectory() for an example). Generally, this writes the image data currently passed and this results in a usable, partially written file. By default, nothing is done.

Reimplemented in IMG_FileFilter.

virtual const char* IMG_File::className ( void ) const [inline, virtual]

Reimplemented in IMG_FileFilterConvert, IMG_FileFilterFlip, IMG_FileFilterLUT, IMG_FileFilterScale, IMG_FileFilterTile, IMG_FileFilterWindow, and IMG_FileTTMap.

Definition at line 151 of file IMG_File.h.

virtual void IMG_File::clearImageTextureOptions ( ) [virtual]

For image formats which support texture options, this will clear out all texture options.

Reimplemented in IMG_FileFilter, and IMG_FileTTMap.

int IMG_File::close ( )

Closes the file. Called by the destructor if needed , so 'delete file' will often take the place of this call. However, you won't receive any error information in that case, so you can call it directly.

Examples:: IMG/IMG_Raw.C.

virtual int IMG_File::closeFile ( ) [protected, pure virtual]

Implemented in IMG_FileFilter, IMG_FileIES, IMG_FileTTMap, and HDK_Sample::IMG_Raw.

virtual void IMG_File::computeCommonData ( ) [protected, virtual]

Reimplemented in IMG_FileFilter, IMG_FileFilterFlip, IMG_FileFilterLUT, IMG_FileFilterTile, and IMG_FileFilterWindow.

bool IMG_File::copyImageTextureOptions	(	const IMG_File &	src,
		bool	clear_existing
	)

Copy the texture image options from another IMG_File.

void IMG_File::copyInputToStream ( ostream & os ) [protected]

static bool IMG_File::copyToFile	(	const char *	sourcename,
		const char *	destname,
		const IMG_FileParms *	options = `0`
	)			`[static]`

Copies an existing image file to another image file. Convenience method to copy an image file from one file to another. The image date may be altered if the formats of the two files are not the same (based on filename extension), or if an optional 'options' class is passed.

static bool IMG_File::copyToStream	(	const char *	sourcename,
		ostream &	deststream,
		const IMG_FileParms *	options = `0`,
		const IMG_Format *	format = `0`
	)			`[static]`

Copies an exsting image file to a stream Convenience method to copy an image file to a stream. The image data may be altered if an optional 'options' class is passed, or if the optional image 'format' parameter does not match the format of the source image file.

virtual int IMG_File::create ( const IMG_Stat & stat ) [protected, virtual]

Reimplemented in HDK_Sample::IMG_Raw.

static IMG_File* IMG_File::create	(	ostream &	os,
		const IMG_Stat &	stat,
		const IMG_FileParms *	options = `0`,
		const IMG_Format *	fmt = `0`,
		int	steal_stream = `0`,
		bool	streamIsSeekable = `true`
	)			`[static]`

Write an image file to an existing stream Writes a new image file to the stream 'os' according to the parameters specified in 'stat'. You can supply an optional 'options' class to translate the image before being written (scale, flip, etc). You can also specify an optional 'format' parameter to force the file to be written as a specific image format (regardless of the extension found in 'filename'). If 'steal_stream' is true, the image library assumes ownership of the stream and closes it when it's finished writing the file. If the stream is not seekable (cannot jump around in the file, such as with a pipe), set 'streamIsSeekable' to false. NULL may be returned if the file could not be created in the stream.

static IMG_File* IMG_File::create	(	const char *	filename,
		const IMG_Stat &	stat,
		const IMG_FileParms *	options = `0`,
		const IMG_Format *	fmt = `0`
	)			`[static]`

Create a new image file Create a new image file with the pathname 'filename' according to the parameters specified in 'stat'. You can supply an optional 'options' class to translate the image before being written (scale, flip, etc). You can also specify an optional 'format' parameter to force the file to be written as a specific image format (regardless of the extension found in 'filename'). NULL may be returned if the file could not be created for any reason.

virtual int IMG_File::createFile	(	const char *	filename,
		const IMG_Stat &	stat
	)			`[protected, virtual]`

void IMG_File::deleteStream ( ) [protected]

static int IMG_File::doErrors ( int newDoErrors ) [static]

Turns error reporting on or off. Returns the previous setting. Errors are reported to the error manager, which will either show up in the node information or the Houdini status bar (if not loaded within a node).

virtual void IMG_File::finishedScanline ( int scan ) [protected, virtual]

bool IMG_File::flushBytes ( ) [protected]

virtual void IMG_File::getAdditionalInfo ( UT_String & text ) [virtual]

Get additional image information about the file that is specific to a particular format. Some formats do not have additional information. The information returned is human-readable in 'text'.

Reimplemented in IMG_FileFilter.

virtual IMG_FileAlphaInfo IMG_File::getAlphaInfo ( float & ) const [inline, virtual]

Returns information about the alpha channel if the IMG_FileParms passed to open() had detectAlphaDetails() specified.

Definition at line 326 of file IMG_File.h.

virtual IMG_File* IMG_File::getBaseFile ( ) const [inline, virtual]

Reimplemented in IMG_FileFilter.

Definition at line 332 of file IMG_File.h.

const IMG_Format* IMG_File::getFormat ( ) const [inline]

Retrieve the file format description of the file. The format contains all information that is general to all files of this format type.

Definition at line 164 of file IMG_File.h.

virtual SYS_DEPRECATED const UT_Options* IMG_File::getImageTextureOptions ( ) const [virtual]

This method is deprecated. Please implement imageTextureOptions().

int IMG_File::getNumOptions ( ) const

Access to the list of file options this file was saved with.

const char* IMG_File::getOption ( const char * name )

returns the value of an image option passed in through IMG_FileParms. Image options are specific to formats. Returns NULL if the option does not exist on the format.

Examples:: IMG/IMG_Raw.C.

const char* IMG_File::getOptionName ( int i ) const

Access to the list of file options this file was saved with.

const char* IMG_File::getOptionValue ( int i ) const

Access to the list of file options this file was saved with.

void* IMG_File::getPlaneBuffer	(	int	y,
		const IMG_Plane &	pi
	)			`[protected]`

int IMG_File::getReadMode ( ) const

Returns 1 if we are reading, 0 if writing.

void* IMG_File::getScanlineBuffer ( int y ) [protected]

IMG_Stat& IMG_File::getStat ( )

Get the image description of the current image file (resolution, data format, etc). The returned class can be queried for all of the current image file's statistics.

const IMG_Stat& IMG_File::getStat ( ) const

Get the image description of the current image file (resolution, data format, etc). The returned class can be queried for all of the current image file's statistics.

const IMG_File* IMG_File::getUnfilteredFile ( ) const

IMG_File* IMG_File::getUnfilteredFile ( )

returns the raw file at the top of the filter stack.

UT_IStream* IMG_File::getUTIStream ( ) [inline, protected]

Definition at line 456 of file IMG_File.h.

bool IMG_File::hasError ( ) const [inline]

Definition at line 320 of file IMG_File.h.

virtual UT_SharedPtr<UT_Options> IMG_File::imageTextureOptions ( ) const [virtual]

Some image formats support "texture" options. Formats which do not support options should return a NULL pointer. This method calls getImageTextureOptions() by default

Reimplemented in IMG_FileFilter, and IMG_FileTTMap.

static void IMG_File::imgError	(	int	code,
		const char *	msg = `0`
	)			`[static, protected]`

static void IMG_File::imgWarning	(	int	code,
		const char *	msg = `0`
	)			`[static, protected]`

virtual int IMG_File::isLeftFirst ( ) const [virtual]

If 0, scanlines are right-to-left. Default is 1 (left-to-right).

Reimplemented in IMG_FileFilter.

virtual bool IMG_File::isPassThrough ( ) const [inline, protected, virtual]

Reimplemented in IMG_FileFilter.

Definition at line 394 of file IMG_File.h.

bool IMG_File::isPlaneSelected ( const IMG_Plane & plane ) const [protected]

virtual int IMG_File::isTopFirst ( ) const [virtual]

orientation of the current file or format. Some formats support multiple orientations specified in the image files themselves, others simply have a fixed orientation. Call these methods rather than querying the orientation from the format, in case the format supports multiple orientations.

Reimplemented in IMG_FileFilter, and IMG_FileFilterFlip.

virtual bool IMG_File::jumpToFrame ( int frame ) [virtual]

Deprecated:: For image files that contain more than one image, such as a movie file, jump to a particular frame in the movie and reset for reading the scanlines of the new frame

IMG_File* IMG_File::makeReadFilters ( const IMG_FileParms & parms ) [protected]

IMG_File* IMG_File::makeWriteFilters ( const IMG_FileParms & parms ) [protected]

static IMG_DataType IMG_File::mapStorageOption	(	const char *	option,
		bool *	denormalize_flag = `0`
	)			`[static]`

This method converts the "standard" bit depth option to an IMG_DataType. This is used by the -b option in mantra as well as many other places. When dealing with floating point arguments, there's an optional flag to "denormalize" the floating point values when writing. This basically removes tiny precision errors. It's up to the user to deal with the denormalization.

char, byte, 8 = uint8
short, 16 = uint16
int = uint32
FLOAT = fpreal32 (denormalize=true)
HALF = fpreal16 (denormalize=true)
float, 32 = fpreal32
half = fpreal16

virtual int IMG_File::open ( ) [protected, virtual]

Only called by format class.

Reimplemented in IMG_FileIES, and HDK_Sample::IMG_Raw.

static IMG_File* IMG_File::open	(	UT_IStream &	is,
		const IMG_FileParms *	options = `0`,
		const IMG_Format *	fmt = `0`,
		int	steal_stream = `0`,
		bool	streamIsSeekable = `true`
	)			`[static]`

Open an image file from a stream Open an image file for reading given a stream. This is useful for embedded images in a file. An optional IMG_FileParms class may be passed to convert it into a specific image type (8bit, specific resoltion, etc). An optional format may also be passed, which forces the library to assume the image file is of that particular format. If 'steal_stream' is true, the image library assumes ownership of the stream and closes it when it's finished reading the file. If the stream is not seekable (cannot jump around in the file, such as with a pipe), set 'streamIsSeekable' to false. This method returns a new IMG_File object which you read the image data from, or NULL if an error occurred.

static IMG_File* IMG_File::open	(	const char *	filename,
		const IMG_FileParms *	options = `0`,
		const IMG_Format *	fmt = `0`
	)			`[static]`

Open an image file using a filename Open an image file for reading by specifying the filename and path of the file. An optional IMG_FileParms class may be passed to convert it into a specific image type (8bit, specific resoltion, etc). An optional format may also be passed, which forces the library to assume the image file is of that particular format. This method returns a new IMG_File object which you read the image data from, or NULL if an error occurred.

virtual int IMG_File::openFile ( const char * filename ) [protected, virtual]

virtual int IMG_File::openPostMagic ( ) [protected, virtual]

int IMG_File::peekByte ( ) [protected]

virtual void IMG_File::randomReadAccessRequired ( ) [virtual]

call this if you won't be reading the scanlines in order, or if you'll be reading all the scanlines for a single plane first.

Reimplemented in IMG_FileFilter.

const void* IMG_File::read	(	int	scan,
		const IMG_Plane *	from_plane = `0`
	)

read a single scannline. read() returns a pointer to the scanline data in an internal buffer. Do not delete it.

bool IMG_File::readAsciiLine ( UT_WorkBuffer & wbuf ) [protected]

bool IMG_File::readBytes	(	void *	buffer,
		int	size
	)			`[inline, protected]`

Examples:: IMG/IMG_Raw.C.

Definition at line 431 of file IMG_File.h.

bool IMG_File::readImage	(	void *	data,
		int	flip = `0`,
		int	scaninc = `0`
	)

Deprecated:: The following methods read/write a whole raster. Unless the scanline increment is passed in, the stat structure will be used to determine the scanline size. Beware if you're using translators... Use readImages() and writeImages() instead.

bool IMG_File::readImages	(	UT_PtrArray< PXL_Raster * > &	images,
		const char *	scope = `0`
	)

Reads all the image data into a list of PXL_Rasters. reads the image data into a a series of rasters. The array should be empty, as this method creates and fills the rasters for you.

bool IMG_File::readIntoBuffer	(	int	scan,
		void *	buffer,
		const IMG_Plane *	from_plane = `0`
	)

Reads the scanline into a buffer that you supply. The buffer passed must be big enough to fit the plane passed. getStat().bytesPerPlaneScan() will return the proper size. Returns 0 on failure.

virtual const void* IMG_File::readPlaneScanline	(	int	y,
		const IMG_Plane &	pi
	)			`[protected, virtual]`

Reimplemented in IMG_FileFilterConvert, IMG_FileFilterFlip, IMG_FileFilterLUT, IMG_FileFilterScale, and IMG_FileFilterWindow.

virtual int IMG_File::readScanline	(	int	scanline,
		void *	data
	)			`[protected, pure virtual]`

Implemented in IMG_FileFilter, IMG_FileIES, and HDK_Sample::IMG_Raw.

int IMG_File::readSomeBytes	(	void *	buffer,
		int	size
	)			`[protected]`

virtual bool IMG_File::readTile	(	const UT_InclusiveRect &	tile,
		void *	data,
		const IMG_Plane *	plane = `0`
	)			`[virtual]`

This is a tile interface for reading files. To use it, you must pass an IMG_FileParms object to open() with IMG_FileParms::useTileInterface() called. Otherwise, this will just return false. The x-y coords of the tile is in pixels.

Reimplemented in IMG_FileFilterTile.

static bool IMG_File::saveRasterAsFile	(	const char *	filename,
		PXL_Raster *	raster
	)			`[static]`

Writes a PXL_Raster to an image file. Convenience method to write an image stored in a PXL_Raster to a disk file.

bool IMG_File::seekFromBeginning ( int64 offset ) [protected]

bool IMG_File::seekFromCurrent ( int64 offset ) [protected]

bool IMG_File::seekFromEnd ( int64 offset ) [protected]

void IMG_File::selectPlanesToRead ( ) [protected]

void IMG_File::setFormat ( const IMG_Format * f ) [inline]

Retrieve the file format description of the file. The format contains all information that is general to all files of this format type.

Definition at line 165 of file IMG_File.h.

virtual bool IMG_File::setImageTextureOptions ( const UT_Options & options ) [virtual]

For image formats which support texture options, merge the UT_Options into the current options.

Reimplemented in IMG_FileFilter, and IMG_FileTTMap.

void IMG_File::setIStream ( UT_IStream * is ) [inline, protected]

Definition at line 457 of file IMG_File.h.

int IMG_File::setOption	(	const char *	token,
		const char *	value
	)			`[protected]`

static void IMG_File::setOptions	(	const IMG_FileParms *	options,
		IMG_File *	file
	)			`[static, protected]`

virtual void IMG_File::setWriteTag	(	const char *	tagname,
		int	num_values,
		const char **	values
	)			`[virtual]`

When being created through a tile device (i.e. rendering, etc.), the writer may send additional information to the file writer after the image has been created.

Reimplemented in IMG_FileFilter.

int64 IMG_File::tellCurrentPosition ( ) [protected]

bool IMG_File::write	(	int	scan,
		const void *	data,
		const IMG_Plane *	to_plane = `0`
	)

Write a scanline to the file. You don't need to write scanlines in order, nor do you need to write planes in order; the data may be cached however. Returns 0 if there was an error during the write. You should immediately stop writing if a failure occured (many formats will behave unpredicably otherwise).

bool IMG_File::writeBytes	(	const void *	buffer,
		int	size
	)			`[inline, protected]`

Definition at line 433 of file IMG_File.h.

bool IMG_File::writeImage	(	void *	data,
		int	flip = `0`,
		int	scaninc = `0`
	)

Deprecated:

bool IMG_File::writeImages	(	UT_PtrArray< PXL_Raster * > &	images,
		bool	freerasters = `false`
	)

Writes all PXL_Rasters to the image format. This method takes a raster per IMG_Plane in the stat. The data format, colormodel and res of the raster must match the corresponding IMG_Plane. If the format is not a deep raster format, not all images may be written. if 'freerasters' is true, it will free the rasters for you.

virtual int IMG_File::writePlaneScanline	(	const void *	data,
		int	y,
		const IMG_Plane &	pi
	)			`[protected, virtual]`

Reimplemented in IMG_FileFilterConvert, IMG_FileFilterFlip, IMG_FileFilterLUT, IMG_FileFilterScale, and IMG_FileFilterWindow.

virtual int IMG_File::writeScanline	(	int	scanline,
		const void *	data
	)			`[protected, pure virtual]`

Implemented in IMG_FileFilter, IMG_FileIES, and HDK_Sample::IMG_Raw.

int IMG_File::writeSomeBytes	(	const void *	buffer,
		int	size
	)			`[protected]`

virtual bool IMG_File::writeTile	(	const UT_InclusiveRect &	tile,
		const void *	data,
		const IMG_Plane *	plane = `0`
	)			`[virtual]`

this is a tile interface for writing files. To use it, you must pass an IMG_FileParms object to open() with IMG_FileParms::useTileInterface() called. Otherwise, this will just return false. The x-y coords of the tile is in pixels.

Reimplemented in IMG_FileFilterTile.

Friends And Related Function Documentation

friend class IMG_FileBuffer [friend]

Definition at line 505 of file IMG_File.h.

friend class IMG_FileFilter [friend]

Definition at line 503 of file IMG_File.h.

friend class IMG_Format [friend]

Definition at line 502 of file IMG_File.h.

friend class IMG_GZip [friend]

Definition at line 504 of file IMG_File.h.

friend class MV_ReadPRISMS [friend]

Definition at line 506 of file IMG_File.h.

Member Data Documentation

unsigned IMG_File::myContinueOnErrorFlag [protected]

Definition at line 466 of file IMG_File.h.

unsigned IMG_File::myCreateIStream [protected]

Definition at line 466 of file IMG_File.h.

unsigned IMG_File::myCreateOStream [protected]

Definition at line 466 of file IMG_File.h.

unsigned IMG_File::myErrorFlag [protected]

Definition at line 466 of file IMG_File.h.

unsigned IMG_File::myFileOpen [protected]

Definition at line 466 of file IMG_File.h.

unsigned IMG_File::myForceRandomReads [protected]

Definition at line 466 of file IMG_File.h.

unsigned IMG_File::myHasRandomReads [protected]

Definition at line 466 of file IMG_File.h.

ostream* IMG_File::myOS [protected]

Examples:: IMG/IMG_Raw.C.

Definition at line 463 of file IMG_File.h.

bool IMG_File::myReadMode [protected]

Definition at line 462 of file IMG_File.h.

IMG_Stat IMG_File::myStat [protected]

Examples:: IMG/IMG_Raw.C.

Definition at line 461 of file IMG_File.h.

int64 IMG_File::myStreamLength [protected]

Definition at line 465 of file IMG_File.h.

int64 IMG_File::myStreamStartPos [protected]

Definition at line 464 of file IMG_File.h.

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

IMG/IMG_File.h


Public Member Functions
virtual	~IMG_File ()
virtual const char *	className () const
int	close ()
int	getReadMode () const
	Returns 1 if we are reading, 0 if writing.
virtual void	getAdditionalInfo (UT_String &text)
const char *	getOption (const char *name)
const void *	read (int scan, const IMG_Plane *from_plane=0)
	read a single scannline. read() returns a pointer to the scanline data in an internal buffer. Do not delete it.
bool	readIntoBuffer (int scan, void buffer, const IMG_Plane from_plane=0)
	Reads the scanline into a buffer that you supply. The buffer passed must be big enough to fit the plane passed. getStat().bytesPerPlaneScan() will return the proper size. Returns 0 on failure.
bool	write (int scan, const void data, const IMG_Plane to_plane=0)
	Write a scanline to the file. You don't need to write scanlines in order, nor do you need to write planes in order; the data may be cached however. Returns 0 if there was an error during the write. You should immediately stop writing if a failure occured (many formats will behave unpredicably otherwise).
void *	allocScanlineBuffer () const
bool	readImages (UT_PtrArray< PXL_Raster * > &images, const char *scope=0)
	Reads all the image data into a list of PXL_Rasters. reads the image data into a a series of rasters. The array should be empty, as this method creates and fills the rasters for you.
bool	writeImages (UT_PtrArray< PXL_Raster * > &images, bool freerasters=false)
	Writes all PXL_Rasters to the image format. This method takes a raster per IMG_Plane in the stat. The data format, colormodel and res of the raster must match the corresponding IMG_Plane. If the format is not a deep raster format, not all images may be written. if 'freerasters' is true, it will free the rasters for you.
virtual bool	jumpToFrame (int frame)
virtual void	abortWrite ()
virtual void	randomReadAccessRequired ()
virtual void	checkpoint ()
bool	hasError () const
virtual IMG_FileAlphaInfo	getAlphaInfo (float &) const
IMG_File *	getUnfilteredFile ()
	returns the raw file at the top of the filter stack.
const IMG_File *	getUnfilteredFile () const
virtual IMG_File *	getBaseFile () const
bool	copyImageTextureOptions (const IMG_File &src, bool clear_existing)
	Copy the texture image options from another IMG_File.
virtual UT_SharedPtr< UT_Options >	imageTextureOptions () const
virtual SYS_DEPRECATED const UT_Options *	getImageTextureOptions () const
	This method is deprecated. Please implement `imageTextureOptions()`.
virtual void	clearImageTextureOptions ()
virtual bool	setImageTextureOptions (const UT_Options &options)
virtual void	setWriteTag (const char tagname, int num_values, const char *values)

const IMG_Format *	getFormat () const
void	setFormat (const IMG_Format *f)

const IMG_Stat &	getStat () const
IMG_Stat &	getStat ()

int	getNumOptions () const
const char *	getOptionName (int i) const
const char *	getOptionValue (int i) const

bool	readImage (void *data, int flip=0, int scaninc=0)
bool	writeImage (void *data, int flip=0, int scaninc=0)

virtual int	isTopFirst () const
virtual int	isLeftFirst () const
	If 0, scanlines are right-to-left. Default is 1 (left-to-right).

virtual bool	readTile (const UT_InclusiveRect &tile, void data, const IMG_Plane plane=0)
virtual bool	writeTile (const UT_InclusiveRect &tile, const void data, const IMG_Plane plane=0)
Static Public Member Functions
static IMG_File *	open (const char filename, const IMG_FileParms options=0, const IMG_Format *fmt=0)
	Open an image file using a filename Open an image file for reading by specifying the filename and path of the file. An optional IMG_FileParms class may be passed to convert it into a specific image type (8bit, specific resoltion, etc). An optional format may also be passed, which forces the library to assume the image file is of that particular format. This method returns a new IMG_File object which you read the image data from, or NULL if an error occurred.
static IMG_File *	open (UT_IStream &is, const IMG_FileParms options=0, const IMG_Format fmt=0, int steal_stream=0, bool streamIsSeekable=true)
	Open an image file from a stream Open an image file for reading given a stream. This is useful for embedded images in a file. An optional IMG_FileParms class may be passed to convert it into a specific image type (8bit, specific resoltion, etc). An optional format may also be passed, which forces the library to assume the image file is of that particular format. If 'steal_stream' is true, the image library assumes ownership of the stream and closes it when it's finished reading the file. If the stream is not seekable (cannot jump around in the file, such as with a pipe), set 'streamIsSeekable' to false. This method returns a new IMG_File object which you read the image data from, or NULL if an error occurred.
static IMG_File *	create (const char filename, const IMG_Stat &stat, const IMG_FileParms options=0, const IMG_Format *fmt=0)
	Create a new image file Create a new image file with the pathname 'filename' according to the parameters specified in 'stat'. You can supply an optional 'options' class to translate the image before being written (scale, flip, etc). You can also specify an optional 'format' parameter to force the file to be written as a specific image format (regardless of the extension found in 'filename'). NULL may be returned if the file could not be created for any reason.
static IMG_File *	create (ostream &os, const IMG_Stat &stat, const IMG_FileParms options=0, const IMG_Format fmt=0, int steal_stream=0, bool streamIsSeekable=true)
	Write an image file to an existing stream Writes a new image file to the stream 'os' according to the parameters specified in 'stat'. You can supply an optional 'options' class to translate the image before being written (scale, flip, etc). You can also specify an optional 'format' parameter to force the file to be written as a specific image format (regardless of the extension found in 'filename'). If 'steal_stream' is true, the image library assumes ownership of the stream and closes it when it's finished writing the file. If the stream is not seekable (cannot jump around in the file, such as with a pipe), set 'streamIsSeekable' to false. NULL may be returned if the file could not be created in the stream.
static bool	saveRasterAsFile (const char filename, PXL_Raster raster)
	Writes a PXL_Raster to an image file. Convenience method to write an image stored in a PXL_Raster to a disk file.
static bool	copyToFile (const char sourcename, const char destname, const IMG_FileParms *options=0)
	Copies an existing image file to another image file. Convenience method to copy an image file from one file to another. The image date may be altered if the formats of the two files are not the same (based on filename extension), or if an optional 'options' class is passed.
static bool	copyToStream (const char sourcename, ostream &deststream, const IMG_FileParms options=0, const IMG_Format *format=0)
	Copies an exsting image file to a stream Convenience method to copy an image file to a stream. The image data may be altered if an optional 'options' class is passed, or if the optional image 'format' parameter does not match the format of the source image file.
static IMG_DataType	mapStorageOption (const char option, bool denormalize_flag=0)
static int	doErrors (int newDoErrors)
Protected Member Functions
	IMG_File ()
virtual int	open ()
	Only called by format class.
virtual int	openPostMagic ()
virtual int	openFile (const char *filename)
void	selectPlanesToRead ()
bool	isPlaneSelected (const IMG_Plane &plane) const
virtual int	readScanline (int scanline, void *data)=0
virtual const void *	readPlaneScanline (int y, const IMG_Plane &pi)
virtual int	createFile (const char *filename, const IMG_Stat &stat)
virtual int	create (const IMG_Stat &stat)
virtual int	writeScanline (int scanline, const void *data)=0
virtual int	writePlaneScanline (const void *data, int y, const IMG_Plane &pi)
virtual int	closeFile ()=0
virtual bool	isPassThrough () const
IMG_File *	makeReadFilters (const IMG_FileParms &parms)
IMG_File *	makeWriteFilters (const IMG_FileParms &parms)
virtual void	computeCommonData ()
void *	getScanlineBuffer (int y)
void *	getPlaneBuffer (int y, const IMG_Plane &pi)
virtual void	finishedScanline (int scan)
int	setOption (const char token, const char value)
bool	canWriteStatWithoutConversion () const
int	peekByte ()
int	readSomeBytes (void *buffer, int size)
int	writeSomeBytes (const void *buffer, int size)
bool	flushBytes ()
bool	readBytes (void *buffer, int size)
bool	writeBytes (const void *buffer, int size)
bool	readAsciiLine (UT_WorkBuffer &wbuf)
bool	seekFromBeginning (int64 offset)
bool	seekFromCurrent (int64 offset)
bool	seekFromEnd (int64 offset)
int64	tellCurrentPosition ()
void	copyInputToStream (ostream &os)
void	deleteStream ()
UT_IStream *	getUTIStream ()
void	setIStream (UT_IStream *is)
Static Protected Member Functions
static void	imgError (int code, const char *msg=0)
static void	imgWarning (int code, const char *msg=0)
static void	setOptions (const IMG_FileParms options, IMG_File file)
Protected Attributes
IMG_Stat	myStat
bool	myReadMode
ostream *	myOS
int64	myStreamStartPos
int64	myStreamLength
unsigned	myCreateIStream:1
unsigned	myCreateOStream:1
unsigned	myForceRandomReads:1
unsigned	myHasRandomReads:1
unsigned	myFileOpen:1
unsigned	myErrorFlag:1
unsigned	myContinueOnErrorFlag:1
Friends
class	IMG_Format
class	IMG_FileFilter
class	IMG_GZip
class	IMG_FileBuffer
class	MV_ReadPRISMS