| Face Engine SDK 5.32.0 A face detection, recognition and tracking engine.

Public Types | Public Member Functions | Static Public Member Functions | Protected Member Functions | Static Protected Member Functions | Protected Attributes | List of all members
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::InvalidInput, 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< Error > | 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. More...
FSDK_API Result< Error > | 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. More...
FSDK_API Result< Error > | 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. More...
FSDK_API Result< Error > | 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. More...
FSDK_API Result< Error > | 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. More...
FSDK_API Result< Error > | 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. More...
FSDK_API Result< Error > | set (const Image &other) noexcept
| Initializes an image as a reference to an other image. More...
FSDK_API Result< Error > | 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. 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...
FSDK_API Result< Image::Error > | extract (Image &dest, 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...
FSDK_API Result< Image::Error > | extract (Image &dest, const Rect &rect) const noexcept
| Extract a sub image of this image. The new image will have it's own reference count. More...
FSDK_API Result< Error > | rescale (Image &dest, float scale) const noexcept
| Rescale image keeping proportions. 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::Error > | convert (Image &dest, int x, int y, int width, int height, Format format, TargetDevice device=TargetDevice::CPU) const noexcept
| Convert image format. More...
Result< Image::Error > | convert (Image &dest, const Point2i &origin, const Size &size, Format format, TargetDevice device=TargetDevice::CPU) const noexcept
| Convert image format. More...
Result< Image::Error > | convert (Image &dest, const Size &size, Format format, TargetDevice device=TargetDevice::CPU) const noexcept
| Convert image format. More...
Result< Image::Error > | convert (Image &dest, const Rect &rect, Format format, TargetDevice device=TargetDevice::CPU) const noexcept
| Convert image format. More...
Result< Image::Error > | convert (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::Error > | save (const char *path, fsdk::Image::ImageCompression additionalFlag=fsdk::Image::ImageCompression::IC_NO_COMPRESSION) const noexcept
| Save image. More...
FSDK_API Result< Error > | save (const char *path, const Format format) const noexcept
| Convert and Save image. More...
FSDK_API Result< Image::Error > | saveToMemory (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::Error > | saveToMemory (Image::Type type, IArchive *archive, const Format format) const noexcept
| Convert and save image to memory buffer. More...
FSDK_API Result< Error > | load (const char *path) noexcept
| Load image from file. More...
FSDK_API Result< Error > | load (const char *path, const Format format) noexcept
| Load image from file and convert it to required format. More...
FSDK_API Result< Error > | loadFromMemory (const void *data, const uint32_t sizeInBytes) noexcept
| Load image from memory. More...
FSDK_API Result< Error > | 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. More...
FSDK_API Result< Error > | loadFromMemory (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< Error > | loadFromMemoryOfType (const void *data, const uint32_t sizeInBytes, const Type type) noexcept
| Load image from memory of specific type. More...
FSDK_API Result< Error > | 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. More...
Image & | operator= (const Image &other) noexcept
| Assign other image. More...
Image & | operator= (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< Error > | guessTypeFromMemory (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

## ◆ Error

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.
InvalidInput | Invalid input.
ReleasedInOtherThread | Failed to retain image: it was released in another thread.

## ◆ ImageCompression

enum fsdk::Image::ImageCompression
| strong

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 | image) compression with minimal (or without) quality loss (only for png or jpg
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)

## ◆ MemoryResidence

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

## ◆ Image() [1/6]

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] | width | image width.
  [in] | height | image height.
  [in] | format | image format.
  [in] | deviceId | index 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.

## ◆ Image() [2/6]

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] | width | image width.
  [in] | height | image height.
  [in] | format | image format.
  [in] | data | image data.
  [in] | deviceId | index 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.

## ◆ Image() [3/6]

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] | width | image width.
  [in] | height | image height.
  [in] | format | image format.
  [in] | data | image data.
  [in] | copy | [optional] whether to copy or reference data.
  [in] | deviceId | index 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.

## ◆ Image() [4/6]

FSDK_API fsdk::Image::Image | ( | const Image & | other | ) |
| noexcept

Initializes an image as a reference to an other image.

Parameters

  [in] | other | other image.

## ◆ Image() [5/6]

FSDK_API fsdk::Image::Image | ( | Image && | other | ) |
| noexcept

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

Parameters

  [in] | other | other image.

## ◆ Image() [6/6]

FSDK_API fsdk::Image::Image | ( | const SubImage & | subImage | ) |
| explicit 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] | subImage | sub image.

## Member Function Documentation

## ◆ allocate()

static FSDK_API void* fsdk::Image::allocate | ( | int | size | ) |
| static protected noexcept

Allocate memory.

Parameters

  [in] | size | memory region size in bytes.

Returns
  Memory region pointer.

## ◆ clone()

Image fsdk::Image::clone | ( |  | ) | const
| inline noexcept

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.

## ◆ convert() [1/5]

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] | dest | destination image.
  [in] | x | horizontal coordinate of top left corner of image rect to convert.
  [in] | y | vertical coordinate of top left corner of image rect to convert.
  [in] | width | width of image rect to convert.
  [in] | height | height of image rect to convert.
  [in] | format | new format.
  [in] | device | target 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.

## ◆ convert() [2/5]

Result<Image::Error> fsdk::Image::convert | ( | Image & | dest,
|  | const Point2i & | origin,
|  | const Size & | size,
|  | Format | format,
|  | TargetDevice | device = `TargetDevice::CPU`
| ) |  | const
| inline noexcept

Convert image format.

Note
  specifying out of bounds area will result in runtime error.

Parameters

  [in,out] | dest | destination image.
  [in] | origin | converted image origin.
  [in] | size | image size to convert.
  [in] | format | new format.
  [in] | device | target 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.

## ◆ convert() [3/5]

Result<Image::Error> fsdk::Image::convert | ( | Image & | dest,
|  | const Size & | size,
|  | Format | format,
|  | TargetDevice | device = `TargetDevice::CPU`
| ) |  | const
| inline noexcept

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] | dest | destination image.
  [in] | format | new format.
  [in] | size | image area size to convert.
  [in] | device | target 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.

## ◆ convert() [4/5]

Result<Image::Error> fsdk::Image::convert | ( | Image & | dest,
|  | const Rect & | rect,
|  | Format | format,
|  | TargetDevice | device = `TargetDevice::CPU`
| ) |  | const
| inline noexcept

Convert image format.

Note
  specifying out of bounds area will result in runtime error.

Parameters

  [in,out] | dest | destination image.
  [in] | format | new format.
  [in] | rect | image area rect to convert.
  [in] | device | target 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.

## ◆ convert() [5/5]

Result<Image::Error> fsdk::Image::convert | ( | Image & | dest,
|  | Format | format,
|  | TargetDevice | device = `TargetDevice::CPU`
| ) |  | const
| inline noexcept

Convert image format.

Parameters

  [in,out] | dest | destination image.
  [in] | format | new format.
  [in] | device | target 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.

## ◆ create() [1/4]

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] | width | image width.
  [in] | height | image height.
  [in] | format | image format.
  [in] | cleanup | initializes internal image memory to default value.
  [in] | residence | memory residence of a data pointer.
  [in] | deviceId | index 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.

## ◆ create() [2/4]

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] | width | image width.
  [in] | height | image height.
  [in] | format | image format.
  [in] | data | image data.
  [in] | memory | residence of a data pointer.
  [in] | deviceId | index 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.

## ◆ create() [3/4]

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] | width | image width.
  [in] | height | image height.
  [in] | format | image format.
  [in] | data | image data.
  [in] | copy | whether to copy or reference data
  [in] | memory | residence of a data pointer.
  [in] | deviceId | index 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.

## ◆ create() [4/4]

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] | image | instance to create copy for
  [in] | residence | memory residence for the target image
  [in] | deviceId | index of a device for the target image

Note
  deviceId is ignored for residence = MemoryResidence::MemoryCPU

Returns
  true in case of success, false otherwise.

## ◆ deallocate()

static FSDK_API void fsdk::Image::deallocate | ( | void * | memory | ) |
| static protected noexcept

Free memory.

Parameters

  [in] | memory | memory region pointer.

## ◆ equalStrong()

bool fsdk::Image::equalStrong | ( | const fsdk::Image & | other | ) | const
| inline 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.

See also
  equalWeak().

## ◆ extract() [1/6]

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] | x | horizontal coordinate of top left corner of image rect to extract.
  [in] | y | vertical coordinate of top left corner of image rect to extract.
  [in] | width | width of image rect to extract.
  [in] | height | height of image rect to extract.

Returns
  new image with copied data.

Note
  empty image returned in case of an memory allocation error.
  Source ROI must be completely inside the image boundaries.
  Memory residence must be MemoryResidence::MemoryCPU or MemoryResidence::MemoryGPU.

## ◆ extract() [2/6]

