#include <Image.h>

Public Types
enum	Type { 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 { IC_NO_COMPRESSION, IC_SMALL_COMPRESSION, IC_MEDIUM_COMPRESSION, IC_HARD_COMPRESSION, IC_BEST_COMPRESSION }
	Supported compression type is used only for jpg and png types. More...
enum	Error { Ok, InvalidWidth, InvalidHeight, InvalidDataPtr, InvalidDataSize, InvalidImage, InvalidArchive, InvalidPath, InvalidType, InvalidFormat, InvalidBitmap, InvalidMemory, InvalidConversion, InvalidResidence, InvalidDevice, InvalidCudaKernel, FailedToSave, FailedToLoad, FailedToInitialize, ReleasedInOtherThread }
	Image error codes. More...
enum	MemoryResidence { MemoryCPU, MemoryGPU, MemoryNPU, 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.
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.
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.
FSDK_API	Image (const Image &other) noexcept
	Initializes an image as a reference to an other image.
FSDK_API	Image (Image &&other) noexcept
	Initializes an image with contents of an other image. Source image is then invalidated.
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.
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.
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.
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.
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.
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.
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.
FSDK_API Result< Error >	set (const Image &other) noexcept
	Initializes an image as a reference to an other image.
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.
FSDK_API SubImage	map (int x, int y, int width, int height) const noexcept
	Map image contents to a given area.
SubImage	map (const Rect &rect) const noexcept
	Map image contents to a given area.
SubImage	map (const Size &size) const noexcept
	Map image contents to a given area.
SubImage	map (const Point2i &origin, const Size &size) const noexcept
	Map image contents to a given area.
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.
Image	extract (const Rect &rect) const noexcept
	Extract a sub image of this image. The new image will have it's own reference count.
Image	extract (const Size &size) const noexcept
	Extract a sub image of this image. The new image will have it's own reference count.
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.
Image	clone () const noexcept
	Create a copy of this image. The new image will have it's own reference count.
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.
Result< Image::Error >	convert (Image &dest, const Point2i &origin, const Size &size, Format format, TargetDevice device=TargetDevice::CPU) const noexcept
	Convert image format.
Result< Image::Error >	convert (Image &dest, const Size &size, Format format, TargetDevice device=TargetDevice::CPU) const noexcept
	Convert image format.
Result< Image::Error >	convert (Image &dest, const Rect &rect, Format format, TargetDevice device=TargetDevice::CPU) const noexcept
	Convert image format.
Result< Image::Error >	convert (Image &dest, Format format, TargetDevice device=TargetDevice::CPU) const noexcept
	Convert image format.
FSDK_API Image	rescale (float scale) const noexcept
	Rescale image keeping proportions.
FSDK_API Result< Image::Error >	save (const char *path, fsdk::Image::ImageCompression additionalFlag=fsdk::Image::ImageCompression::IC_NO_COMPRESSION) const noexcept
	Save image.
FSDK_API Result< Error >	save (const char *path, const Format format) const noexcept
	Convert and Save image.
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.
FSDK_API Result< Image::Error >	saveToMemory (Image::Type type, IArchive *archive, const Format format) const noexcept
	Convert and save image to memory buffer.
FSDK_API Result< Error >	load (const char *path) noexcept
	Load image from file.
FSDK_API Result< Error >	load (const char *path, const Format format) noexcept
	Load image from file and convert it to required format.
FSDK_API Result< Error >	loadFromMemory (const void *data, const uint32_t sizeInBytes) noexcept
	Load image from memory.
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.
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.
FSDK_API Result< Error >	loadFromMemoryOfType (const void *data, const uint32_t sizeInBytes, const Type type) noexcept
	Load image from memory of specific type.
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.
Image &	operator= (const Image &other) noexcept
	Assign other image.
Image &	operator= (Image &&other) noexcept
	Move other image.
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.
FSDK_API void *	getScanLine (int y) noexcept
	Get image scanline data.
FSDK_API const void *	getScanLine (int y) const noexcept
	Get image scanline data.
FSDK_API int	getDataSize () const noexcept
FSDK_API void	getDataSize (Sizer &sizer) const noexcept
	Get actual image size in bytes.
template<typename T >
T *	getScanLineAs (int y) noexcept
	Get image scanline data.
template<typename T >
const T *	getScanLineAs (int y) const noexcept
	Get image scanline data.
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.
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.
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.
Protected Member Functions
FSDK_API int	retain () noexcept
	Increase reference count.
FSDK_API int	release () noexcept
	Decrease reference count.
FSDK_API int	getRefCount () const noexcept
	Obtain reference count.
Static Protected Member Functions
static FSDK_API void *	allocate (int size) noexcept
	Allocate memory.
static FSDK_API void	deallocate (void *memory) noexcept
	Free memory.
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 (
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

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.

enum fsdk::Image::ImageCompression

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)

enum fsdk::Image::MemoryResidence

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`
	)

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.

FSDK_API fsdk::Image::Image	(	int	width,
		int	height,
		Format	format,
		const void *	data,
		MemoryResidence	residence = `MemoryResidence::MemoryCPU`,
		int	deviceId = `0`
	)

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.

FSDK_API fsdk::Image::Image	(	int	width,
		int	height,
		Format	format,
		void *	data,
		bool	copy,
		MemoryResidence	residence = `MemoryResidence::MemoryCPU`,
		int	deviceId = `0`
	)

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.

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

Initializes an image as a reference to an other image.

Parameters:

[in] other other image.

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

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

Parameters:

[in] other other image.

FSDK_API fsdk::Image::Image ( const SubImage & subImage ) [explicit]

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

static FSDK_API void* fsdk::Image::allocate ( int size ) [static, protected]

Allocate memory.

Parameters:

[in] size memory region size in bytes.

Returns:: Memory region pointer.

Image fsdk::Image::clone ( ) const [inline]

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

Convert image format.

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

Parameters:

	[inout]	dest destination image.
[in]	x	horisontal 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.

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

Convert image format.

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

Parameters:

	[inout]	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.

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

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:

	[inout]	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.

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

Convert image format.

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

Parameters:

	[inout]	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.

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

Convert image format.

Parameters:

	[inout]	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.

FSDK_API Result<Error> fsdk::Image::create	(	int	width,
		int	height,
		Format	format,
		bool	cleanup = `true`,
		MemoryResidence	residence = `MemoryResidence::MemoryCPU`,
		int	deviceId = `0`
	)

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.

FSDK_API Result<Error> fsdk::Image::create	(	int	width,
		int	height,
		Format	format,
		const void *	data,
		MemoryResidence	residence = `MemoryResidence::MemoryCPU`,
		int	deviceId = `0`
	)

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.

FSDK_API Result<Error> fsdk::Image::create	(	int	width,
		int	height,
		Format	format,
		void *	data,
		bool	copy,
		MemoryResidence	residence = `MemoryResidence::MemoryCPU`,
		int	deviceId = `0`
	)

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.

FSDK_API Result<Error> fsdk::Image::create	(	const fsdk::Image &	source,
		MemoryResidence	residence,
		int	deviceId = `0`
	)

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.

static FSDK_API void fsdk::Image::deallocate ( void * memory ) [static, protected]

Free memory.

Parameters:

[in] memory memory region pointer.

bool fsdk::Image::equalStrong ( const fsdk::Image & other ) const [inline]

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

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

Parameters:

[in]	x	horisontal 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.; Memory residence must be MemoryResidence::MemoryCPU.

Image fsdk::Image::extract ( const Rect & rect ) const [inline]

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.; Memory residence must be MemoryResidence::MemoryCPU.

Image fsdk::Image::extract ( const Size & size ) const [inline]

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.; Memory residence must be MemoryResidence::MemoryCPU.

Image fsdk::Image::extract	(	const Point2i &	origin,
		const Size &	size
	)		const `[inline]`

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.; Memory residence must be MemoryResidence::MemoryCPU.

float fsdk::Image::getAspectRatio ( ) const [inline]

Returns:: image aspect ratio (width to height).

void* fsdk::Image::getData ( ) [inline]

Returns:: pointer to raw image data.

const void* fsdk::Image::getData ( ) const [inline]

Returns:: pointer to raw image data.

template<typename T >

T* fsdk::Image::getDataAs ( ) [inline]

Returns:: pointer to image data cast to a given type.

template<typename T >

const T* fsdk::Image::getDataAs ( ) const [inline]

Returns:: pointer to image data cast to a given type.

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

Returns:: actual image size in bytes.

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

Get actual image size in bytes.

Parameters:

[inout] sizer sizer to append result to.

Format fsdk::Image::getFormat ( ) const [inline]

Returns:: image format.

int fsdk::Image::getHeight ( ) const [inline]

Returns:: image height.

Rect fsdk::Image::getRect ( ) const [inline]

Returns:: image rectangle.

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

FSDK_API int fsdk::Image::getRefCount ( ) const [protected]

Obtain reference count.

Returns:: Current reference count.

int fsdk::Image::getRowSize ( ) const [inline]

Returns:: size of image pixel row in bytes.

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

Get image scanline data.

Parameters:

[in] y scanline number.

Returns:: pointer to raw data.

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

Get image scanline data.

Parameters:

[in] y scanline number.

Returns:: pointer to raw data.

template<typename T >

T* fsdk::Image::getScanLineAs ( int y ) [inline]

Get image scanline data.

Parameters:

[in] y scanline number.

Returns:: pointer image data cast to a given type.

template<typename T >

const T* fsdk::Image::getScanLineAs ( int y ) const [inline]

Get image scanline data.

Parameters:

[in] y scanline number.

Returns:: pointer image data cast to a given type.

Size fsdk::Image::getSize ( ) const [inline]

Returns:: image size.

int fsdk::Image::getWidth ( ) const [inline]

Returns:: image width.

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

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.

bool fsdk::Image::isNull ( ) const [inline]

Returns:: true if image data is not allocated.

bool fsdk::Image::isSharedWith ( const Image & other ) const [inline]

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.

bool fsdk::Image::isValid ( ) const [inline]

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 )

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.

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

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.

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

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.

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

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.

FSDK_API Result<Error> fsdk::Image::loadFromMemoryOfType	(	const void *	data,
		const uint32_t	sizeInBytes,
		const Type	type
	)

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.

FSDK_API Result<Error> fsdk::Image::loadFromMemoryOfType	(	const void *	data,
		const uint32_t	sizeInBytes,
		const Type	type,
		const Format	format
	)

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.

FSDK_API SubImage fsdk::Image::map	(	int	x,
		int	y,
		int	width,
		int	height
	)		const

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.

SubImage fsdk::Image::map ( const Rect & rect ) const [inline]

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.

SubImage fsdk::Image::map ( const Size & size ) const [inline]

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.

SubImage fsdk::Image::map	(	const Point2i &	origin,
		const Size &	size
	)		const `[inline]`

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.

fsdk::Image::operator bool ( ) const [inline]

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

See also:: isValid.

Image& fsdk::Image::operator= ( const Image & other ) [inline]

Assign other image.

Parameters:

[in] other image to assign.

Image& fsdk::Image::operator= ( Image && other ) [inline]

Move other image.

Parameters:

[in] other image to move.

bool fsdk::Image::ownsData ( ) const [inline]

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 ( ) [protected]

Decrease reference count.

Returns:: Current reference count.

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

Rescale image keeping proportions.

Note:: Performs bilinear interpolation.

Parameters:

[in] scale factor. Must be positive.

Returns:: scaled image.

FSDK_API int fsdk::Image::retain ( ) [protected]

Increase reference count.

Returns:: Current reference count.

FSDK_API Result<Error> fsdk::Image::rotate	(	Image &	dest,
		RotationType	rotationType
	)		const

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]	dest	dest image.
[in]	rotationType	rotation 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

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.

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

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.

FSDK_API Result<Image::Error> fsdk::Image::saveToMemory	(	Image::Type	type,
		IArchive *	archive,
		fsdk::Image::ImageCompression	additionalFlag = `fsdk::Image::ImageCompression::IC_NO_COMPRESSION`
	)		const

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.

FSDK_API Result<Image::Error> fsdk::Image::saveToMemory	(	Image::Type	type,
		IArchive *	archive,
		const Format	format
	)		const

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.

FSDK_API Result<Error> fsdk::Image::set	(	int	width,
		int	height,
		Format	format,
		const void *	data,
		MemoryResidence	residence = `MemoryResidence::MemoryCPU`,
		int	deviceId = `0`
	)

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.

FSDK_API Result<Error> fsdk::Image::set	(	int	width,
		int	height,
		Format	format,
		void *	data,
		bool	copy,
		MemoryResidence	residence = `MemoryResidence::MemoryCPU`,
		int	deviceId = `0`
	)

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.

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

Initializes an image as a reference to an other image.

Parameters:

[in] other other image.

Returns:: true in case of success, false otherwise.

FSDK_API Result<Error> fsdk::Image::set ( const SubImage & subImage )

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.

void fsdk::Image::swap ( Image & other ) [inline]

Swap contents with another image.

Parameters:

[inout] other image 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:

include/fsdk/Types/Image.h

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation