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:

Public Member Functions
virtual	~IMG_File ()

virtual int64	getMemoryUsage (bool inclusive) const

virtual const char *	className () const

int	close ()

int	getReadMode () const
	Returns 1 if we are reading, 0 if writing. More...

virtual void	getAdditionalInfo (UT_String &text)

const char *	getOption (const char *name) const

const void *	read (int scan, const IMG_Plane *from_plane=nullptr)
	read a single scanline. read() returns a pointer to the scanline data in an internal buffer. Do not delete it. More...

bool	readIntoBuffer (int scan, void buffer, const IMG_Plane from_plane=nullptr)
	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. More...

bool	write (int scan, const void data, const IMG_Plane to_plane=nullptr)
	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 occurred (many formats will behave unpredictably otherwise). More...

void *	allocScanlineBuffer () const

bool	readImages (UT_Array< PXL_Raster * > &images, const char *scope=nullptr)
	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. More...

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

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

virtual UT_SharedPtr< UT_Options >	imageTextureOptions () const

virtual const UT_Options *	getImageTextureOptions () const
	This method is deprecated. Please implement `imageTextureOptions()` More...

virtual void	clearImageTextureOptions ()

virtual bool	setImageTextureOptions (const UT_Options &options)

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

bool	getWorldToCamera (UT_Matrix4D &xform) const

bool	getCameraToNDC (UT_Matrix4D &xform, int xres, int yres, bool fit_z=true) const

bool	getWorldToNDC (UT_Matrix4D &xform, int xres, int yres, bool fit_z=true) const

virtual int	getDeepPixelSamples (int x, int y)

virtual bool	getDeepPixelPlaneData (int x, int y, const IMG_Plane &plane, float *data)

virtual bool	getDeepPixelData (int x, int y, float const data)

virtual bool	readDeepPixelData (int x, int y, PXL_DeepSampleList &pixel)
	Read a deep pixel. More...


IMG_ImageType	getImageType () const


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)


bool	writeImages (const UT_Array< const PXL_Raster * > &imgs)
	Writes all PXL_Rasters to the image format. This method takes a raster per IMG_Plane in the stat. The data format, color model 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. More...

bool	writeImages (UT_Array< 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, color model 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. More...


virtual int	isTopFirst () const

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


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)


virtual bool	writeDeepPixelData (int x, int y, const PXL_DeepSampleListPtr &pixel)


void	selectPlanesToRead ()

bool	isPlaneSelected (const IMG_Plane &plane) const

Static Public Member Functions
static IMG_File *	open (const char filename, const IMG_FileParms options=nullptr, const IMG_Format *fmt=nullptr)
	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 resolution, 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. More...

static IMG_File *	open (UT_IStream &is, const IMG_FileParms options=nullptr, const IMG_Format fmt=nullptr, 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 resolution, 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. More...

static IMG_File *	create (const char filename, const IMG_Stat &stat, const IMG_FileParms options=nullptr, const IMG_Format *fmt=nullptr)
	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. More...

static IMG_File *	create (std::ostream &os, const IMG_Stat &stat, const IMG_FileParms options=nullptr, const IMG_Format fmt=nullptr, 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. More...

static bool	saveRastersAsFiles (const char *filename, const IMG_SaveRastersToFilesParms &parms)
	Writes PXL_Raster's to image files. Convenience method to write images stored in PXL_Raster's to disk files. The `linear_planes` parameter specifies a pattern of planes which should be written to in linear space. More...

static bool	copyToFile (const char sourcename, const char destname, const IMG_FileParms *options=nullptr)
	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. More...

static bool	copyToFileFormat (const char sourcename, const char formatname, UT_String destname=nullptr, const IMG_FileParms options=nullptr)

static bool	copyToStream (const char sourcename, std::ostream &deststream, const IMG_FileParms options=nullptr, const IMG_Format *format=nullptr)
	Copies an existing 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. More...

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

static int	doErrors (int newDoErrors)

static void	setFileCreateCB (UT_Functor1< int, const UT_StringRef & > cb)


static bool	saveRasterAsFile (const char filename, const PXL_Raster raster, const IMG_SaveRastersToFilesParms &parms)
	Writes a PXL_Raster to an image file. Convenience method to write an image stored in a PXL_Raster to a disk file. More...

static bool	saveRasterAsFile (const char filename, const PXL_Raster raster, const IMG_FileParms fparms=nullptr, const IMG_Format format=nullptr)
	Writes a PXL_Raster to an image file. Convenience method to write an image stored in a PXL_Raster to a disk file. More...

Protected Member Functions
	IMG_File ()

virtual int	open ()
	Only called by format class. More...

virtual int	openPostMagic ()

virtual int	openFile (const char *filename)

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 void	postCloseAction ()

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)

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 (std::ostream &os)

void	deleteStream ()

UT_IStream *	getUTIStream ()

void	setIStream (UT_IStream *is)


int	setOption (const char token, const char value)

int	setOption (const char *token, fpreal64 val)

int	setOption (const char *token, int64 val)

int	setOption (const char *option, int value)

Static Protected Member Functions
static void	imgError (int code, const char *msg=nullptr)

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

static void	setOptions (const IMG_FileParms options, IMG_File file)

Protected Attributes
IMG_Stat	myStat

bool	myReadMode

std::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_Sample.C, and IMG/IMG_Sample.h.

Definition at line 55 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 interrupted 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

inlinevirtual

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

Definition at line 173 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.

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_Sample.C.

virtual int IMG_File::closeFile ( )

protectedpure virtual

Implemented in IMG_PSD, IMG_FileTTMap, IMG_FileFilter, HDK_Sample::IMG_Sample, and IMG_FileIES.

virtual void IMG_File::computeCommonData ( )

protectedvirtual

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

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

Copy the texture image options from another IMG_File.

void IMG_File::copyInputToStream ( std::ostream & os )

protected

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

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::copyToFileFormat	(	const char *	sourcename,
		const char *	formatname,
		UT_String *	destname = `nullptr`,
		const IMG_FileParms *	options = `nullptr`
	)

static

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

static

Copies an existing 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_File* IMG_File::create	(	const char *	filename,
		const IMG_Stat &	stat,
		const IMG_FileParms *	options = `nullptr`,
		const IMG_Format *	fmt = `nullptr`
	)

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.

static IMG_File* IMG_File::create	(	std::ostream &	os,
		const IMG_Stat &	stat,
		const IMG_FileParms *	options = `nullptr`,
		const IMG_Format *	fmt = `nullptr`,
		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.

virtual int IMG_File::create ( const IMG_Stat & stat )

protectedvirtual

Reimplemented in IMG_PSD, and HDK_Sample::IMG_Sample.

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

protectedvirtual

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 )

protectedvirtual

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

inlinevirtual

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

Definition at line 358 of file IMG_File.h.

virtual IMG_File* IMG_File::getBaseFile ( ) const

inlinevirtual

Reimplemented in IMG_FileFilter.

Definition at line 364 of file IMG_File.h.

bool IMG_File::getCameraToNDC	(	UT_Matrix4D &	xform,
		int	xres,
		int	yres,
		bool	fit_z = `true`
	)		const

Read the image options (

See Also: getOption()) to extract the camera to NDC transform. If the data isn't available in the options, this method returns false. This will likely only work when the image is being created from mantra. If the fit_z option is true, the near/far range will be set to (0,1). This will not be possible if the "camera:clip" setting wasn't passed in the options.

virtual bool IMG_File::getDeepPixelData	(	int	x,
		int	y,
		float const	data
	)

virtual

Reimplemented in IMG_FileFilter, IMG_FileFilterFlip, and IMG_FileFilterWindow.

virtual bool IMG_File::getDeepPixelPlaneData	(	int	x,
		int	y,
		const IMG_Plane &	plane,
		float *	data
	)

virtual

Reimplemented in IMG_FileFilter, IMG_FileFilterFlip, and IMG_FileFilterWindow.

virtual int IMG_File::getDeepPixelSamples	(	int	x,
		int	y
	)

virtual

Reimplemented in IMG_FileFilter, IMG_FileFilterFlip, and IMG_FileFilterWindow.

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 191 of file IMG_File.h.

virtual const UT_Options* IMG_File::getImageTextureOptions ( ) const

virtual

This method is deprecated. Please implement imageTextureOptions()

IMG_ImageType IMG_File::getImageType ( ) const

Returns the image type of the format we just opened.

virtual int64 IMG_File::getMemoryUsage ( bool inclusive ) const

virtual

Reimplemented in IMG_FileTTMap.

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 ) const

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

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.

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.