FSDK_API Result<Image::Error> fsdk::Image::extract | ( | Image & | dest,
|  | 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

  [out] | dest | the destination image.
  [in] | x | horizontal coordinate of top left corner of image rect to extract.
  [in] | y | vertical coordinate of top left corner of image rect to extract.
  [in] | width | width of image rect to extract.
  [in] | height | height of image rect to extract.

Returns
  Result with error code specified by Image::Error.

Note
  Source ROI must be completely inside the image boundaries.
  Memory residence must be MemoryResidence::MemoryCPU or MemoryResidence::MemoryGPU.

## ◆ extract() [3/6]

FSDK_API Result<Image::Error> fsdk::Image::extract | ( | Image & | dest,
|  | const Rect & | rect
| ) |  | const
| noexcept

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

Parameters

  [out] | dest | the destination image.
  [in] | rect | rectangle specifying the region of the image to extract.

Returns
  Result with error code specified by Image::Error.

See also
  Result and Image::Error.

Note
  empty image returned in case of an memory allocation error.
  Source ROI must be completely inside the image boundaries.
  Memory residence must be MemoryResidence::MemoryCPU or MemoryResidence::MemoryGPU.

## ◆ extract() [4/6]

Image fsdk::Image::extract | ( | const Rect & | rect | ) | const
| inline noexcept

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

Parameters

  [in] | rect | image rect to extract.

Returns
  new image with copied data.

Note
  empty image returned in case of an memory allocation error.
  Source ROI must be completely inside the image boundaries.
  Memory residence must be MemoryResidence::MemoryCPU or MemoryResidence::MemoryGPU.

## ◆ extract() [5/6]

Image fsdk::Image::extract | ( | const Size & | size | ) | const
| inline noexcept

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] | size | image size to extract.

Returns
  new image with copied data.

Note
  empty image returned in case of an memory allocation error.
  Source ROI must be completely inside the image boundaries.
  Memory residence must be MemoryResidence::MemoryCPU or MemoryResidence::MemoryGPU.

## ◆ extract() [6/6]

Image fsdk::Image::extract | ( | const Point2i & | origin,
|  | const Size & | size
| ) |  | const
| inline noexcept

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

Parameters

  [in] | origin | extracted image origin.
  [in] | size | image size to extract.

Returns
  new image with copied data.

Note
  empty image returned in case of an memory allocation error.
  Source ROI must be completely inside the image boundaries.
  Memory residence must be MemoryResidence::MemoryCPU or MemoryResidence::MemoryGPU.

## ◆ getAspectRatio()

float fsdk::Image::getAspectRatio | ( |  | ) | const
| inline noexcept

Returns
  image aspect ratio (width to height).

## ◆ getData() [1/2]

void* fsdk::Image::getData | ( |  | ) |
| inline noexcept

Returns
  pointer to raw image data.

## ◆ getData() [2/2]

const void* fsdk::Image::getData | ( |  | ) | const
| inline noexcept

Returns
  pointer to raw image data.

## ◆ getDataAs() [1/2]

template<typename T >

T* fsdk::Image::getDataAs | ( |  | ) |
| inline noexcept

Returns
  pointer to image data cast to a given type.

## ◆ getDataAs() [2/2]

template<typename T >

const T* fsdk::Image::getDataAs | ( |  | ) | const
| inline noexcept

Returns
  pointer to image data cast to a given type.

## ◆ getDataSize() [1/2]

FSDK_API int fsdk::Image::getDataSize | ( |  | ) | const
| noexcept

Returns
  actual image size in bytes.

## ◆ getDataSize() [2/2]

FSDK_API void fsdk::Image::getDataSize | ( | Sizer & | sizer | ) | const
| noexcept

Get actual image size in bytes.

Parameters

  [in,out] | sizer | sizer to append result to.

## ◆ getFormat()

Format fsdk::Image::getFormat | ( |  | ) | const
| inline noexcept

Returns
  image format.

## ◆ getHeight()

int fsdk::Image::getHeight | ( |  | ) | const
| inline noexcept

Returns
  image height.

## ◆ getRect()

Rect fsdk::Image::getRect | ( |  | ) | const
| inline noexcept

Returns
  image rectangle.

Note
  resulting rectangle top left corner is lways at (0, 0).

## ◆ getRefCount()

FSDK_API int fsdk::Image::getRefCount | ( |  | ) | const
| protected noexcept

Obtain reference count.

Returns
  Current reference count.

## ◆ getRowSize()

int fsdk::Image::getRowSize | ( |  | ) | const
| inline noexcept

Returns
  size of image pixel row in bytes.

## ◆ getScanLine() [1/2]

FSDK_API void* fsdk::Image::getScanLine | ( | int | y | ) |
| noexcept

