Support Forum G3D Web Page |
Provides general image loading, saving, conversion and pixel access. More...
Inherits G3D::ReferenceCountedObject.
Classes | |
class | Error |
Public Types | |
enum | ImageFileFormat { UNKNOWN = -1, BMP = 0, ICO = 1, JPEG = 2, JNG = 3, KOALA = 4, LBM = 5, IFF = LBM, MNG = 6, PBM = 7, PBMRAW = 8, PCD = 9, PCX = 10, PGM = 11, PGMRAW = 12, PNG = 13, PPM = 14, PPMRAW = 15, RAS = 16, TARGA = 17, TIFF = 18, WBMP = 19, PSD = 20, CUT = 21, XBM = 22, XPM = 23, DDS = 24, GIF = 25, HDR = 26, FAXG3 = 27, SGI = 28, EXR = 29, J2K = 30, JP2 = 31, PFM = 32, PICT = 33, RAW = 34 } |
Public Member Functions | |
virtual | ~Image () |
Color4 | bicubic (float x, float y, WrapMode w=WrapMode::ERROR) const |
Color4 | bicubic (const Point2 &pos, WrapMode w=WrapMode::ERROR) const |
Color4 | bilinear (float x, float y, WrapMode wrap=WrapMode::ERROR) const |
Bilinear interpolation, in the style of OpenGL's GL_LINEAR . More... | |
Color4 | bilinear (const Point2 &pos, WrapMode wrap=WrapMode::ERROR) const |
Bilinear interpolation, in the style of OpenGL's GL_LINEAR . More... | |
Color4 | bilinearGamma (float x, float y, float gamma, WrapMode wrap=WrapMode::ERROR) const |
Bilinear interpolation, with gamma applied to RGB channels. More... | |
template<class ColorN > | |
void | bilinearIncrement (const Point2 &pos, const ColorN &color, WrapMode wrap=WrapMode::IGNORE) |
Increments values within the bilinear footprint according to their weights. More... | |
Rect2D | bounds () const |
shared_ptr< Image > | clone () const |
Copies the underlying pixel data. More... | |
void | convert (const ImageFormat *dstFmt) |
Convert the internal representation to the specified format using G3D::ImageConvert. More... | |
bool | convertToL8 () |
Direct replacements for old GImage functions for now. More... | |
bool | convertToR8 () |
bool | convertToRGB8 () |
bool | convertToRGBA8 () |
void | flipHorizontal () |
void | flipVertical () |
template<typename ColorType > | |
void | forEachPixel (std::function< ColorType(const ColorType &src, Point2int32 coord)> callback, bool multiThread=false) |
Executes for each pixel at coord of this, where src is the value before callback runs and the result is set to the return value of the callback. More... | |
template<typename ColorType > | |
void | forEachPixel (std::function< ColorType(const ColorType &src)> callback, bool multiThread=false) |
template<typename ColorType > | |
void | forEachPixel (std::function< ColorType(ColorType src)> callback, bool multiThread=false) |
template<typename ColorType > | |
void | forEachPixel (std::function< void(ColorType src)> callback, bool multiThread=false) const |
template<typename ColorType > | |
void | forEachPixel (std::function< ColorType(Point2int32 coord)> callback, bool multiThread=false) |
const ImageFormat * | format () const |
void | get (const Point2int32 &pos, Color4 &color) const |
8-bit and 16-bit values are returned on the range [0, 1] losslessly. More... | |
void | get (const Point2int32 &pos, Color3 &color) const |
void | get (const Point2int32 &pos, Color1 &color) const |
void | get (const Point2int32 &pos, Color4unorm8 &color) const |
void | get (const Point2int32 &pos, Color3unorm8 &color) const |
void | get (const Point2int32 &pos, Color1unorm8 &color) const |
template<class ValueType > | |
ValueType | get (Point2int32 pos, WrapMode wrap=WrapMode::ERROR) const |
Provides functional access with wrap modes. More... | |
template<class ValueType > | |
ValueType | get (int x, int y, WrapMode w=WrapMode::ERROR) const |
Helper function for convenient functional access to elements and wrap modes. More... | |
int | height () const |
Height in pixels. More... | |
template<class ColorN > | |
void | increment (const Point2int32 &pos, const ColorN &color) |
template<class ColorN > | |
void | increment (const Point2int32 &pos, const ColorN &color, WrapMode wrapMode) |
Color4 | nearest (const Point2 &pos, WrapMode w=WrapMode::ERROR) const |
Returns the nearest neighbor's pixel value, as in OpenGL's GL_NEAREST texture filter mode. More... | |
Color4 | nearest (int x, int y, WrapMode w=WrapMode::ERROR) const |
Returns the nearest neighbor's pixel value, as in OpenGL's GL_NEAREST texture filter mode. More... | |
void | rotateCCW (double radians) |
void | rotateCW (double radians) |
void | save (const String &filename) const |
Saves internal pixel data to file specified by filename. More... | |
void | serialize (BinaryOutput &bo, ImageFileFormat fileFormat) const |
Saves internal pixel data to existing BinaryOutput bo. More... | |
void | set (const shared_ptr< PixelTransferBuffer > &buffer) |
Copies all elements from buffer, adjusting the size and format of this to match. More... | |
void | set (const shared_ptr< PixelTransferBuffer > &buffer, int x, int y) |
Copies only pixels from buffer to the specified location in the image. More... | |
void | set (const Point2int32 &pos, const Color4 &color) |
void | set (const Point2int32 &pos, const Color3 &color) |
void | set (const Point2int32 &pos, const Color1 &color) |
void | set (const Point2int32 &pos, const Color4unorm8 &color) |
void | set (const Point2int32 &pos, const Color3unorm8 &color) |
void | set (const Point2int32 &pos, const Color1unorm8 &color) |
template<class ValueType > | |
void | set (Point2int32 pos, const ValueType &v, WrapMode wrap) |
Slower than the other set methods. More... | |
template<class ValueType > | |
void | set (int x, int y, const ValueType &v, WrapMode wrap=WrapMode::ERROR) |
void | setAll (const Color4 &color) |
void | setAll (const Color3 &color) |
void | setAll (const Color1 &color) |
void | setAll (const Color4unorm8 &color) |
void | setAll (const Color3unorm8 &color) |
void | setAll (const Color1unorm8 &color) |
void | setSize (int w, int h, const ImageFormat *fmt=ImageFormat::AUTO()) |
The contents are undefined after resize. More... | |
shared_ptr< PixelTransferBuffer > | toPixelTransferBuffer () const |
Extracts a copy of the pixel data. More... | |
shared_ptr< PixelTransferBuffer > | toPixelTransferBuffer (Rect2D rect, shared_ptr< PixelTransferBuffer > ptb=nullptr) const |
Extracts a copy of the pixel data within the specified rectangle. More... | |
int | width () const |
Width in pixels. More... | |
Static Public Member Functions | |
static shared_ptr< PixelTransferBuffer > | arrayToPixelTransferBuffer (const Array< shared_ptr< Image > > &images) |
Takes in an Array of Images and loades them all into a single CPUPixelTransferBuffer. More... | |
static shared_ptr< Image > | create (int width, int height, const ImageFormat *imageFormat) |
static bool | fileSupported (const String &filename, bool allowCheckSignature=false) |
Determines if the format of a file is supported. More... | |
static shared_ptr< Image > | fromBinaryInput (BinaryInput &bi, const ImageFormat *imageFormat=ImageFormat::AUTO()) |
Loads an image from existing BinaryInput bi. More... | |
static shared_ptr< Image > | fromFile (const String &filename, const ImageFormat *imageFormat=ImageFormat::AUTO()) |
Loads an image from file specified by filename. More... | |
static shared_ptr< Image > | fromPixelTransferBuffer (const shared_ptr< PixelTransferBuffer > &buffer) |
Loads an image from existing PixelTransferBuffer buffer. More... | |
static bool | metaDataFromBinaryInput (BinaryInput &bi, int &width, int &height, const ImageFormat *&format) |
Reads just metadata (if the file format supports it, undefined otherwise). More... | |
static void | saveGIF (const String &filename, const Array< shared_ptr< Image >> &sequence, const double &fps) |
Saves GIF of a sequence of images to file specified by filename/ The save is not lossy if the images are RGB8 format and have a palette size of at most 256 colros. More... | |
Protected Member Functions | |
Image () | |
Image (const Image &) | |
Image & | operator= (const Image &) |
float | R (float x) const |
Static Protected Member Functions | |
template<class T , class ... ArgTypes> | |
static shared_ptr< T > | createShared (ArgTypes &&... args) |
Like std::make_shared, but works for protected constructors. More... | |
static void | initFreeImage () |
Initialize the FreeImage library on first use. More... | |
Protected Attributes | |
const ImageFormat * | m_format |
fipImage * | m_image |
Static Protected Attributes | |
static std::mutex | s_freeImageMutex |
Ensures that FreeImage is not initialized on multiple threads simultaneously. More... | |
Friends | |
class | CubeMap |
Provides general image loading, saving, conversion and pixel access.
Image allows you to load a variety of supported file formats in their native pixel format with very few exceptions. Callers are responsible for converting pixel data to the desired format after loading and before saving.
Image will also try to save directly to a file in the same pixel format as it is stored internally. If a file format does not support that pixel format, then the caller is responsible for converting before saving.
The Image::Error exception is thrown if a file cannot be loaded.
|
protected |
|
protected |
|
virtual |
|
static |
Takes in an Array of Images and loades them all into a single CPUPixelTransferBuffer.
This is meant to be used for creating 2D_Texture Arrays.
Color4 G3D::Image::bicubic | ( | float | x, |
float | y, | ||
WrapMode | w = WrapMode::ERROR |
||
) | const |
Color4 G3D::Image::bicubic | ( | const Point2 & | pos, |
WrapMode | w = WrapMode::ERROR |
||
) | const |
Color4 G3D::Image::bilinear | ( | float | x, |
float | y, | ||
WrapMode | wrap = WrapMode::ERROR |
||
) | const |
Bilinear interpolation, in the style of OpenGL's GL_LINEAR
.
Needs to access elements from (floor(x), floor(y))
to (floor(x) + 1, floor(y) + 1)
and will use the wrap mode appropriately, possibly generating out of bounds errors.
Guaranteed to match nearest(x, y)
at integer locations. That is, pixel centers are at integers.
Color4 G3D::Image::bilinear | ( | const Point2 & | pos, |
WrapMode | wrap = WrapMode::ERROR |
||
) | const |
Bilinear interpolation, in the style of OpenGL's GL_LINEAR
.
Needs to access elements from (floor(x), floor(y))
to (floor(x) + 1, floor(y) + 1)
and will use the wrap mode appropriately, possibly generating out of bounds errors.
Guaranteed to match nearest(x, y)
at integer locations. That is, pixel centers are at integers.
Color4 G3D::Image::bilinearGamma | ( | float | x, |
float | y, | ||
float | gamma, | ||
WrapMode | wrap = WrapMode::ERROR |
||
) | const |
Bilinear interpolation, with gamma applied to RGB channels.
|
inline |
Increments values within the bilinear footprint according to their weights.
Needs to access elements from (floor(x), floor(y))
to (floor(x) + 1, floor(y) + 1)
and will use the wrap mode appropriately, possibly generating out of bounds errors.
wrap | Defaults to WrapMode::IGNORE |
|
inline |
shared_ptr<Image> G3D::Image::clone | ( | ) | const |
Copies the underlying pixel data.
void G3D::Image::convert | ( | const ImageFormat * | dstFmt | ) |
Convert the internal representation to the specified format using G3D::ImageConvert.
bool G3D::Image::convertToL8 | ( | ) |
Direct replacements for old GImage functions for now.
bool G3D::Image::convertToR8 | ( | ) |
bool G3D::Image::convertToRGB8 | ( | ) |
bool G3D::Image::convertToRGBA8 | ( | ) |
|
static |
|
inlinestaticprotectedinherited |
Like std::make_shared, but works for protected constructors.
Call as createShared<myclass>.
|
static |
Determines if the format of a file is supported.
Does not open file unless allowCheckSignature is true.
Does not check if the pixel format is supported.
void G3D::Image::flipHorizontal | ( | ) |
void G3D::Image::flipVertical | ( | ) |
|
inline |
Executes for each pixel at coord of this, where src is the value before callback runs and the result is set to the return value of the callback.
If multiThread is true (the default in release mode) then multiple CPU threads may be used.
Note that there are overloads that accept just a coordinate or just a source color.
Examples:
|
inline |
|
inline |
|
inline |
|
inline |
const ImageFormat* G3D::Image::format | ( | ) | const |
|
static |
Loads an image from existing BinaryInput bi.
|
static |
Loads an image from file specified by filename.
imageFormat | If specified and bit-compatible (ImageFormat::canInterpretAs()) with the image's original file format, reinterprets the data in the new format (i.e., as if with a C++ reinterpret_cast). For example, RGB8 data could be reinterpreted as SRGB8, RGB8I, RGB8UI, BGR8, etc. |
Referenced by G3D::OSWindow::setIcon().
|
static |
Loads an image from existing PixelTransferBuffer buffer.
Performs a copy of pixel data.
void G3D::Image::get | ( | const Point2int32 & | pos, |
Color4 & | color | ||
) | const |
8-bit and 16-bit values are returned on the range [0, 1] losslessly.
32-bit float values are mapped with some precision loss. float32 values are unmodified.
void G3D::Image::get | ( | const Point2int32 & | pos, |
Color3 & | color | ||
) | const |
void G3D::Image::get | ( | const Point2int32 & | pos, |
Color1 & | color | ||
) | const |
void G3D::Image::get | ( | const Point2int32 & | pos, |
Color4unorm8 & | color | ||
) | const |
void G3D::Image::get | ( | const Point2int32 & | pos, |
Color3unorm8 & | color | ||
) | const |
void G3D::Image::get | ( | const Point2int32 & | pos, |
Color1unorm8 & | color | ||
) | const |
|
inline |
Provides functional access with wrap modes.
This is slower than the other get() methods.
|
inline |
int G3D::Image::height | ( | ) | const |
Height in pixels.
Referenced by bounds(), forEachPixel(), get(), and set().
|
inline |
|
inline |
|
staticprotected |
Initialize the FreeImage library on first use.
|
static |
Reads just metadata (if the file format supports it, undefined otherwise).
Returns true on success, false on failure
Color4 G3D::Image::nearest | ( | const Point2 & | pos, |
WrapMode | w = WrapMode::ERROR |
||
) | const |
Returns the nearest neighbor's pixel value, as in OpenGL's GL_NEAREST texture filter mode.
Values are considered to be at pixel centers, so image->nearest(x, y) == image->get<Color4>(iFloor(x), iFloor(y))
.
Note that this method uses pixel addressing, not texel addressing, so the lower-right edge of the image is at (width(), height()), not (1, 1)
Color4 G3D::Image::nearest | ( | int | x, |
int | y, | ||
WrapMode | w = WrapMode::ERROR |
||
) | const |
Returns the nearest neighbor's pixel value, as in OpenGL's GL_NEAREST texture filter mode.
Values are considered to be at pixel centers, so image->nearest(x, y) == image->get<Color4>(iFloor(x), iFloor(y))
.
Note that this method uses pixel addressing, not texel addressing, so the lower-right edge of the image is at (width(), height()), not (1, 1)
|
inlineprotected |
void G3D::Image::rotateCCW | ( | double | radians | ) |
void G3D::Image::rotateCW | ( | double | radians | ) |
void G3D::Image::save | ( | const String & | filename | ) | const |
Saves internal pixel data to file specified by filename.
Does not convert pixel format before saving. Throws string exception if failure.
|
static |
Saves GIF of a sequence of images to file specified by filename/ The save is not lossy if the images are RGB8 format and have a palette size of at most 256 colros.
All images must have same width and height as specified by first image in sequence. Fails silently if empty sequence or 0 framerate. Throws string exception if failure.
void G3D::Image::serialize | ( | BinaryOutput & | bo, |
ImageFileFormat | fileFormat | ||
) | const |
Saves internal pixel data to existing BinaryOutput bo.
Does not convert pixel format before saving.
void G3D::Image::set | ( | const shared_ptr< PixelTransferBuffer > & | buffer | ) |
Copies all elements from buffer, adjusting the size and format of this to match.
void G3D::Image::set | ( | const shared_ptr< PixelTransferBuffer > & | buffer, |
int | x, | ||
int | y | ||
) |
Copies only pixels from buffer to the specified location in the image.
Does not adjust the size nor format of this to match
void G3D::Image::set | ( | const Point2int32 & | pos, |
const Color4 & | color | ||
) |
void G3D::Image::set | ( | const Point2int32 & | pos, |
const Color3 & | color | ||
) |
void G3D::Image::set | ( | const Point2int32 & | pos, |
const Color1 & | color | ||
) |
void G3D::Image::set | ( | const Point2int32 & | pos, |
const Color4unorm8 & | color | ||
) |
void G3D::Image::set | ( | const Point2int32 & | pos, |
const Color3unorm8 & | color | ||
) |
void G3D::Image::set | ( | const Point2int32 & | pos, |
const Color1unorm8 & | color | ||
) |
|
inline |
Slower than the other set methods.
|
inline |
void G3D::Image::setAll | ( | const Color4 & | color | ) |
void G3D::Image::setAll | ( | const Color3 & | color | ) |
void G3D::Image::setAll | ( | const Color1 & | color | ) |
void G3D::Image::setAll | ( | const Color4unorm8 & | color | ) |
void G3D::Image::setAll | ( | const Color3unorm8 & | color | ) |
void G3D::Image::setAll | ( | const Color1unorm8 & | color | ) |
void G3D::Image::setSize | ( | int | w, |
int | h, | ||
const ImageFormat * | fmt = ImageFormat::AUTO() |
||
) |
The contents are undefined after resize.
Does not resize if the width, height, and format are unchanged.
fmt | If ImageFormat::AUTO(), then the current format is retained |
shared_ptr<PixelTransferBuffer> G3D::Image::toPixelTransferBuffer | ( | ) | const |
Extracts a copy of the pixel data.
shared_ptr<PixelTransferBuffer> G3D::Image::toPixelTransferBuffer | ( | Rect2D | rect, |
shared_ptr< PixelTransferBuffer > | ptb = nullptr |
||
) | const |
Extracts a copy of the pixel data within the specified rectangle.
ptb | If non-null, must have the matching size and format. |
int G3D::Image::width | ( | ) | const |
Width in pixels.
Referenced by bounds(), forEachPixel(), get(), and set().
|
friend |
|
protected |
|
protected |
|
staticprotected |
Ensures that FreeImage is not initialized on multiple threads simultaneously.