Detailed Description

APIs creating and using raw image data type.

Data Structures
struct	tivx_raw_image_format_t
	The raw image format structure that is given to the tivxCreateRawImage function. More...

struct	tivx_raw_image_create_params_t
	The raw image create params structure that is given to the tivxCreateRawImage function. More...

Defines
#define	TIVX_TYPE_RAW_IMAGE 0x817
	The object type enumeration for raw images. More...

#define	TIVX_ENUM_RAW_IMAGE_BUFFER_ACCESS (vx_enum)0x0
	The enum type enumeration for raw images. More...

#define	TIVX_RAW_IMAGE_MAX_EXPOSURES 3
	Maximum number of RAW image exposures that can be contained in a raw image object.

Typedefs
typedef struct _tivx_raw_image *	tivx_raw_image
	The Raw Image Object. Raw Image is a strongly-typed container for RAW sensor images.

Enumerations
enum	tivx_raw_image_attribute_e { TIVX_RAW_IMAGE_WIDTH = VX_ATTRIBUTE_BASE(VX_ID_TI, TIVX_TYPE_RAW_IMAGE) + 0x0, TIVX_RAW_IMAGE_HEIGHT = VX_ATTRIBUTE_BASE(VX_ID_TI, TIVX_TYPE_RAW_IMAGE) + 0x1, TIVX_RAW_IMAGE_NUM_EXPOSURES = VX_ATTRIBUTE_BASE(VX_ID_TI, TIVX_TYPE_RAW_IMAGE) + 0x2, TIVX_RAW_IMAGE_LINE_INTERLEAVED = VX_ATTRIBUTE_BASE(VX_ID_TI, TIVX_TYPE_RAW_IMAGE) + 0x3, TIVX_RAW_IMAGE_FORMAT = VX_ATTRIBUTE_BASE(VX_ID_TI, TIVX_TYPE_RAW_IMAGE) + 0x4, TIVX_RAW_IMAGE_META_HEIGHT_BEFORE = VX_ATTRIBUTE_BASE(VX_ID_TI, TIVX_TYPE_RAW_IMAGE) + 0x5, TIVX_RAW_IMAGE_META_HEIGHT_AFTER = VX_ATTRIBUTE_BASE(VX_ID_TI, TIVX_TYPE_RAW_IMAGE) + 0x6, TIVX_RAW_IMAGE_IMAGEPATCH_ADDRESSING = VX_ATTRIBUTE_BASE(VX_ID_TI, TIVX_TYPE_RAW_IMAGE) + 0x7 }
	The raw image attributes. More...

enum	tivx_raw_image_buffer_access_e { TIVX_RAW_IMAGE_ALLOC_BUFFER = VX_ENUM_BASE(VX_ID_TI, TIVX_ENUM_RAW_IMAGE_BUFFER_ACCESS) + 0x0, TIVX_RAW_IMAGE_PIXEL_BUFFER = VX_ENUM_BASE(VX_ID_TI, TIVX_ENUM_RAW_IMAGE_BUFFER_ACCESS) + 0x1, TIVX_RAW_IMAGE_META_BEFORE_BUFFER = VX_ENUM_BASE(VX_ID_TI, TIVX_ENUM_RAW_IMAGE_BUFFER_ACCESS) + 0x2, TIVX_RAW_IMAGE_META_AFTER_BUFFER = VX_ENUM_BASE(VX_ID_TI, TIVX_ENUM_RAW_IMAGE_BUFFER_ACCESS) + 0x3 }
	The raw image buffer access enum. More...

enum	tivx_raw_image_pixel_container_e { TIVX_RAW_IMAGE_16_BIT = VX_ENUM_BASE(VX_ID_TI, TIVX_ENUM_RAW_IMAGE_PIXEL_CONTAINER) + 0x0, TIVX_RAW_IMAGE_8_BIT = VX_ENUM_BASE(VX_ID_TI, TIVX_ENUM_RAW_IMAGE_PIXEL_CONTAINER) + 0x1, TIVX_RAW_IMAGE_P12_BIT = VX_ENUM_BASE(VX_ID_TI, TIVX_ENUM_RAW_IMAGE_PIXEL_CONTAINER) + 0x2 }
	The raw image pixel container enum. More...

