#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< 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...

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

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.

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

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.

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.

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

noexcept

Initializes an image as a reference to an other image.

Parameters

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

Member Function Documentation

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

staticprotectednoexcept

Allocate memory.

Parameters

[in] size memory 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]	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

inlinenoexcept

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.

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]	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

inlinenoexcept

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.

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

inlinenoexcept

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.

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.

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.

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.

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.

static FSDK_API void fsdk::Image::deallocate ( void * memory )

staticprotectednoexcept

Free memory.

Parameters

[in] memory memory 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]	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

inlinenoexcept

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

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] 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

inlinenoexcept

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

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] sizer sizer 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] y scanline number.

Returns: pointer to raw data.

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.

template<typename T >

T* fsdk::Image::getScanLineAs ( int y )

inlinenoexcept

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

inlinenoexcept

Get image scanline data.

Parameters

[in] y scanline 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]	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

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] other other 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:

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
	)

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.

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.

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.

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.

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.

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.

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] rect image 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] size image 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]	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

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] other image to assign.

Image& fsdk::Image::operator= ( Image && other )

inlinenoexcept

Move other image.

Parameters

[in] other image 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] scale factor. 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]	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

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.

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.

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.

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.

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.

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.

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.

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.

void fsdk::Image::swap ( Image & other )

inlinenoexcept

Swap contents with another image.

Parameters

[in,out] 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