IMG_File* IMG_File::getUnfilteredFile ( )

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

const IMG_File* IMG_File::getUnfilteredFile ( ) const

UT_IStream* IMG_File::getUTIStream ( )

inlineprotected

Definition at line 575 of file IMG_File.h.

bool IMG_File::getWorldToCamera ( UT_Matrix4D & xform ) const

Read the image options (

See Also: getOption()) to extract the world to camera transform. If the data isn't available, this method returns false. This will likely only work when the image is being created from mantra.

bool IMG_File::getWorldToNDC	(	UT_Matrix4D &	xform,
		int	xres,
		int	yres,
		bool	fit_z = `true`
	)		const

Read the image options (

See Also: getOption()) to extract the world to NDC transform. If the data isn't available in the options, this method returns false. This will likely only work when the image is being created from mantra. If the fit_z option is true, the near/far range will be set to (0,1). This will not be possible if the "camera:clip" setting wasn't passed in the options.

bool IMG_File::hasError ( ) const

inline

Definition at line 352 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.

static void IMG_File::imgError	(	int	code,
		const char *	msg = `nullptr`
	)

staticprotected

static void IMG_File::imgWarning	(	int	code,
		const char *	msg = `nullptr`
	)

staticprotected

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

inlineprotectedvirtual

Reimplemented in IMG_FileFilter.

Definition at line 504 of file IMG_File.h.

bool IMG_File::isPlaneSelected ( const IMG_Plane & plane ) const

users of IMG_File can select only certain planes to read using IMG_FileParms::selectPlane..(). Call selectPlanesToRead() first, usually at the end of open(), and then call isPlaneSelected() to determine if the plane was selected for read.

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_FileFilterFlip, and IMG_FileFilter.

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 = `nullptr`
	)

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

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

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 resolution, 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* IMG_File::open	(	UT_IStream &	is,
		const IMG_FileParms *	options = `nullptr`,
		const IMG_Format *	fmt = `nullptr`,
		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 resolution, 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.

virtual int IMG_File::open ( )

protectedvirtual

Only called by format class.

Reimplemented in IMG_PSD, HDK_Sample::IMG_Sample, and IMG_FileIES.

virtual int IMG_File::openFile ( const char * filename )

protectedvirtual

virtual int IMG_File::openPostMagic ( )

protectedvirtual

int IMG_File::peekByte ( )

protected

virtual void IMG_File::postCloseAction ( )

protectedvirtual

Run after the output stream has been closed. Be careful, since some things have been destructed.

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 = `nullptr`
	)

read a single scanline. 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
	)

inlineprotected

Examples:: IMG/IMG_Sample.C.

Definition at line 550 of file IMG_File.h.

virtual bool IMG_File::readDeepPixelData	(	int	x,
		int	y,
		PXL_DeepSampleList &	pixel
	)

virtual

Read a deep pixel.

Reimplemented in IMG_FileFilter, IMG_FileFilterFlip, and IMG_FileFilterWindow.

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_Array< PXL_Raster * > &	images,
		const char *	scope = `nullptr`
	)

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.

Note: You must delete the rasters returned by this method.

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

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
	)

protectedvirtual

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

virtual int IMG_File::readScanline	(	int	scanline,
		void *	data
	)

protectedpure virtual

Implemented in IMG_PSD, IMG_FileFilter, HDK_Sample::IMG_Sample, and IMG_FileIES.

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,
		const PXL_Raster *	raster,
		const IMG_SaveRastersToFilesParms &	parms
	)

static

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 IMG_File::saveRasterAsFile	(	const char *	filename,
		const PXL_Raster *	raster,
		const IMG_FileParms *	fparms = `nullptr`,
		const IMG_Format *	format = `nullptr`
	)

static

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 IMG_File::saveRastersAsFiles	(	const char *	filename,
		const IMG_SaveRastersToFilesParms &	parms
	)

static

Writes PXL_Raster's to image files. Convenience method to write images stored in PXL_Raster's to disk files. The linear_planes parameter specifies a pattern of planes which should be written to in linear space.

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 ( )