Functions
VX_API_ENTRY tivx_raw_image VX_API_CALL	tivxCreateRawImage (vx_context context, tivx_raw_image_create_params_t *params)
	Creates an opaque reference to a raw sensor image (including multi-exposure and metadata). More...

VX_API_ENTRY vx_status VX_API_CALL	tivxReleaseRawImage (tivx_raw_image *raw_image)
	Releases a reference of a raw image. The object may not be garbage collected until its total reference count is zero. After returning from this function the reference is zeroed. More...

VX_API_ENTRY vx_status VX_API_CALL	tivxQueryRawImage (tivx_raw_image raw_image, vx_enum attribute, volatile void *ptr, vx_size size)
	Queries the raw image for some specific information. More...

VX_API_ENTRY vx_status VX_API_CALL	tivxCopyRawImagePatch (tivx_raw_image raw_image, const vx_rectangle_t rect, vx_uint32 exposure_index, const vx_imagepatch_addressing_t user_addr, void *user_ptr, vx_enum usage, vx_enum mem_type, vx_enum buffer_select)
	Allows the application to copy a rectangular patch from/into a raw image object exposure. More...

VX_API_ENTRY vx_status VX_API_CALL	tivxMapRawImagePatch (tivx_raw_image raw_image, const vx_rectangle_t rect, vx_uint32 exposure_index, vx_map_id map_id, vx_imagepatch_addressing_t addr, void *user_ptr, vx_enum usage, vx_enum mem_type, vx_enum buffer_select)
	Allows the application to get direct access to a rectangular patch of a raw image object exposure. More...

VX_API_ENTRY vx_status VX_API_CALL	tivxUnmapRawImagePatch (tivx_raw_image raw_image, vx_map_id map_id)
	Unmap and commit potential changes to a raw image object patch that were previously mapped. More...

Macro Definition Documentation

◆ TIVX_TYPE_RAW_IMAGE

#define TIVX_TYPE_RAW_IMAGE 0x817

The object type enumeration for raw images.

A tivx_raw_image.

Definition at line 87 of file tivx_ext_raw_image.h.

◆ TIVX_ENUM_RAW_IMAGE_BUFFER_ACCESS

#define TIVX_ENUM_RAW_IMAGE_BUFFER_ACCESS (vx_enum)0x0

The enum type enumeration for raw images.

A tivx_raw_image_buffer_access_e.

Definition at line 93 of file tivx_ext_raw_image.h.

Enumeration Type Documentation

◆ tivx_raw_image_attribute_e

enum tivx_raw_image_attribute_e

The raw image attributes.

Enumerator
TIVX_RAW_IMAGE_WIDTH	Queries an image for its width. Read-only. Use a `vx_uint32` parameter.
TIVX_RAW_IMAGE_HEIGHT	Queries an image for its height. Read-only. Use a `vx_uint32` parameter.
TIVX_RAW_IMAGE_NUM_EXPOSURES	Queries an image for its number of exposures. Read-only. Use a `vx_uint32` parameter.
TIVX_RAW_IMAGE_LINE_INTERLEAVED	Queries an image for if its exposures are line interleaved in memory. Read-only. Use a `vx_bool` parameter.
TIVX_RAW_IMAGE_FORMAT	Queries an image for its format (see `tivx_raw_image_format_t`). Read-only. Use a pointer to a `tivx_raw_image_format_t` array.
TIVX_RAW_IMAGE_META_HEIGHT_BEFORE	Queries an image for its meta height at top of readout. Read-only. Use a `vx_uint32` parameter.
TIVX_RAW_IMAGE_META_HEIGHT_AFTER	Queries an image for its meta height at bottom of readout. Read-only. Use a `vx_uint32` parameter.
TIVX_RAW_IMAGE_IMAGEPATCH_ADDRESSING	Queries an image for its addressing structure. Read-only. Use a `vx_imagepatch_addressing_t[TIVX_RAW_IMAGE_MAX_EXPOSURES]` parameter.

