#include <imagecache.h>
Public Member Functions | |
virtual void | clear ()=0 |
virtual bool | attribute (const std::string &name, TypeDesc type, const void *val)=0 |
virtual bool | attribute (const std::string &name, int val)=0 |
virtual bool | attribute (const std::string &name, float val)=0 |
virtual bool | attribute (const std::string &name, double val)=0 |
virtual bool | attribute (const std::string &name, const char *val)=0 |
virtual bool | attribute (const std::string &name, const std::string &val)=0 |
virtual bool | getattribute (const std::string &name, TypeDesc type, void *val)=0 |
Get the named attribute, store it in value. | |
virtual bool | getattribute (const std::string &name, int &val)=0 |
virtual bool | getattribute (const std::string &name, float &val)=0 |
virtual bool | getattribute (const std::string &name, double &val)=0 |
virtual bool | getattribute (const std::string &name, char **val)=0 |
virtual bool | getattribute (const std::string &name, std::string &val)=0 |
virtual std::string | resolve_filename (const std::string &filename) const =0 |
virtual bool | get_image_info (ustring filename, ustring dataname, TypeDesc datatype, void *data)=0 |
virtual bool | get_imagespec (ustring filename, ImageSpec &spec, int subimage=0)=0 |
virtual const ImageSpec * | imagespec (ustring filename, int subimage=0)=0 |
virtual bool | get_pixels (ustring filename, int subimage, int xbegin, int xend, int ybegin, int yend, int zbegin, int zend, TypeDesc format, void *result)=0 |
virtual Tile * | get_tile (ustring filename, int subimage, int x, int y, int z)=0 |
virtual void | release_tile (Tile *tile) const =0 |
virtual const void * | tile_pixels (Tile *tile, TypeDesc &format) const =0 |
virtual std::string | geterror () const =0 |
virtual std::string | getstats (int level=1) const =0 |
virtual void | invalidate (ustring filename)=0 |
virtual void | invalidate_all (bool force=false)=0 |
Static Public Member Functions | |
static ImageCache * | create (bool shared=true) |
static void | destroy (ImageCache *x) |
Define an API to an abstract class that manages image files, caches of open file handles as well as tiles of pixels so that truly huge amounts of image data may be accessed by an application with low memory footprint.
virtual bool OpenImageIO::ImageCache::attribute | ( | const std::string & | name, | |
TypeDesc | type, | |||
const void * | val | |||
) | [pure virtual] |
Set an attribute controlling the image cache. Return true if the name and type were recognized and the attrib was set. Documented attributes: int max_open_files : maximum number of file handles held open float max_memory_MB : maximum tile cache size, in MB string searchpath : colon-separated search path for images int autotile : if >0, tile size to emulate for non-tiled images int automip : if nonzero, emulate mipmap on the fly int accept_untiled : if nonzero, accept untiled images, but if zero, reject untiled images (default=1)
virtual void OpenImageIO::ImageCache::clear | ( | ) | [pure virtual] |
Close everything, free resources, start from scratch.
static ImageCache* OpenImageIO::ImageCache::create | ( | bool | shared = true |
) | [static] |
Create a ImageCache and return a pointer. This should only be freed by passing it to ImageCache::destroy()!
If shared==true, it's intended to be shared with other like-minded owners in the same process who also ask for a shared cache. If false, a private image cache will be created.
static void OpenImageIO::ImageCache::destroy | ( | ImageCache * | x | ) | [static] |
Destroy a ImageCache that was created using ImageCache::create().
virtual bool OpenImageIO::ImageCache::get_image_info | ( | ustring | filename, | |
ustring | dataname, | |||
TypeDesc | datatype, | |||
void * | data | |||
) | [pure virtual] |
Get information about the named image. Return true if found and the data has been put in *data. Return false if the image doesn't exist, doesn't have the requested data, if the data doesn't match the type requested. or some other failure.
virtual bool OpenImageIO::ImageCache::get_imagespec | ( | ustring | filename, | |
ImageSpec & | spec, | |||
int | subimage = 0 | |||
) | [pure virtual] |
Get the ImageSpec associated with the named image (the first subimage, by default, or as set by 'subimage'). If the file is found and is an image format that can be read, store a copy of its specification in spec and return true. Return false if the file was not found or could not be opened as an image file by any available ImageIO plugin.
virtual bool OpenImageIO::ImageCache::get_pixels | ( | ustring | filename, | |
int | subimage, | |||
int | xbegin, | |||
int | xend, | |||
int | ybegin, | |||
int | yend, | |||
int | zbegin, | |||
int | zend, | |||
TypeDesc | format, | |||
void * | result | |||
) | [pure virtual] |
Retrieve the rectangle of pixels spanning [xbegin..xend) X [ybegin..yend) X [zbegin..zend), with "exclusive end" a la STL, specified as integer pixel coordinates in the designated subimage, storing the pixel values beginning at the address specified by result. The pixel values will be converted to the type specified by format. It is up to the caller to ensure that result points to an area of memory big enough to accommodate the requested rectangle (taking into consideration its dimensions, number of channels, and data format).
Return true if the file is found and could be opened by an available ImageIO plugin, otherwise return false.
virtual Tile* OpenImageIO::ImageCache::get_tile | ( | ustring | filename, | |
int | subimage, | |||
int | x, | |||
int | y, | |||
int | z | |||
) | [pure virtual] |
Find a tile given by an image filename, subimage, and pixel coordinates. An opaque pointer to the tile will be returned, or NULL if no such file (or tile within the file) exists or can be read. The tile will not be purged from the cache until after release_tile() is called on the tile pointer. This is thread-safe!
virtual bool OpenImageIO::ImageCache::getattribute | ( | const std::string & | name, | |
TypeDesc | type, | |||
void * | val | |||
) | [pure virtual] |
Get the named attribute, store it in value.
virtual std::string OpenImageIO::ImageCache::geterror | ( | ) | const [pure virtual] |
If any of the API routines returned false indicating an error, this routine will return the error string (and clear any error flags). If no error has occurred since the last time geterror() was called, it will return an empty string.
virtual std::string OpenImageIO::ImageCache::getstats | ( | int | level = 1 |
) | const [pure virtual] |
Return the statistics output as a huge string.
virtual const ImageSpec* OpenImageIO::ImageCache::imagespec | ( | ustring | filename, | |
int | subimage = 0 | |||
) | [pure virtual] |
Return a pointer to an ImageSpec associated with the named image (the first subimage, by default, or as set by 'subimage') if the file is found and is an image format that can be read, otherwise return NULL.
This method is much more efficient than get_imagespec(), since it just returns a pointer to the spec held internally by the ImageCache (rather than copying the spec to the user's memory). However, the caller must beware that the pointer is only valid as long as nobody (even other threads) calls invalidate() on the file, or invalidate_all(), or destroys the ImageCache.
virtual void OpenImageIO::ImageCache::invalidate | ( | ustring | filename | ) | [pure virtual] |
Invalidate any loaded tiles or open file handles associated with the filename, so that any subsequent queries will be forced to re-open the file or re-load any tiles (even those that were previously loaded and would ordinarily be reused). A client might do this if, for example, they are aware that an image being held in the cache has been updated on disk. This is safe to do even if other procedures are currently holding reference-counted tile pointers from the named image, but those procedures will not get updated pixels until they release the tiles they are holding.
virtual void OpenImageIO::ImageCache::invalidate_all | ( | bool | force = false |
) | [pure virtual] |
Invalidate all loaded tiles and open file handles. This is safe to do even if other procedures are currently holding reference-counted tile pointers from the named image, but those procedures will not get updated pixels until they release the tiles they are holding. If force is true, everything will be invalidated, no matter how wasteful it is, but if force is false, in actuality files will only be invalidated if their modification times have been changed since they were first opened.
virtual void OpenImageIO::ImageCache::release_tile | ( | Tile * | tile | ) | const [pure virtual] |
After finishing with a tile, release_tile will allow it to once again be purged from the tile cache if required.
virtual std::string OpenImageIO::ImageCache::resolve_filename | ( | const std::string & | filename | ) | const [pure virtual] |
Given possibly-relative 'filename', resolve it using the search path rules and return the full resolved filename.
virtual const void* OpenImageIO::ImageCache::tile_pixels | ( | Tile * | tile, | |
TypeDesc & | format | |||
) | const [pure virtual] |
For a tile retrived by get_tile(), return a pointer to the pixel data itself, and also store in 'format' the data type that the pixels are internally stored in (which may be different than the data type of the pixels in the disk file).