Face Engine SDK  5.14.0
A face detection, recognition and tracking engine.
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
fsdk::Image Struct Reference

Image. More...

#include <Image.h>

Public Types

enum  Type : uint8_t {
  BMP, JPG, PNG, PPM,
  TIFF, Unknown
}
 Supported image types.
 
enum  TargetDevice { CPU, GPU, NPU }
 Target device that fsdk::Image algorithms will be running on.
 
enum  ImageCompression {
  ImageCompression::IC_NO_COMPRESSION, ImageCompression::IC_SMALL_COMPRESSION, ImageCompression::IC_MEDIUM_COMPRESSION, ImageCompression::IC_HARD_COMPRESSION,
  ImageCompression::IC_BEST_COMPRESSION
}
 Supported compression type is used only for jpg and png types. More...
 
enum  Error : uint32_t {
  Error::Ok, Error::InvalidWidth, Error::InvalidHeight, Error::InvalidDataPtr,
  Error::InvalidDataSize, Error::InvalidImage, Error::InvalidArchive, Error::InvalidPath,
  Error::InvalidType, Error::InvalidFormat, Error::InvalidBitmap, Error::InvalidMemory,
  Error::InvalidConversion, Error::InvalidResidence, Error::InvalidDevice, Error::InvalidCudaKernel,
  Error::FailedToSave, Error::FailedToLoad, Error::FailedToInitialize, Error::ReleasedInOtherThread
}
 Image error codes. More...
 
enum  MemoryResidence : uint32_t { MemoryResidence::MemoryCPU, MemoryResidence::MemoryGPU, MemoryResidence::MemoryNPU, MemoryResidence::MemoryNPU_DPP }
 Memory residence. More...
 

Public Member Functions

FSDK_API Image () noexcept
 Initializes an empty image.
 
FSDK_API Image (int width, int height, Format format, MemoryResidence residence=MemoryResidence::MemoryCPU, int deviceId=0) noexcept
 Initializes an empty image and preallocates storage buffer of given size. More...
 
FSDK_API Image (int width, int height, Format format, const void *data, MemoryResidence residence=MemoryResidence::MemoryCPU, int deviceId=0) noexcept
 Initializes an empty image and preallocates storage buffer of given size. Fills image contents with provided data. More...
 
FSDK_API Image (int width, int height, Format format, void *data, bool copy, MemoryResidence residence=MemoryResidence::MemoryCPU, int deviceId=0) noexcept
 Initializes an image. If copy is true, this allocates a new buffer of given size and fills image contents with provided data (copies it). If copy is false (which is default) this will just reference the provided data. More...
 
FSDK_API Image (const Image &other) noexcept
 Initializes an image as a reference to an other image. More...
 
FSDK_API Image (Image &&other) noexcept
 Initializes an image with contents of an other image. Source image is then invalidated. More...
 
FSDK_API Image (const SubImage &subImage) noexcept
 Initializes an image with contents of a sub image. Since sub images do not handle data life time, image contents are always copied. More...
 
FSDK_API Result< Errorcreate (int width, int height, Format format, bool cleanup=true, MemoryResidence residence=MemoryResidence::MemoryCPU, int deviceId=0) noexcept
 Initializes an empty image and preallocates storage buffer of given size. More...
 
FSDK_API Result< Errorcreate (int width, int height, Format format, const void *data, MemoryResidence residence=MemoryResidence::MemoryCPU, int deviceId=0) noexcept
 Initializes an empty image and preallocates storage buffer of given size. Fills image contents with provided data. More...
 
FSDK_API Result< Errorcreate (int width, int height, Format format, void *data, bool copy, MemoryResidence residence=MemoryResidence::MemoryCPU, int deviceId=0) noexcept
 Initializes an image. If copy is true, this allocates a new buffer of given size and fills image contents with provided data (copies it). If copy is false (which is default) this will just reference the provided data. More...
 
FSDK_API Result< Errorcreate (const fsdk::Image &source, MemoryResidence residence, int deviceId=0) noexcept
 Creates image with given memory residence based on other image instance. If source image has another MemoryResidence or device id, all memory will be copied to the new residence. In the other case new instance will be just a reference for the source. More...
 
FSDK_API Result< Errorset (int width, int height, Format format, const void *data, MemoryResidence residence=MemoryResidence::MemoryCPU, int deviceId=0) noexcept
 Initializes an image with provided data. If current image is not empty and it's size and format match the provided ones, no memory reallocation is performed. Otherwise image is re-created to match requirements. More...
 
FSDK_API Result< Errorset (int width, int height, Format format, void *data, bool copy, MemoryResidence residence=MemoryResidence::MemoryCPU, int deviceId=0) noexcept
 Initializes an image with provided data. If copy is true and if current image is not empty and it's size and format match the provided ones, no memory reallocation is performed. Otherwise image is re-created to match requirements. If copy is false (which is default) this will just reference the provided data. More...
 
FSDK_API Result< Errorset (const Image &other) noexcept
 Initializes an image as a reference to an other image. More...
 