Definition at line 138 of file tivx_ext_raw_image.h.

◆ tivx_raw_image_buffer_access_e

enum tivx_raw_image_buffer_access_e

The raw image buffer access enum.

Enumerator
TIVX_RAW_IMAGE_ALLOC_BUFFER	For accessing pointer to full allocated buffer (pixel buffer + meta buffer).
TIVX_RAW_IMAGE_PIXEL_BUFFER	For accessing pointer to pixel buffer only.
TIVX_RAW_IMAGE_META_BEFORE_BUFFER	For accessing pointer to meta buffer only.
TIVX_RAW_IMAGE_META_AFTER_BUFFER	For accessing pointer to meta buffer only.

Definition at line 160 of file tivx_ext_raw_image.h.

◆ tivx_raw_image_pixel_container_e

enum tivx_raw_image_pixel_container_e

The raw image pixel container enum.

Enumerator
TIVX_RAW_IMAGE_16_BIT	Two bytes per pixel in memory.
TIVX_RAW_IMAGE_8_BIT	One byte per pixel in memory.
TIVX_RAW_IMAGE_P12_BIT	Packed 12 bit mode; Three bytes per two pixels in memory.

Definition at line 174 of file tivx_ext_raw_image.h.

Function Documentation

◆ tivxCreateRawImage()

VX_API_ENTRY tivx_raw_image VX_API_CALL tivxCreateRawImage	(	vx_context	context,
		tivx_raw_image_create_params_t *	params
	)

Creates an opaque reference to a raw sensor image (including multi-exposure and metadata).

Not guaranteed to exist until the vx_graph containing it has been verified.

Parameters

[in]	context	The reference to the implementation context.
[in]	params	The pointer to a tivx_raw_image_create_params_t structure

Returns: A raw image reference tivx_raw_image. Any possible errors preventing a successful creation should be checked using vxGetStatus.

See also: tivxMapRawImagePatch to obtain direct memory access to the image data.

◆ tivxReleaseRawImage()

VX_API_ENTRY vx_status VX_API_CALL tivxReleaseRawImage ( tivx_raw_image * raw_image )

Releases a reference of a raw image. The object may not be garbage collected until its total reference count is zero. After returning from this function the reference is zeroed.

Parameters

[in] raw_image The pointer to the Raw Image Object to release.

Returns: A vx_status_e enumeration.

Return values

VX_SUCCESS	No errors.
VX_ERROR_INVALID_REFERENCE	If raw_image is not a `tivx_raw_image`.

◆ tivxQueryRawImage()

VX_API_ENTRY vx_status VX_API_CALL tivxQueryRawImage	(	tivx_raw_image	raw_image,
		vx_enum	attribute,
		volatile void *	ptr,
		vx_size	size
	)

Queries the raw image for some specific information.

Parameters

[in]	raw_image	The reference to the raw image.
[in]	attribute	The attribute to query. Use a `tivx_raw_image_attribute_e`.
[out]	ptr	The location at which to store the resulting value.
[in]	size	The size in bytes of the container to which ptr points.

Returns: A vx_status_e enumeration.

Return values

VX_SUCCESS	No errors.
VX_ERROR_INVALID_REFERENCE	If the raw_image is not a `tivx_raw_image`.
VX_ERROR_NOT_SUPPORTED	If the attribute is not a value supported on this implementation.
VX_ERROR_INVALID_PARAMETERS	If any of the other parameters are incorrect.

◆ tivxCopyRawImagePatch()

