OpenImageIO::ImageBuf Class Reference

#include <imagebuf.h>

Classes
class	ConstIterator
class	Iterator
Public Member Functions
	ImageBuf (const std::string &name=std::string(), ImageCache *imagecache=NULL)
	ImageBuf (const std::string &name, const ImageSpec &spec)
virtual	~ImageBuf ()
virtual void	clear ()
virtual void	reset (const std::string &name=std::string(), ImageCache *imagecache=NULL)
virtual void	reset (const std::string &name, const ImageSpec &spec)
virtual void	alloc (const ImageSpec &spec)
virtual bool	read (int subimage=0, bool force=false, TypeDesc convert=TypeDesc::UNKNOWN, OpenImageIO::ProgressCallback progress_callback=NULL, void *progress_callback_data=NULL)
virtual bool	init_spec (const std::string &filename)
virtual bool	save (const std::string &filename=std::string(), const std::string &fileformat=std::string(), OpenImageIO::ProgressCallback progress_callback=NULL, void *progress_callback_data=NULL) const
virtual bool	write (ImageOutput out, OpenImageIO::ProgressCallback progress_callback=NULL, void progress_callback_data=NULL) const
std::string	geterror (void) const
std::string	error_message () const
const ImageSpec &	spec () const
const std::string &	name (void) const
const std::string &	file_format_name (void) const
int	subimage () const
int	nsubimages () const
int	nchannels () const
float	getchannel (int x, int y, int c) const
void	getpixel (int x, int y, float *pixel, int maxchannels=1000) const
void	interppixel (float x, float y, float *pixel) const
void	interppixel_NDC (float x, float y, float *pixel) const
void	interppixel_NDC_full (float x, float y, float *pixel) const
void	setpixel (int x, int y, const float *pixel, int maxchannels=1000)
void	setpixel (int i, const float *pixel, int maxchannels=1000)
bool	copy_pixels (int xbegin, int xend, int ybegin, int yend, TypeDesc format, void *result) const
template<typename T >
bool	copy_pixels (int xbegin, int xend, int ybegin, int yend, T *result) const
template<typename T >
bool	copy_pixels (int xbegin, int xend, int ybegin, int yend, std::vector< T > &result) const
int	orientation () const
int	oriented_width () const
int	oriented_height () const
int	oriented_x () const
int	oriented_y () const
int	oriented_full_width () const
int	oriented_full_height () const
int	oriented_full_x () const
int	oriented_full_y () const
int	xbegin () const
int	xend () const
int	ybegin () const
int	yend () const
int	xmin () const
int	xmax () const
int	ymin () const
int	ymax () const
void	zero ()
void	fill (const float *pixel)
void	fill (const float *pixel, int xbegin, int xend, int ybegin, int yend)
bool	pixels_valid (void) const
bool	localpixels () const
ImageCache *	imagecache () const
Protected Member Functions
void	realloc ()
const void *	pixeladdr (int x, int y) const
void *	pixeladdr (int x, int y)
const void *	retile (int subimage, int x, int y, ImageCache::Tile *&tile, int &tilexbegin, int &tileybegin) const
Protected Attributes
ustring	m_name
	Filename of the image.
ustring	m_fileformat
	File format name.
int	m_nsubimages
	How many subimages are there?
int	m_current_subimage
	Current subimage we're viewing.
ImageSpec	m_spec
	Describes the image (size, etc).
std::vector< char >	m_pixels
	Pixel data.
bool	m_localpixels
	Pixels are local, in m_pixels.
bool	m_spec_valid
	Is the spec valid.
bool	m_pixels_valid
	Image is valid.
bool	m_badfile
	File not found.
std::string	m_err
	Last error message.
int	m_orientation
	Orientation of the image.
float	m_pixelaspect
	Pixel aspect ratio of the image.
ImageCache *	m_imagecache
	ImageCache to use.
TypeDesc	m_cachedpixeltype
	Data type stored in the cache.

Detailed Description

An ImageBuf is a simple in-memory representation of a 2D image. It uses ImageInput and ImageOutput underneath for its file I/O, and has simple routines for setting and getting individual pixels, that hides most of the details of memory layout and data representation (translating to/from float automatically).

Constructor & Destructor Documentation

OpenImageIO::ImageBuf::ImageBuf	(	const std::string &	name = `std::string()`,
		ImageCache *	imagecache = `NULL`
	)

Construct an ImageBuf to read the named image. If name is the empty string (the default), it's a completely uninitialized ImageBuf.