Get image scanline data.

Parameters

  [in] | y | scanline number.

Returns
  pointer to raw data.

## ◆ getScanLine() [2/2]

FSDK_API const void* fsdk::Image::getScanLine | ( | int | y | ) | const
| noexcept

Get image scanline data.

Parameters

  [in] | y | scanline number.

Returns
  pointer to raw data.

## ◆ getScanLineAs() [1/2]

template<typename T >

T* fsdk::Image::getScanLineAs | ( | int | y | ) |
| inline noexcept

Get image scanline data.

Parameters

  [in] | y | scanline number.

Returns
  pointer image data cast to a given type.

## ◆ getScanLineAs() [2/2]

template<typename T >

const T* fsdk::Image::getScanLineAs | ( | int | y | ) | const
| inline noexcept

Get image scanline data.

Parameters

  [in] | y | scanline number.

Returns
  pointer image data cast to a given type.

## ◆ getSize()

Size fsdk::Image::getSize | ( |  | ) | const
| inline noexcept

Returns
  image size.

## ◆ getWidth()

int fsdk::Image::getWidth | ( |  | ) | const
| inline noexcept

Returns
  image width.

## ◆ guessTypeFromMemory()

static FSDK_API Result<Error> fsdk::Image::guessTypeFromMemory | ( | const void * | data,
|  | const uint32_t | sizeInBytes,
|  | Type & | type
| ) |  |
| static noexcept

Guess type of image written into memory.

Parameters

  [in] | data | Pointer to memory containing image.
  [in] | sizeInBytes | Count of bytes containing image pointed to by data.
  [out] | type | Type of passed image.

Returns
  true if success, false if some error occured.

Note
  Unknown type of image is not an error.

## ◆ isNull()

bool fsdk::Image::isNull | ( |  | ) | const
| inline noexcept

Returns
  true if image data is not allocated.

## ◆ isSharedWith()

bool fsdk::Image::isSharedWith | ( | const Image & | other | ) | const
| inline noexcept

Returns
  true if this image shares the same memory chunk for it's data as the other one.

Parameters

  [in] | other | other image to check againts.

## ◆ isValid()

bool fsdk::Image::isValid | ( |  | ) | const
| inline noexcept

Returns
  true if image is not null and has valid dimenstions and format.

See also
  isNull.

## ◆ load() [1/2]

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:

- the file can be opened
- the file is of supported format
  Parameters

    [in] | path | Input file path.

  Returns
    Result with error code specified by Image::Error.
  See also
    Result and Image::Error.
  Note
    Memory residence must be MemoryResidence::MemoryCPU.

## ◆ load() [2/2]

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] | path | Input file path.
  [in] | format | required image format.

Returns
  Result with error code specified by Image::Error.

See also
  Result and Image::Error.

Note
  Memory residence must be MemoryResidence::MemoryCPU.

## ◆ loadFromMemory() [1/2]

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:

- the file can be opened
- the file is of supported format
  Parameters

    [in] | data | Pointer to input memory.
    [in] | sizeInBytes | Count of bytes of image pointed to by data.

  Returns
    Result with error code specified by Image::Error.
  See also
    Result and Image::Error.
  Note
    Memory residence must be MemoryResidence::MemoryCPU.

## ◆ loadFromMemory() [2/2]

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] | data | Pointer to input memory.
  [in] | sizeInBytes | Count of bytes of image pointed to by data.
  [in] | format | required 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.

## ◆ loadFromMemoryOfType() [1/2]

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] | data | Pointer to input memory.
    [in] | sizeInBytes | Count of bytes of image pointed to by data.
    [in] | type | Type 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.

## ◆ loadFromMemoryOfType() [2/2]

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] | data | Pointer to input memory.
  [in] | sizeInBytes | Count of bytes of image pointed to by data.
  [in] | type | Type of image to be loaded.
  [in] | format | required image format.

Returns
  Result with error code specified by Image::Error.

See also
  Result and Image::Error.

Note
  Memory residence must be MemoryResidence::MemoryCPU.

## ◆ map() [1/4]

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] | x | horizontal coordinate of top left corner of image rect to map.
  [in] | y | vertical coordinate of top left corner of image rect to map.
  [in] | width | width of image rect to map
  [in] | height | height of image rect to map

Returns
  sub image corresponding to the given area.

## ◆ map() [2/4]

SubImage fsdk::Image::map | ( | const Rect & | rect | ) | const
| inline 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] | rect | image rect to extract

Returns
  sub image corresponding to the given area.

## ◆ map() [3/4]