VX_API_ENTRY vx_status VX_API_CALL tivxCopyRawImagePatch	(	tivx_raw_image	raw_image,
		const vx_rectangle_t *	rect,
		vx_uint32	exposure_index,
		const vx_imagepatch_addressing_t *	user_addr,
		void *	user_ptr,
		vx_enum	usage,
		vx_enum	mem_type,
		vx_enum	buffer_select
	)

Allows the application to copy a rectangular patch from/into a raw image object exposure.

Parameters

[in]	raw_image	The reference to the raw image object that is the source or the destination of the copy.
[in]	rect	The coordinates of the image patch. The patch must be within the bounds of the image. (start_x, start_y) gives the coordinates of the topleft pixel inside the patch, while (end_x, end_y) gives the coordinates of the bottomright element out of the patch. Must be 0 <= start < end <= number of pixels in the image dimension. Only valid when buffer_select is TIVX_RAW_IMAGE_PIXEL_BUFFER.
[in]	exposure_index	The exposure index of the raw image object that is the source or the destination of the patch copy.
[in]	user_addr	The address of a structure describing the layout of the user memory location pointed by user_ptr. In the structure, only dim_x, dim_y, stride_x and stride_y fields must be provided, other fields are ignored by the function. The layout of the user memory must follow a row major order: stride_x == pixel size in bytes, and stride_y >= stride_x * dim_x. When buffer_select is not TIVX_RAW_IMAGE_PIXEL_BUFFER, only dim_x is valid (number of bytes).
[in]	user_ptr	The address of the memory location where to store the requested data if the copy was requested in read mode, or from where to get the data to store into the image object if the copy was requested in write mode. The accessible memory must be large enough to contain the specified patch with the specified layout: accessible memory in bytes >= (end_y - start_y) * stride_y.
[in]	usage	This declares the effect of the copy with regard to the image object using the `vx_accessor_e` enumeration. Only VX_READ_ONLY and VX_WRITE_ONLY are supported: VX_READ_ONLY means that data is copied from the image object into the application memory VX_WRITE_ONLY means that data is copied into the image object from the application memory
[in]	mem_type	A `vx_memory_type_e` enumeration that specifies the memory type of the memory referenced by the user_addr.
[in]	buffer_select	A `tivx_raw_image_buffer_access_e` enumeration that specifies the buffer to copy to/from.

Returns: A vx_status_e enumeration.

Return values

VX_ERROR_OPTIMIZED_AWAY	This is a reference to a virtual raw image that cannot be accessed by the application.
VX_ERROR_INVALID_REFERENCE	The raw image reference is not actually a raw image reference.
VX_ERROR_INVALID_PARAMETERS	An other parameter is incorrect.

Note: The application may ask for data outside the bounds of the valid region, but such data has an undefined value.

◆ tivxMapRawImagePatch()

VX_API_ENTRY vx_status VX_API_CALL tivxMapRawImagePatch	(	tivx_raw_image	raw_image,
		const vx_rectangle_t *	rect,
		vx_uint32	exposure_index,
		vx_map_id *	map_id,
		vx_imagepatch_addressing_t *	addr,
		void **	user_ptr,
		vx_enum	usage,
		vx_enum	mem_type,
		vx_enum	buffer_select
	)

Allows the application to get direct access to a rectangular patch of a raw image object exposure.

Parameters