FSDK_API Result< Errorset (const SubImage &subImage) noexcept
 Initializes an image with contents of a sub image. Since sub images do not handle data life time, image contents are always copied. More...
 
FSDK_API SubImage map (int x, int y, int width, int height) const noexcept
 Map image contents to a given area. More...
 
SubImage map (const Rect &rect) const noexcept
 Map image contents to a given area. More...
 
SubImage map (const Size &size) const noexcept
 Map image contents to a given area. More...
 
SubImage map (const Point2i &origin, const Size &size) const noexcept
 Map image contents to a given area. More...
 
FSDK_API Image extract (int x, int y, int width, int height) const noexcept
 Extract a sub image of this image. The new image will have it's own reference count. More...
 
Image extract (const Rect &rect) const noexcept
 Extract a sub image of this image. The new image will have it's own reference count. More...
 
Image extract (const Size &size) const noexcept
 Extract a sub image of this image. The new image will have it's own reference count. More...
 
Image extract (const Point2i &origin, const Size &size) const noexcept
 Extract a sub image of this image. The new image will have it's own reference count. More...
 
Image clone () const noexcept
 Create a copy of this image. The new image will have it's own reference count. More...
 
FSDK_API Result< Image::Errorconvert (Image &dest, int x, int y, int width, int height, Format format, TargetDevice device=TargetDevice::CPU) const noexcept
 Convert image format. More...
 
Result< Image::Errorconvert (Image &dest, const Point2i &origin, const Size &size, Format format, TargetDevice device=TargetDevice::CPU) const noexcept
 Convert image format. More...
 
Result< Image::Errorconvert (Image &dest, const Size &size, Format format, TargetDevice device=TargetDevice::CPU) const noexcept
 Convert image format. More...
 
Result< Image::Errorconvert (Image &dest, const Rect &rect, Format format, TargetDevice device=TargetDevice::CPU) const noexcept
 Convert image format. More...
 
Result< Image::Errorconvert (Image &dest, Format format, TargetDevice device=TargetDevice::CPU) const noexcept
 Convert image format. More...
 
FSDK_API Image rescale (float scale) const noexcept
 Rescale image keeping proportions. More...
 
FSDK_API Result< Image::Errorsave (const char *path, fsdk::Image::ImageCompression additionalFlag=fsdk::Image::ImageCompression::IC_NO_COMPRESSION) const noexcept
 Save image. More...
 
FSDK_API Result< Errorsave (const char *path, const Format format) const noexcept
 Convert and Save image. More...
 
FSDK_API Result< Image::ErrorsaveToMemory (Image::Type type, IArchive *archive, fsdk::Image::ImageCompression additionalFlag=fsdk::Image::ImageCompression::IC_NO_COMPRESSION) const noexcept
 Save image to memory buffer. More...
 
FSDK_API Result< Image::ErrorsaveToMemory (Image::Type type, IArchive *archive, const Format format) const noexcept
 Convert and save image to memory buffer. More...
 
FSDK_API Result< Errorload (const char *path) noexcept
 Load image from file. More...
 
FSDK_API Result< Errorload (const char *path, const Format format) noexcept
 Load image from file and convert it to required format. More...
 
FSDK_API Result< ErrorloadFromMemory (const void *data, const uint32_t sizeInBytes) noexcept
 Load image from memory. More...
 
FSDK_API Result< Errorrotate (Image &dest, RotationType rotationType) const noexcept
 Rotates an image on 90, 180 and 270 degrees. Allocates a new buffer of given size and fills image contents with provided data. More...
 
FSDK_API Result< ErrorloadFromMemory (const void *data, const uint32_t sizeInBytes, const Format format) noexcept
 Load image from memory and convert it to required format. More...
 
FSDK_API Result< ErrorloadFromMemoryOfType (const void *data, const uint32_t sizeInBytes, const Type type) noexcept
 Load image from memory of specific type. More...
 
FSDK_API Result< ErrorloadFromMemoryOfType (const void *data, const uint32_t sizeInBytes, const Type type, const Format format) noexcept
 Load image from memory of specific type and convert it to required format. More...
 
Imageoperator= (const Image &other) noexcept
 Assign other image. More...
 
Imageoperator= (Image &&other) noexcept
 Move other image. More...
 
bool isNull () const noexcept
 
bool isValid () const noexcept
 
 operator bool () const noexcept
 Implicit cast to boolean; results in true if image is valid, false if not. More...
 
FSDK_API void * getScanLine (int y) noexcept
 Get image scanline data. More...
 
FSDK_API const void * getScanLine (int y) const noexcept
 Get image scanline data. More...
 
FSDK_API int getDataSize () const noexcept
 
FSDK_API void getDataSize (Sizer &sizer) const noexcept
 Get actual image size in bytes. More...
 
template<typename T >
T * getScanLineAs (int y) noexcept
 Get image scanline data. More...
 
template<typename T >
const T * getScanLineAs (int y) const noexcept
 Get image scanline data. More...
 
void * getData () noexcept
 
const void * getData () const noexcept
 
template<typename T >
T * getDataAs () noexcept
 
template<typename T >
const T * getDataAs () const noexcept
 