users of IMG_File can select only certain planes to read using IMG_FileParms::selectPlane..(). Call selectPlanesToRead() first, usually at the end of open(), and then call isPlaneSelected() to determine if the plane was selected for read.

static void IMG_File::setFileCreateCB ( UT_Functor1< int, const UT_StringRef & > cb )

static

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

void IMG_File::setIStream ( UT_IStream * is )

inlineprotected

Definition at line 576 of file IMG_File.h.

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

protected

Set option to control behaviour of the file. For example, the compression level when creating the image.

int IMG_File::setOption	(	const char *	token,
		fpreal64	val
	)

protected

Set option to control behaviour of the file. For example, the compression level when creating the image.

int IMG_File::setOption	(	const char *	token,
		int64	val
	)

protected

Set option to control behaviour of the file. For example, the compression level when creating the image.

int IMG_File::setOption	(	const char *	option,
		int	value
	)

inlineprotected

Set option to control behaviour of the file. For example, the compression level when creating the image.

Definition at line 529 of file IMG_File.h.

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

staticprotected

virtual void IMG_File::setWriteTag	(	const char *	tagname,
		int	num_values,
		const char const	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 = `nullptr`
	)

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 occurred (many formats will behave unpredictably otherwise).

bool IMG_File::writeBytes	(	const void *	buffer,
		int	size
	)

inlineprotected

Definition at line 552 of file IMG_File.h.

virtual bool IMG_File::writeDeepPixelData	(	int	x,
		int	y,
		const PXL_DeepSampleListPtr &	pixel
	)

virtual

A method to write deep pixel data for all channels, at a given pixel location. The function should be given an array of pointers to float arrays, where each float array contains the value of all image components for a given sample level.

Returns false if the data cannot be written, or if the image is not a deep pixel image.

Reimplemented in IMG_FileFilter, IMG_FileFilterFlip, and IMG_FileFilterWindow.

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

Deprecated:

bool IMG_File::writeImages ( const UT_Array< const PXL_Raster * > & imgs )

Writes all PXL_Rasters to the image format. This method takes a raster per IMG_Plane in the stat. The data format, color model 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.

bool IMG_File::writeImages	(	UT_Array< 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, color model 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
	)

protectedvirtual

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

virtual int IMG_File::writeScanline	(	int	scanline,
		const void *	data
	)

protectedpure virtual

Implemented in IMG_PSD, IMG_FileFilter, HDK_Sample::IMG_Sample, and IMG_FileIES.

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 648 of file IMG_File.h.

friend class IMG_FileFilter

friend

Definition at line 646 of file IMG_File.h.

friend class IMG_Format

friend

Definition at line 645 of file IMG_File.h.

friend class IMG_GZip

friend

Definition at line 647 of file IMG_File.h.

friend class MV_ReadPRISMS

friend

Definition at line 649 of file IMG_File.h.

Member Data Documentation

unsigned IMG_File::myContinueOnErrorFlag

protected

Definition at line 585 of file IMG_File.h.

unsigned IMG_File::myCreateIStream

protected

Definition at line 585 of file IMG_File.h.

unsigned IMG_File::myCreateOStream

protected

Definition at line 585 of file IMG_File.h.

unsigned IMG_File::myErrorFlag

protected

Definition at line 585 of file IMG_File.h.

unsigned IMG_File::myFileOpen

protected

Definition at line 585 of file IMG_File.h.

unsigned IMG_File::myForceRandomReads

protected

Definition at line 585 of file IMG_File.h.

unsigned IMG_File::myHasRandomReads

protected

Definition at line 585 of file IMG_File.h.

std::ostream* IMG_File::myOS

protected

Examples:: IMG/IMG_Sample.C.

Definition at line 582 of file IMG_File.h.

bool IMG_File::myReadMode

protected

Definition at line 581 of file IMG_File.h.

IMG_Stat IMG_File::myStat

protected

Examples:: IMG/IMG_Sample.C.

Definition at line 580 of file IMG_File.h.

int64 IMG_File::myStreamLength

protected

Definition at line 584 of file IMG_File.h.

int64 IMG_File::myStreamStartPos

protected

Definition at line 583 of file IMG_File.h.

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

IMG/IMG_File.h

Public Member Functions

Static Public Member Functions

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Friends

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

Member Data Documentation