[in]	raw_image	The reference to the raw image object that contains the patch to map.
[in]	rect	The coordinates of raw image patch. The patch must be within the bounds of the image. (start_x, start_y) gives the coordinate of the topleft element inside the patch, while (end_x, end_y) give the coordinate of the bottomright element out of the patch. Must be 0 <= start < end. Only valid when buffer_select is TIVX_RAW_IMAGE_PIXEL_BUFFER.
[in]	exposure_index	The exposure index of the image object to be accessed.
[out]	map_id	The address of a vx_map_id variable where the function returns a map identifier. (*map_id) must eventually be provided as the map_id parameter of a call to `tivxUnmapRawImagePatch`.
[out]	addr	The address of a structure describing the memory layout of the image patch to access. The function fills the structure pointed by addr with the layout information that the application must consult to access the pixel data at address (user_ptr). The layout of the mapped memory follows a row-major order: stride_x>0, stride_y>0 and stride_y >= stride_x dim_x. When buffer_select is not TIVX_RAW_IMAGE_PIXEL_BUFFER, only dim_x is valid (number of bytes).
[out]	user_ptr	The address of a pointer that the function sets to the address where the requested data can be accessed. This returned (*ptr) address is only valid between the call to this function and the corresponding call to `tivxUnmapRawImagePatch`.
[in]	usage	This declares the access mode for the image patch, using the `vx_accessor_e` enumeration. VX_READ_ONLY: after the function call, the content of the memory location pointed by (ptr) contains the image patch data. Writing into this memory location is forbidden and its behavior is undefined. VX_READ_AND_WRITE : after the function call, the content of the memory location pointed by (ptr) contains the image patch data; writing into this memory is allowed only for the location of pixels only and will result in a modification of the written pixels in the image object once the patch is unmapped. Writing into a gap between lines (when addr->stride_y > addr->stride_xaddr->dim_x) is forbidden and its behavior is undefined. VX_WRITE_ONLY: after the function call, the memory location pointed by (ptr) contains undefined data; writing each pixel of the patch is required prior to unmapping. Pixels not written by the application before unmap will become undefined after unmap, even if they were well defined before map. Like for VX_READ_AND_WRITE, writing into a gap between pixels is forbidden and its behavior is undefined.
[in]	mem_type	A `vx_memory_type_e` enumeration that specifies the type of the memory where the image patch is requested to be mapped.
[in]	buffer_select	A `tivx_raw_image_buffer_access_e` enumeration that specifies the buffer to map.

Returns: A vx_status_e enumeration.

Return values

VX_ERROR_OPTIMIZED_AWAY	This is a reference to a virtual raw image that cannot be accessed by the application.
VX_ERROR_INVALID_REFERENCE	The raw image reference is not actually a raw image reference.
VX_ERROR_INVALID_PARAMETERS	An other parameter is incorrect.

Note: The user may ask for data outside the bounds of the valid region, but such data has an undefined value.

Postcondition: tivxUnmapRawImagePatch with same (*map_id) value.

◆ tivxUnmapRawImagePatch()

VX_API_ENTRY vx_status VX_API_CALL tivxUnmapRawImagePatch	(	tivx_raw_image	raw_image,
		vx_map_id	map_id
	)

Unmap and commit potential changes to a raw image object patch that were previously mapped.

Unmapping a raw image patch invalidates the memory location from which the patch could be accessed by the application. Accessing this memory location after the unmap function completes has an undefined behavior.

Parameters

[in]	raw_image	The reference to the raw image object to unmap.
[out]	map_id	The unique map identifier that was returned by `tivxMapRawImagePatch`

Returns: A vx_status_e enumeration.

Return values

VX_ERROR_INVALID_REFERENCE	The raw image reference is not actually a raw image reference.
VX_ERROR_INVALID_PARAMETERS	An other parameter is incorrect.

Precondition: tivxMapRawImagePatch with same map_id value

Detailed Description

Data Structures

Defines

Typedefs

Enumerations

Functions

Macro Definition Documentation

◆ TIVX_TYPE_RAW_IMAGE

◆ TIVX_ENUM_RAW_IMAGE_BUFFER_ACCESS

Enumeration Type Documentation

◆ tivx_raw_image_attribute_e

◆ tivx_raw_image_buffer_access_e

◆ tivx_raw_image_pixel_container_e

Function Documentation

◆ tivxCreateRawImage()

◆ tivxReleaseRawImage()

◆ tivxQueryRawImage()

◆ tivxCopyRawImagePatch()

◆ tivxMapRawImagePatch()

◆ tivxUnmapRawImagePatch()