int getRowSize () const noexcept
 
int getWidth () const noexcept
 
int getHeight () const noexcept
 
float getAspectRatio () const noexcept
 
Format getFormat () const noexcept
 
MemoryResidence getMemoryResidence () const noexcept
 
int getDeviceId () const noexcept
 
Size getSize () const noexcept
 
Rect getRect () const noexcept
 
bool ownsData () const noexcept
 
bool isSharedWith (const Image &other) const noexcept
 
void swap (Image &other) noexcept
 Swap contents with another image. More...
 
void reset () noexcept
 Reset image contents.
 
bool equalWeak (const fsdk::Image &other) const noexcept
 Performs weak comparison of this image with other. Weak in this context means only image parameters should be equal i.e width, height, format and residence. Actual data pointer of two images might differ.
 
bool equalStrong (const fsdk::Image &other) const noexcept
 Performs strong comparison of this image with other. Beside weak comparison strong comparison also checks whether two images point to the same block of pixels. More...
 
FSDK_API void putPixel (uint32_t x, uint32_t y) noexcept
 

Static Public Member Functions

static FSDK_API Result< ErrorguessTypeFromMemory (const void *data, const uint32_t sizeInBytes, Type &type) noexcept
 Guess type of image written into memory. More...
 

Protected Member Functions

FSDK_API int retain () noexcept
 Increase reference count. More...
 
FSDK_API int release () noexcept
 Decrease reference count. More...
 
FSDK_API int getRefCount () const noexcept
 Obtain reference count. More...
 

Static Protected Member Functions

static FSDK_API void * allocate (int size) noexcept
 Allocate memory. More...
 
static FSDK_API void deallocate (void *memory) noexcept
 Free memory. More...
 

Protected Attributes

void * m_data
 raw image data.
 
int * m_ref
 reference counter. nullptr if image does not own data.
 
int m_height
 image height.
 
int m_width
 image width.
 
int m_deviceId
 id of the device where image memory is allocated
 