OpenImageIO::ImageBuf::ImageBuf	(	const std::string &	name,
		const ImageSpec &	spec
	)

Construct an Imagebuf given both a name and a proposed spec describing the image size and type, and allocate storage for the pixels of the image (whose values will be undefined).

virtual OpenImageIO::ImageBuf::~ImageBuf ( ) [virtual]

Destructor for an ImageBuf.

Member Function Documentation

virtual void OpenImageIO::ImageBuf::alloc ( const ImageSpec & spec ) [virtual]

Allocate space the right size for an image described by the format spec. If the ImageBuf already has allocated pixels, their values will not be preserved if the new spec does not describe an image of the same size and data type as it used to be.

virtual void OpenImageIO::ImageBuf::clear ( ) [virtual]

Restore the ImageBuf to an uninitialized state.

template<typename T >

bool OpenImageIO::ImageBuf::copy_pixels	(	int	xbegin,
		int	xend,
		int	ybegin,
		int	yend,
		std::vector< T > &	result
	)			const `[inline]`

Even safer version of copy_pixels: Retrieve the rectangle of pixels spanning [xbegin..xend) X [ybegin..yend) (with exclusive 'end'), specified as integer pixel coordinates, at the current MIP-map level, storing the pixel values in the 'result' vector (even allocating the right size). Return true if the operation could be completed, otherwise return false.

template<typename T >

bool OpenImageIO::ImageBuf::copy_pixels	(	int	xbegin,
		int	xend,
		int	ybegin,
		int	yend,
		T *	result
	)			const `[inline]`

Retrieve the rectangle of pixels spanning [xbegin..xend) X [ybegin..yend) (with exclusive 'end'), specified as integer pixel coordinates, at the current MIP-map level, storing the pixel values beginning at the address specified by result, converting to the type <T> in the process. It is up to the caller to ensure that result points to an area of memory big enough to accommodate the requested rectangle. Return true if the operation could be completed, otherwise return false.

bool OpenImageIO::ImageBuf::copy_pixels	(	int	xbegin,
		int	xend,
		int	ybegin,
		int	yend,
		TypeDesc	format,
		void *	result
	)			const

Retrieve the rectangle of pixels spanning [xbegin..xend) X [ybegin..yend) (with exclusive 'end'), specified as integer pixel coordinates, at the current MIP-map level, storing the pixel values beginning at the address specified by result. It is up to the caller to ensure that result points to an area of memory big enough to accommodate the requested rectangle. Return true if the operation could be completed, otherwise return false.

std::string OpenImageIO::ImageBuf::error_message ( ) const [inline]

Deprecated

const std::string& OpenImageIO::ImageBuf::file_format_name ( void ) const [inline]

Return the name of the image file format of the disk file we read into this image. Returns an empty string if this image was not the result of a read().

void OpenImageIO::ImageBuf::fill	(	const float *	pixel,
		int	xbegin,
		int	xend,
		int	ybegin,
		int	yend
	)

Fill a subregion of the image with the given pixel value. The subregion is bounded by [xbegin..xend) X [ybegin..yend).

void OpenImageIO::ImageBuf::fill ( const float * pixel )

Fill the entire image with the given pixel value.

float OpenImageIO::ImageBuf::getchannel	(	int	x,
		int	y,
		int	c
	)			const

Retrieve a single channel of one pixel.

std::string OpenImageIO::ImageBuf::geterror ( void ) const [inline]

Return info on the last error that occurred since geterror() was called. This also clears the error message for next time.

void OpenImageIO::ImageBuf::getpixel	(	int	x,
		int	y,
		float *	pixel,
		int	maxchannels = `1000`
	)			const

Retrieve the pixel value by x and y coordintes (on [0,res-1]), storing the floating point version in pixel[]. Retrieve at most maxchannels (will be clamped to the actual number of channels).

virtual bool OpenImageIO::ImageBuf::init_spec ( const std::string & filename ) [virtual]

Initialize this ImageBuf with the named image file, and read its header to fill out the spec correctly. Return true if this succeeded, false if the file could not be read. But don't allocate or read the pixels.

void OpenImageIO::ImageBuf::interppixel	(	float	x,
		float	y,
		float *	pixel
	)			const

Linearly interpolate at pixel coordinates (x,y), where (0,0) is the upper left corner, (xres,yres) the lower right corner of the pixel data.