SubImage fsdk::Image::map | ( | const Size & | size | ) | const
| inline noexcept

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] | size | image size to map.

Returns
  sub image corresponding to the given area.

## ◆ map() [4/4]

SubImage fsdk::Image::map | ( | const Point2i & | origin,
|  | const Size & | size
| ) |  | const
| inline 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] | origin | sub image image origin.
  [in] | size | sub image size to extract.

Returns
  sub image corresponding to the given area.

## ◆ operator bool()

fsdk::Image::operator bool | ( |  | ) | const
| inline noexcept

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

See also
  isValid.

## ◆ operator=() [1/2]

Image& fsdk::Image::operator= | ( | const Image & | other | ) |
| inline noexcept

Assign other image.

Parameters

  [in] | other | image to assign.

## ◆ operator=() [2/2]

Image& fsdk::Image::operator= | ( | Image && | other | ) |
| inline noexcept

Move other image.

Parameters

  [in] | other | image to move.

## ◆ ownsData()

bool fsdk::Image::ownsData | ( |  | ) | const
| inline noexcept

Returns
  true, if this image data was allocated by the image itself (via ctor or create()). Otherwise returns false.

## ◆ release()

FSDK_API int fsdk::Image::release | ( |  | ) |
| protected noexcept

Decrease reference count.

Returns
  Current reference count.

## ◆ rescale() [1/2]

FSDK_API Result<Error> fsdk::Image::rescale | ( | Image & | dest,
|  | float | scale
| ) |  | const
| noexcept

Rescale image keeping proportions.

Note
  Performs bilinear interpolation.

Parameters

  [out] | dest | the destination image.
  [in] | scale | factor. Must be positive.

Returns
  Result with error code specified by Image::Error.

See also
  Result and Image::Error.

## ◆ rescale() [2/2]

FSDK_API Image fsdk::Image::rescale | ( | float | scale | ) | const
| noexcept

Rescale image keeping proportions.

Note
  Performs bilinear interpolation.

Parameters

  [in] | scale | factor. Must be positive.

Returns
  scaled image.

## ◆ retain()

FSDK_API int fsdk::Image::retain | ( |  | ) |
| protected noexcept

Increase reference count.

Returns
  Current reference count.

## ◆ rotate()

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

  [out] | dest | the destination image.
  [in] | rotationType | rotation type.

Returns
  Result with error code specified by Image::Error.

See also
  Result and Image::Error.

## ◆ save() [1/2]

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] | path | output file path with proper file extension.
  [in] | additionalFlag | additional flag for saving of png or jpg image

Returns
  Result with error code specified by Image::Error.

See also
  Result and Image::Error.

## ◆ save() [2/2]

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] | path | output file path with proper file extension.
  [in] | format | required image format.

Returns
  Result with error code specified by Image::Error.

See also
  Result and Image::Error.

Note
  Memory residence must be MemoryResidence::MemoryCPU.

## ◆ saveToMemory() [1/2]

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::Type | format used to encode.
  [in] | IArchive | to store contents of encoded image.
  [in] | additionalFlag | additional 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.

## ◆ saveToMemory() [2/2]

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::Type | format used to encode.
  [in] | IArchive | to store contents of encoded image.
  [in] | format | required image format.

Returns
  Result with error code specified by Image::Error.

See also
  Result and Image::Error.

Note
  Memory residence must be MemoryResidence::MemoryCPU.

## ◆ set() [1/4]

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] | width | image width.
  [in] | height | image height.
  [in] | format | image format.
  [in] | data | image data.
  [in] | memory | residence of a data pointer.
  [in] | deviceId | index 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.

## ◆ set() [2/4]

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] | width | image width.
  [in] | height | image height.
  [in] | format | image format.
  [in] | data | image data.
  [in] | copy | whether to copy or reference data.
  [in] | memory | residence of a data pointer.
  [in] | deviceId | index 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.

## ◆ set() [3/4]

FSDK_API Result<Error> fsdk::Image::set | ( | const Image & | other | ) |
| noexcept

Initializes an image as a reference to an other image.

Parameters

  [in] | other | other image.

Returns
  true in case of success, false otherwise.

## ◆ set() [4/4]

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] | subImage | sub image.

## ◆ swap()

void fsdk::Image::swap | ( | Image & | other | ) |
| inline noexcept

Swap contents with another image.

Parameters

  [in,out] | other | image to swap with.

## Member Data Documentation

## ◆ m_format

Format fsdk::Image::m_format
| protected

image format (

See also
  Format).

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

- include/fsdk/Types/Image.h