Format m_format
 image format ( More...
 
MemoryResidence m_residence
 

Detailed Description

Image.

Image objects embed an implicit reference counter to automatically track consumers perform assignments without unnecessary reallocations in a thread-safe manner.

Every time you assign or set an other image as the source of the current image, the current image data reference count is decreased, new data pointer is referenced, and it's counter is increased. When data reference count drops to zero, the data is deallocated.

Image can also reference external data without an actual ownership. This way you can operate on your data buffer using methods of Image and still own it and cotrol it's life time.

Note
be careful when initializing Image via set() or create() and do NOT provide pointer to data owned by an other image, since this way the destination image will be unaware of data reference counter which will lead to undefined behavior. Always use appropriate overloads to set image data.

Member Enumeration Documentation

enum fsdk::Image::Error : uint32_t
strong

Image error codes.

Enumerator
Ok 

Ok.

InvalidWidth 

Invalid width.

InvalidHeight 

Invalid height.

InvalidDataPtr 

Bad input data pointer.

InvalidDataSize 

Bad input data size.

InvalidImage 

Invalid image.

InvalidArchive 

Archive error.

InvalidPath 

Bad path for saving / loading.

InvalidType 

Unsupported type.

See Also
Image::Type for more information.
InvalidFormat 

Unsupported format.

See Also
Image::Format for more information.
InvalidBitmap 

Bitmap error occurred.

InvalidMemory 

Error at memory opening.

InvalidConversion 

Conversion not implemented.

InvalidResidence 

Invalid memory residence.

InvalidDevice 

Target Device is not supported for this system.

InvalidCudaKernel 

Error during apply cuda kernel.

FailedToSave 

Error during image saving.

FailedToLoad 

Error during image loading.

FailedToInitialize 

Error during initialization.

ReleasedInOtherThread 

Failed to retain image: it was released in another thread.

Supported compression type is used only for jpg and png types.

JPG case: the higher level of compression corresponds to the lower quality. Compression/decompression speed are constant. PNG case: the higher level of compression corresponds to the lower compression speed. Quality are constant.

Enumerator
IC_NO_COMPRESSION 

no compression (only for png or jpg image)

IC_SMALL_COMPRESSION 

compression with minimal (or without) quality loss (only for png or jpg image)

IC_MEDIUM_COMPRESSION 

medium compression (only for png or jpg)

IC_HARD_COMPRESSION 

more than medium compression (only for png or jpg)

IC_BEST_COMPRESSION 

maximum compression level (only for png or jpg)

enum fsdk::Image::MemoryResidence : uint32_t
strong

Memory residence.

Note
MemoryGPU residence is not supported for mobile platforms! Attempt to use such image on such platforms will cause an error.
Enumerator
MemoryCPU 

Image in Host device memory.

MemoryGPU 

Image in Cuda device memory.

MemoryNPU 

Image in NPU device memory.

MemoryNPU_DPP 

Image in NPU PreProcessing module memory.

Constructor & Destructor Documentation

FSDK_API fsdk::Image::Image ( int  width,
int  height,
Format  format,
MemoryResidence  residence = MemoryResidence::MemoryCPU,
int  deviceId = 0 
)
noexcept

Initializes an empty image and preallocates storage buffer of given size.

Parameters
[in]widthimage width.
[in]heightimage height.
[in]formatimage format.
[in]deviceIdindex of a device where image will be allocated
Note
deviceId is ignored for residence = MemoryResidence::MemoryCPU
if memory allocation fails, no exception is thrown; function call results in empty image.
FSDK_API fsdk::Image::Image ( int  width,
int  height,
Format  format,
const void *  data,
MemoryResidence  residence = MemoryResidence::MemoryCPU,
int  deviceId = 0 
)
noexcept

Initializes an empty image and preallocates storage buffer of given size. Fills image contents with provided data.

Parameters
[in]widthimage width.
[in]heightimage height.
[in]formatimage format.
[in]dataimage data.
[in]deviceIdindex of a device where image will be allocated
Note
deviceId is ignored for residence = MemoryResidence::MemoryCPU
if memory allocation fails, no exception is thrown; function call results in empty image.
FSDK_API fsdk::Image::Image ( int  width,
int  height,
Format  format,
void *  data,
bool  copy,
MemoryResidence  residence = MemoryResidence::MemoryCPU,
int  deviceId = 0 
)
noexcept

Initializes an image. If copy is true, this allocates a new buffer of given size and fills image contents with provided data (copies it). If copy is false (which is default) this will just reference the provided data.

Parameters
[in]widthimage width.
[in]heightimage height.
[in]formatimage format.
[in]dataimage data.
[in]copy[optional] whether to copy or reference data.
[in]deviceIdindex of a device where image will be allocated
Note
deviceId is ignored for residence = MemoryResidence::MemoryCPU
if memory allocation fails, no exception is thrown; function call results in empty image.
FSDK_API fsdk::Image::Image ( const Image other)
noexcept

Initializes an image as a reference to an other image.

Parameters
[in]otherother image.
FSDK_API fsdk::Image::Image ( Image &&  other)
noexcept

Initializes an image with contents of an other image. Source image is then invalidated.

Parameters
[in]otherother image.
FSDK_API fsdk::Image::Image ( const SubImage subImage)
explicitnoexcept

Initializes an image with contents of a sub image. Since sub images do not handle data life time, image contents are always copied.

Parameters
[in]subImagesub image.

Member Function Documentation

static FSDK_API void* fsdk::Image::allocate ( int  size)
staticprotectednoexcept

Allocate memory.

Parameters
[in]sizememory region size in bytes.
Returns
Memory region pointer.
Image fsdk::Image::clone ( ) const
inlinenoexcept

Create a copy of this image. The new image will have it's own reference count.

Returns
new image with copied data.
Note
empty image returned in case of an error.
FSDK_API Result<Image::Error> fsdk::Image::convert ( Image dest,
int  x,
int  y,
int  width,
int  height,
Format  format,
TargetDevice  device = TargetDevice::CPU 
) const
noexcept

Convert image format.

Note
specifying out of bounds area will result in runtime error.
Parameters
[in,out]destdestination image.
[in]xhorisontal coordinate of top left corner of image rect to convert.
[in]yvertical coordinate of top left corner of image rect to convert.
[in]widthwidth of image rect to convert.
[in]heightheight of image rect to convert.
[in]formatnew format.
[in]devicetarget device to run convert on.
Note
dest should not be the same as this image.
memory will not be reallocated if dest was already created with appropriate dimensions and format.
Returns
Result with error code specified by Image::Error.
See Also
Result and Image::Error.
Result<Image::Error> fsdk::Image::convert ( Image dest,
const Point2i origin,
const Size size,
Format  format,
TargetDevice  device = TargetDevice::CPU 
) const
inlinenoexcept

Convert image format.

Note
specifying out of bounds area will result in runtime error.
Parameters
[in,out]destdestination image.
[in]originconverted image origin.
[in]sizeimage size to convert.
[in]formatnew format.
[in]devicetarget device to run convert on.
Note
dest should not be the same as this image.
memory will not be reallocated if dest was already created with appropriate dimensions and format.
Returns
Result with error code specified by Image::Error.
See Also
Result and Image::Error.
Result<Image::Error> fsdk::Image::convert ( Image dest,
const Size size,
Format  format,
TargetDevice  device = TargetDevice::CPU 
) const
inlinenoexcept

Convert image format.

Note
specifying out of bounds area will result in runtime error.
new image origin is assumed at the top-left corner of the existing one.
Parameters
[in,out]destdestination image.
[in]formatnew format.
[in]sizeimage area size to convert.
[in]devicetarget device to run convert on.
Note
dest should not be the same as this image.
memory will not be reallocated if dest was already created with appropriate dimensions and format.
Returns
Result with error code specified by Image::Error.
See Also
Result and Image::Error.
Result<Image::Error> fsdk::Image::convert ( Image dest,
const Rect rect,
Format  format,
TargetDevice  device = TargetDevice::CPU 
) const
inlinenoexcept

Convert image format.

Note
specifying out of bounds area will result in runtime error.
Parameters
[in,out]destdestination image.
[in]formatnew format.
[in]rectimage area rect to convert.
[in]devicetarget device to run convert on.
Note
dest should not be the same as this image.
memory will not be reallocated if dest was already created with appropriate dimensions and format.
Returns
Result with error code specified by Image::Error.
See Also
Result and Image::Error.
Result<Image::Error> fsdk::Image::convert ( Image dest,
Format  format,
TargetDevice  device = TargetDevice::CPU 
) const
inlinenoexcept

Convert image format.

Parameters
[in,out]destdestination image.
[in]formatnew format.
[in]devicetarget device to run convert on.
Note
dest should not be the same as this image.
memory will not be reallocated if dest was already created with appropriate dimensions and format.
Returns
Result with error code specified by Image::Error.
See Also
Result and Image::Error.
FSDK_API Result<Error> fsdk::Image::create ( int  width,
int  height,
Format  format,
bool  cleanup = true,
MemoryResidence  residence = MemoryResidence::MemoryCPU,
int  deviceId = 0 
)
noexcept

Initializes an empty image and preallocates storage buffer of given size.

Parameters
[in]widthimage width.
[in]heightimage height.
[in]formatimage format.
[in]cleanupinitializes internal image memory to default value.
[in]residencememory residence of a data pointer.
[in]deviceIdindex of a device where image will be allocated
Note
deviceId is ignored for residence = MemoryResidence::MemoryCPU
output image will have memory residence of the provided data pointer.
if memory allocation fails, no exception is thrown; function call results in empty image.
Returns
true in case of success, false otherwise.
FSDK_API Result<Error> fsdk::Image::create ( int  width,
int  height,
Format  format,
const void *  data,
MemoryResidence  residence = MemoryResidence::MemoryCPU,
int  deviceId = 0 
)
noexcept

Initializes an empty image and preallocates storage buffer of given size. Fills image contents with provided data.

Parameters
[in]widthimage width.
[in]heightimage height.
[in]formatimage format.
[in]dataimage data.
[in]memoryresidence of a data pointer.
[in]deviceIdindex of a device where data pointer was allocated
Note
deviceId is ignored for residence = MemoryResidence::MemoryCPU
output image will have memory residence of the provided data pointer.
if memory allocation fails, no exception is thrown; function call results in empty image.
Returns
true in case of success, false otherwise.
FSDK_API Result<Error> fsdk::Image::create ( int  width,
int  height,
Format  format,
void *  data,
bool  copy,
MemoryResidence  residence = MemoryResidence::MemoryCPU,
int  deviceId = 0 
)
noexcept

Initializes an image. If copy is true, this allocates a new buffer of given size and fills image contents with provided data (copies it). If copy is false (which is default) this will just reference the provided data.

Parameters
[in]widthimage width.
[in]heightimage height.
[in]formatimage format.
[in]dataimage data.
[in]copywhether to copy or reference data
[in]memoryresidence of a data pointer.
[in]deviceIdindex of a device where data pointer was allocated
Note
deviceId is ignored for residence = MemoryResidence::MemoryCPU
output image will have memory residence of the provided data pointer.
if memory allocation fails, no exception is thrown; function call results in empty image.
Returns
true in case of success, false otherwise.
FSDK_API Result<Error> fsdk::Image::create ( const fsdk::Image source,
MemoryResidence  residence,
int  deviceId = 0 
)
noexcept

Creates image with given memory residence based on other image instance. If source image has another MemoryResidence or device id, all memory will be copied to the new residence. In the other case new instance will be just a reference for the source.

Parameters
[in]imageinstance to create copy for
[in]residencememory residence for the target image
[in]deviceIdindex of a device for the target image
Note
deviceId is ignored for residence = MemoryResidence::MemoryCPU
Returns
true in case of success, false otherwise.
static FSDK_API void fsdk::Image::deallocate ( void *  memory)
staticprotectednoexcept

Free memory.

Parameters
[in]memorymemory region pointer.
bool fsdk::Image::equalStrong ( const fsdk::Image other) const
inlinenoexcept

Performs strong comparison of this image with other. Beside weak comparison strong comparison also checks whether two images point to the same block of pixels.

See Also
equalWeak().
FSDK_API Image fsdk::Image::extract ( int  x,
int  y,
int  width,
int  height 
) const
noexcept

Extract a sub image of this image. The new image will have it's own reference count.

Parameters
[in]xhorisontal coordinate of top left corner of image rect to extract.
[in]yvertical coordinate of top left corner of image rect to extract.
[in]widthwidth of image rect to extract.
[in]heightheight of image rect to extract.
Returns
new image with copied data.
Note
empty image returned in case of an memory allocation error.
Memory residence must be MemoryResidence::MemoryCPU.
Image fsdk::Image::extract ( const Rect rect) const
inlinenoexcept

Extract a sub image of this image. The new image will have it's own reference count.

Parameters
[in]rectimage rect to extract.
Returns
new image with copied data.
Note
empty image returned in case of an memory allocation error.
Memory residence must be MemoryResidence::MemoryCPU.
Image fsdk::Image::extract ( const Size size) const
inlinenoexcept

Extract a sub image of this image. The new image will have it's own reference count.

Note
new image origin is assumed at the top-left corner of the existing one.
Parameters
[in]sizeimage size to extract.
Returns
new image with copied data.
Note
empty image returned in case of an memory allocation error.
Memory residence must be MemoryResidence::MemoryCPU.
Image fsdk::Image::extract ( const Point2i origin,
const Size size 
) const
inlinenoexcept

Extract a sub image of this image. The new image will have it's own reference count.

Parameters
[in]originextracted image origin.
[in]sizeimage size to extract.
Returns
new image with copied data.
Note
empty image returned in case of an memory allocation error.
Memory residence must be MemoryResidence::MemoryCPU.
float fsdk::Image::getAspectRatio ( ) const
inlinenoexcept
Returns
image aspect ratio (width to height).
void* fsdk::Image::getData ( )
inlinenoexcept
Returns
pointer to raw image data.
const void* fsdk::Image::getData ( ) const
inlinenoexcept
Returns
pointer to raw image data.
template<typename T >
T* fsdk::Image::getDataAs ( )
inlinenoexcept
Returns
pointer to image data cast to a given type.
template<typename T >
const T* fsdk::Image::getDataAs ( ) const
inlinenoexcept
Returns
pointer to image data cast to a given type.
FSDK_API int fsdk::Image::getDataSize ( ) const
noexcept
Returns
actual image size in bytes.
FSDK_API void fsdk::Image::getDataSize ( Sizer sizer) const
noexcept

Get actual image size in bytes.

Parameters
[in,out]sizersizer to append result to.
Format fsdk::Image::getFormat ( ) const
inlinenoexcept
Returns
image format.
int fsdk::Image::getHeight ( ) const
inlinenoexcept
Returns
image height.
Rect fsdk::Image::getRect ( ) const
inlinenoexcept
Returns
image rectangle.
Note
resulting rectangle top left corner is lways at (0, 0).
FSDK_API int fsdk::Image::getRefCount ( ) const
protectednoexcept

Obtain reference count.

Returns
Current reference count.
int fsdk::Image::getRowSize ( ) const
inlinenoexcept
Returns
size of image pixel row in bytes.
FSDK_API void* fsdk::Image::getScanLine ( int  y)
noexcept

Get image scanline data.

Parameters
[in]yscanline number.
Returns
pointer to raw data.
FSDK_API const void* fsdk::Image::getScanLine ( int  y) const
noexcept

Get image scanline data.

Parameters
[in]yscanline number.
Returns
pointer to raw data.
template<typename T >
T* fsdk::Image::getScanLineAs ( int  y)
inlinenoexcept

Get image scanline data.

Parameters
[in]yscanline number.
Returns
pointer image data cast to a given type.
template<typename T >
const T* fsdk::Image::getScanLineAs ( int  y) const
inlinenoexcept

Get image scanline data.

Parameters
[in]yscanline number.
Returns
pointer image data cast to a given type.
Size fsdk::Image::getSize ( ) const
inlinenoexcept
Returns
image size.
int fsdk::Image::getWidth ( ) const
inlinenoexcept
Returns
image width.
static FSDK_API Result<Error> fsdk::Image::guessTypeFromMemory ( const void *  data,
const uint32_t  sizeInBytes,
Type type 
)
staticnoexcept

Guess type of image written into memory.

Parameters
[in]dataPointer to memory containing image.
[in]sizeInBytesCount of bytes containing image pointed to by data.
[out]typeType of passed image.
Returns
true if success, false if some error occured.
Note
Unknown type of image is not an error.
bool fsdk::Image::isNull ( ) const
inlinenoexcept
Returns
true if image data is not allocated.
bool fsdk::Image::isSharedWith ( const Image other) const
inlinenoexcept
Returns
true if this image shares the same memory chunk for it's data as the other one.
Parameters
[in]otherother image to check againts.
bool fsdk::Image::isValid ( ) const
inlinenoexcept
Returns
true if image is not null and has valid dimenstions and format.
See Also
isNull.
FSDK_API Result<Error> fsdk::Image::load ( const char *  path)
noexcept

Load image from file.

This function loads image contents from disk. Supported types are: bmp, png, ppm, jpeg, tiff. If image is not empty, it's content will be freed and memory will be reallocated to fit in the data from the file if:

FSDK_API Result<Error> fsdk::Image::load ( const char *  path,
const Format  format 
)
noexcept

Load image from file and convert it to required format.

This function does exact same thing as method above, and additionally converts loaded image to input format.

Parameters
[in]pathInput file path.
[in]formatrequired image format.
Returns
Result with error code specified by Image::Error.
See Also
Result and Image::Error.
Note
Memory residence must be MemoryResidence::MemoryCPU.
FSDK_API Result<Error> fsdk::Image::loadFromMemory ( const void *  data,
const uint32_t  sizeInBytes 
)
noexcept

Load image from memory.

This function loads image contents from memory. Supported types are: bmp, png, ppm, jpeg, tiff. If image is not empty, it's content will be freed and memory will be reallocated to fit in the data from the file if:

FSDK_API Result<Error> fsdk::Image::loadFromMemory ( const void *  data,
const uint32_t  sizeInBytes,
const Format  format 
)
noexcept

Load image from memory and convert it to required format.

This function does exact same thing as method above, and additionally converts loaded image to input format.

Parameters
[in]dataPointer to input memory.
[in]sizeInBytesCount of bytes of image pointed to by data.
[in]formatrequired image format.
Note
dest should not be the same as this image.
Returns
Result with error code specified by Image::Error.
See Also
Result and Image::Error.
Note
Memory residence must be MemoryResidence::MemoryCPU.
FSDK_API Result<Error> fsdk::Image::loadFromMemoryOfType ( const void *  data,
const uint32_t  sizeInBytes,
const Type  type 
)
noexcept

Load image from memory of specific type.

This function loads specific type image contents from memory. If data points to image of another type, not the one passed, does nothing. Supported types are: bmp, png, ppm, jpeg, tiff. If image is not empty, it's content will be freed and memory will be reallocated to fit in the data from the file if:

  • the file can be opened
  • the file is of supported format
    Parameters
    [in]dataPointer to input memory.
    [in]sizeInBytesCount of bytes of image pointed to by data.
    [in]typeType of image to be loaded.
    Returns
    Result with error code specified by Image::Error.
    See Also
    Result and Image::Error.
    Note
    Memory residence must be MemoryResidence::MemoryCPU.
FSDK_API Result<Error> fsdk::Image::loadFromMemoryOfType ( const void *  data,
const uint32_t  sizeInBytes,
const Type  type,
const Format  format 
)
noexcept

Load image from memory of specific type and convert it to required format.

This function does exact same thing as method above, and additionally converts loaded image to input format.

Parameters
[in]dataPointer to input memory.
[in]sizeInBytesCount of bytes of image pointed to by data.
[in]typeType of image to be loaded.
[in]formatrequired image format.
Returns
Result with error code specified by Image::Error.
See Also
Result and Image::Error.
Note
Memory residence must be MemoryResidence::MemoryCPU.
FSDK_API SubImage fsdk::Image::map ( int  x,
int  y,
int  width,
int  height 
) const
noexcept

Map image contents to a given area.

Note
specifying out of bounds area will result in runtime error.
Memory residence must be MemoryResidence::MemoryCPU.
Parameters
[in]xhorizontal coordinate of top left corner of image rect to map.
[in]yvertical coordinate of top left corner of image rect to map.
[in]widthwidth of image rect to map
[in]heightheight of image rect to map
Returns
sub image corresponding to the given area.
SubImage fsdk::Image::map ( const Rect rect) const
inlinenoexcept

Map image contents to a given area.

Note
specifying out of bounds area will result in runtime error.
Memory residence must be MemoryResidence::MemoryCPU.
Parameters
[in]rectimage rect to extract
Returns
sub image corresponding to the given area.
SubImage fsdk::Image::map ( const Size size) const
inlinenoexcept

Map image contents to a given area.

Note
specifying out of bounds area will result in runtime error.
sub image origin is assumed at the top-left corner of the existing one.
Memory residence must be MemoryResidence::MemoryCPU.
Parameters
[in]sizeimage size to map.
Returns
sub image corresponding to the given area.
SubImage fsdk::Image::map ( const Point2i origin,
const Size size 
) const
inlinenoexcept

Map image contents to a given area.

Note
specifying out of bounds area will result in runtime error.
Memory residence must be MemoryResidence::MemoryCPU.
Parameters
[in]originsub image image origin.
[in]sizesub image size to extract.
Returns
sub image corresponding to the given area.
fsdk::Image::operator bool ( ) const
inlinenoexcept

Implicit cast to boolean; results in true if image is valid, false if not.

See Also
isValid.
Image& fsdk::Image::operator= ( const Image other)
inlinenoexcept

Assign other image.

Parameters
[in]otherimage to assign.
Image& fsdk::Image::operator= ( Image &&  other)
inlinenoexcept

Move other image.

Parameters
[in]otherimage to move.
bool fsdk::Image::ownsData ( ) const
inlinenoexcept
Returns
true, if this image data was allocated by the image itself (via ctor or create()). Otherwise returns false.
FSDK_API int fsdk::Image::release ( )
protectednoexcept

Decrease reference count.

Returns
Current reference count.
FSDK_API Image fsdk::Image::rescale ( float  scale) const
noexcept

Rescale image keeping proportions.

Note
Performs bilinear interpolation.
Parameters
[in]scalefactor. Must be positive.
Returns
scaled image.
FSDK_API int fsdk::Image::retain ( )
protectednoexcept

Increase reference count.

Returns
Current reference count.
FSDK_API Result<Error> fsdk::Image::rotate ( Image dest,
RotationType  rotationType 
) const
noexcept

Rotates an image on 90, 180 and 270 degrees. Allocates a new buffer of given size and fills image contents with provided data.

Parameters
[in]destdest image.
[in]rotationTyperotation type.
Returns
Result with error code specified by Image::Error.
See Also
Result and Image::Error.
FSDK_API Result<Image::Error> fsdk::Image::save ( const char *  path,
fsdk::Image::ImageCompression  additionalFlag = fsdk::Image::ImageCompression::IC_NO_COMPRESSION 
) const
noexcept

Save image.

This function saves image contents to disk. Type is extracted from provided file extension. If it is unknown, function fails. Supported types are: bmp, png, ppm, jpeg, tiff.

Note
Memory residence must be MemoryResidence::MemoryCPU.
Parameters
[in]pathoutput file path with proper file extension.
[in]additionalFlagadditional flag for saving of png or jpg image
Returns
Result with error code specified by Image::Error.
See Also
Result and Image::Error.
FSDK_API Result<Error> fsdk::Image::save ( const char *  path,
const Format  format 
) const
noexcept

Convert and Save image.

This function converts image to required format and saves image contents to disk. Type is extracted from provided file extension. If it is unknown, function fails. Supported types are: bmp, png, ppm, jpeg, tiff.

Parameters
[in]pathoutput file path with proper file extension.
[in]formatrequired image format.
Returns
Result with error code specified by Image::Error.
See Also
Result and Image::Error.
Note
Memory residence must be MemoryResidence::MemoryCPU.
FSDK_API Result<Image::Error> fsdk::Image::saveToMemory ( Image::Type  type,
IArchive archive,
fsdk::Image::ImageCompression  additionalFlag = fsdk::Image::ImageCompression::IC_NO_COMPRESSION 
) const
noexcept

Save image to memory buffer.

This function saves image contents to memory buffer (IArchive). Passed IArchvie will call setSizeHint for resize.

Parameters
[in]Image::Typeformat used to encode.
[in]IArchiveto store contents of encoded image.
[in]additionalFlagadditional flag for saving of png or jpg image
Returns
Result with error code specified by Image::Error.
See Also
Result and Image::Error.
Note
Memory residence must be MemoryResidence::MemoryCPU.
FSDK_API Result<Image::Error> fsdk::Image::saveToMemory ( Image::Type  type,
IArchive archive,
const Format  format 
) const
noexcept

Convert and save image to memory buffer.

This function converts image to required format and saves image contents to memory buffer (IArchive). Passed IArchvie will call setSizeHint for resize.

Parameters
[in]Image::Typeformat used to encode.
[in]IArchiveto store contents of encoded image.
[in]formatrequired image format.
Returns
Result with error code specified by Image::Error.
See Also
Result and Image::Error.
Note
Memory residence must be MemoryResidence::MemoryCPU.
FSDK_API Result<Error> fsdk::Image::set ( int  width,
int  height,
Format  format,
const void *  data,
MemoryResidence  residence = MemoryResidence::MemoryCPU,
int  deviceId = 0 
)
noexcept

Initializes an image with provided data. If current image is not empty and it's size and format match the provided ones, no memory reallocation is performed. Otherwise image is re-created to match requirements.

Parameters
[in]widthimage width.
[in]heightimage height.
[in]formatimage format.
[in]dataimage data.
[in]memoryresidence of a data pointer.
[in]deviceIdindex of a device where data pointer was allocated
Note
deviceId is ignored for residence = MemoryResidence::MemoryCPU
output image will have memory residence of the provided data pointer.
if memory allocation fails, no exception is thrown; function call results in empty image.
Returns
true in case of success, false otherwise.
FSDK_API Result<Error> fsdk::Image::set ( int  width,
int  height,
Format  format,
void *  data,
bool  copy,
MemoryResidence  residence = MemoryResidence::MemoryCPU,
int  deviceId = 0 
)
noexcept

Initializes an image with provided data. If copy is true and if current image is not empty and it's size and format match the provided ones, no memory reallocation is performed. Otherwise image is re-created to match requirements. If copy is false (which is default) this will just reference the provided data.

Parameters
[in]widthimage width.
[in]heightimage height.
[in]formatimage format.
[in]dataimage data.
[in]copywhether to copy or reference data.
[in]memoryresidence of a data pointer.
[in]deviceIdindex of a device where data pointer was allocated
Note
deviceId is ignored for residence = MemoryResidence::MemoryCPU
output image will have memory residence of the provided data pointer.
if memory allocation fails, no exception is thrown; function call results in empty image.
Returns
true in case of success, false otherwise.
FSDK_API Result<Error> fsdk::Image::set ( const Image other)
noexcept

Initializes an image as a reference to an other image.

Parameters
[in]otherother image.
Returns
true in case of success, false otherwise.
FSDK_API Result<Error> fsdk::Image::set ( const SubImage subImage)
noexcept

Initializes an image with contents of a sub image. Since sub images do not handle data life time, image contents are always copied.

Parameters
[in]subImagesub image.
void fsdk::Image::swap ( Image other)
inlinenoexcept

Swap contents with another image.

Parameters
[in,out]otherimage to swap with.

Member Data Documentation

Format fsdk::Image::m_format
protected

image format (

See Also
Format).

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