void OpenImageIO::ImageBuf::interppixel_NDC	(	float	x,
		float	y,
		float *	pixel
	)			const `[inline]`

Linearly interpolate at pixel coordinates (x,y), where (0,0) is the upper left corner of the pixel data window, (1,1) the lower right corner of the pixel data.

void OpenImageIO::ImageBuf::interppixel_NDC_full	(	float	x,
		float	y,
		float *	pixel
	)			const `[inline]`

Linearly interpolate at pixel coordinates (x,y), where (0,0) is the upper left corner of the display window, (1,1) the lower right corner of the display window.

const std::string& OpenImageIO::ImageBuf::name ( void ) const [inline]

Return the name of this image.

int OpenImageIO::ImageBuf::nchannels ( ) const [inline]

Return the number of color channels in the image.

int OpenImageIO::ImageBuf::nsubimages ( ) const [inline]

Return the number of subimages in the file.

virtual bool OpenImageIO::ImageBuf::read	(	int	subimage = `0`,
		bool	force = `false`,
		TypeDesc	convert = `TypeDesc::UNKNOWN`,
		OpenImageIO::ProgressCallback	progress_callback = `NULL`,
		void *	progress_callback_data = `NULL`
	)			`[virtual]`

Read the file from disk. Generally will skip the read if we've already got a current version of the image in memory, unless force==true. This uses ImageInput underneath, so will read any file format for which an appropriate imageio plugin can be found. Return value is true if all is ok, otherwise false.

virtual void OpenImageIO::ImageBuf::reset	(	const std::string &	name,
		const ImageSpec &	spec
	)			`[virtual]`

Forget all previous info, reset this ImageBuf to a blank image of the given name and dimensions.

virtual void OpenImageIO::ImageBuf::reset	(	const std::string &	name = `std::string()`,
		ImageCache *	imagecache = `NULL`
	)			`[virtual]`

Forget all previous info, reset this ImageBuf to a new image.

virtual bool OpenImageIO::ImageBuf::save	(	const std::string &	filename = `std::string()`,
		const std::string &	fileformat = `std::string()`,
		OpenImageIO::ProgressCallback	progress_callback = `NULL`,
		void *	progress_callback_data = `NULL`
	)			const `[virtual]`

Save the image or a subset thereof, with override for filename ("" means use the original filename) and file format ("" indicates to infer it from the filename). This uses ImageOutput underneath, so will write any file format for which an appropriate imageio plugin can be found.

void OpenImageIO::ImageBuf::setpixel	(	int	i,
		const float *	pixel,
		int	maxchannels = `1000`
	)

Set the i-th pixel value of the image (out of width*height*depth), from floating-point values in pixel[]. Set at most maxchannels (will be clamped to the actual number of channels).

void OpenImageIO::ImageBuf::setpixel	(	int	x,
		int	y,
		const float *	pixel,
		int	maxchannels = `1000`
	)

Set the pixel value by x and y coordintes (on [0,res-1]), from floating-point values in pixel[]. Set at most maxchannels (will be clamped to the actual number of channels).

const ImageSpec& OpenImageIO::ImageBuf::spec ( ) const [inline]

Return a read-only (const) reference to the image spec.

int OpenImageIO::ImageBuf::subimage ( ) const [inline]

Return the index of the subimage are we currently viewing

virtual bool OpenImageIO::ImageBuf::write	(	ImageOutput *	out,
		OpenImageIO::ProgressCallback	progress_callback = `NULL`,
		void *	progress_callback_data = `NULL`
	)			const `[virtual]`

Write the image to the open ImageOutput 'out'. Return true if all went ok, false if there were errors writing. It does NOT close the file when it's done (and so may be called in a loop to write a multi-image file).

int OpenImageIO::ImageBuf::xbegin ( ) const [inline]

Return the beginning (minimum) x coordinate of the defined image.

int OpenImageIO::ImageBuf::xend ( ) const [inline]

Return the end (one past maximum) x coordinate of the defined image.

int OpenImageIO::ImageBuf::xmax ( ) const [inline]

Return the maximum x coordinate of the defined image.

int OpenImageIO::ImageBuf::xmin ( ) const [inline]

Return the minimum x coordinate of the defined image.

int OpenImageIO::ImageBuf::ybegin ( ) const [inline]

Return the beginning (minimum) y coordinate of the defined image.

int OpenImageIO::ImageBuf::yend ( ) const [inline]

Return the end (one past maximum) y coordinate of the defined image.