Image Locking and Unlocking

Detailed Description

Locking and unlocking controls access to the image surfaces.

Warning

These functions are for diagnostics purposes only. They are not for use in production code.

Data Structures
struct	NvMediaImageSurface
	Holds an image surface descriptor used by NvMediaImageLock(). More...
struct	NvMediaImageSurfaceMap
	Holds an image surface map descriptor used by NvMediaImageLock(). More...
struct	NvMediaTensorSurfaceMap
	Defines the tensor surface map descriptor used by NvMediaTensorLock(). More...

Enumerations
enum	NvMediaImageLockAccess {   NVMEDIA_IMAGE_ACCESS_READ = (1u << 0),   NVMEDIA_IMAGE_ACCESS_WRITE = (1u << 1),   NVMEDIA_IMAGE_ACCESS_READ_WRITE = (NVMEDIA_IMAGE_ACCESS_READ | NVMEDIA_IMAGE_ACCESS_WRITE) }
	Specifies image lock access types. More...
enum	NvMediaArrayLockAccess {   NVMEDIA_ARRAY_ACCESS_READ = 1,   NVMEDIA_ARRAY_ACCESS_WRITE = 2,   NVMEDIA_ARRAY_ACCESS_READ_WRITE = 3 }
	Defines array-lock access types. More...
enum	NvMediaTensorLockAccess {   NVMEDIA_TENSOR_ACCESS_READ = (1 << 0),   NVMEDIA_TENSOR_ACCESS_WRITE = (1 << 1),   NVMEDIA_TENSOR_ACCESS_READ_WRITE = (NVMEDIA_TENSOR_ACCESS_READ | NVMEDIA_TENSOR_ACCESS_WRITE) }
	Defines tensor lock access types. More...

Functions
NvMediaStatus	NvMediaImageLock (const NvMediaImage *image, NvMediaImageLockAccess lockAccessType, NvMediaImageSurfaceMap *surfaceMap)
	Locks an image and returns the associated mapped pointers to the image surface data. More...
void	NvMediaImageUnlock (const NvMediaImage *image)
	Unlocks an image. More...
NvMediaStatus	NvMediaArrayLock (NvMediaArray *handle, NvMediaArrayLockAccess lockAccessType, void **ptr)
	Locks an array. More...
void	NvMediaArrayUnlock (NvMediaArray *handle)
	Unlocks an array. More...
NvMediaStatus	NvMediaImagePyramidLock (NvMediaImagePyramid *pyramid, uint32_t lockAccessType, NvMediaImageSurfaceMap *surfaceMap)
	Locks an image pyramid and returns the associated mapped pointers to the image pyramid surface data. More...
void	NvMediaImagePyramidUnlock (NvMediaImagePyramid *pyramid)
	Unlocks an image pyramid. More...
NvMediaStatus	NvMediaTensorLock (NvMediaTensor *tensor, NvMediaTensorLockAccess lockAccessType, NvMediaTensorSurfaceMap *surfaceMap)
	Locks a tensor and returns the associated mapped pointers pointing to the tensor surface data. More...
void	NvMediaTensorUnlock (NvMediaTensor *tensor)
	Unlocks a tensor. More...

Enumeration Type Documentation

NvMediaArrayLockAccess

enum NvMediaArrayLockAccess

Defines array-lock access types.

Enumerator
NVMEDIA_ARRAY_ACCESS_READ	Specifies read access.
NVMEDIA_ARRAY_ACCESS_WRITE	Specifies write access.
NVMEDIA_ARRAY_ACCESS_READ_WRITE	Specifies read/write access.

Definition at line 119 of file nvmedia_array.h.

NvMediaImageLockAccess

enum NvMediaImageLockAccess

Specifies image lock access types.

Enumerator
NVMEDIA_IMAGE_ACCESS_READ	Specifies read access.
NVMEDIA_IMAGE_ACCESS_WRITE	Specifies write access.
NVMEDIA_IMAGE_ACCESS_READ_WRITE	Specifies read/write access.

Definition at line 353 of file nvmedia_image.h.

NvMediaTensorLockAccess

enum NvMediaTensorLockAccess

Defines tensor lock access types.

Enumerator
NVMEDIA_TENSOR_ACCESS_READ	Read access.
NVMEDIA_TENSOR_ACCESS_WRITE	Write access.
NVMEDIA_TENSOR_ACCESS_READ_WRITE	Read/Write access.

Definition at line 235 of file nvmedia_tensor.h.

Function Documentation

NvMediaArrayLock()

NvMediaStatus NvMediaArrayLock	(	NvMediaArray *	handle,
		NvMediaArrayLockAccess	lockAccessType,
		void **	ptr
	)

Locks an array.

A client can read or write a locked array without interference from another thread or process.

If the array is being used by an internal engine, this function waits until the operation is completed.

Parameters

[in]	handle	Handle to the array to be locked.
[in]	lockAccessType	Specifies the access type. The following access types are supported, and may be OR'd together: NVMEDIA_ARRAY_ACCESS_READ specifies read access. NVMEDIA_ARRAY_ACCESS_WRITE specifies write access. NVMEDIA_ARRAY_ACCESS_READ_WRITE Specifies read/write access.
[out]	ptr	A CPU mapped pointer which may be used to read or write data.

Returns

A status code; NVMEDIA_STATUS_OK if the call is successful, or NVMEDIA_STATUS_ERROR otherwise.

NvMediaArrayUnlock()

void NvMediaArrayUnlock

(

NvMediaArray *

handle

)

Unlocks an array.

Call this function when the client has finished writing to or reading from the array.

Parameters

[in]

handle

Handle to the array to be unlocked.

NvMediaImageLock()

NvMediaStatus NvMediaImageLock	(	const NvMediaImage *	image,
		NvMediaImageLockAccess	lockAccessType,
		NvMediaImageSurfaceMap *	surfaceMap
	)

Locks an image and returns the associated mapped pointers to the image surface data.

Only images created without the NVM_SURF_ATTR_CPU_ACCESS_UNMAPPED attribute can be accessed by the CPU. If an image is being used by an internal engine, this function waits until the operation is completed.

Parameters

[in]	image	A pointer to the image object.
[in]	lockAccessType	Determines the access type. The following access types are supported, and may be OR'd together: NVMEDIA_IMAGE_ACCESS_READ specifies read access. NVMEDIA_IMAGE_ACCESS_WRITE Specifies write access. NVMEDIA_IMAGE_ACCESS_READ_WRITE specifies read/write access.
[out]	surfaceMap	A pointer to surface descriptors.

Returns

A status code; NVMEDIA_STATUS_OK if the call was successful, NVMEDIA_STATUS_BAD_PARAMETER if the arguments to the function are invalid, or NVMEDIA_STATUS_ERROR otherwise.

NvMediaImagePyramidLock()

NvMediaStatus NvMediaImagePyramidLock	(	NvMediaImagePyramid *	pyramid,
		uint32_t	lockAccessType,
		NvMediaImageSurfaceMap *	surfaceMap
	)

Locks an image pyramid and returns the associated mapped pointers to the image pyramid surface data.

The CPU can only access images created without the NVM_SURF_ATTR_CPU_ACCESS_UNMAPPED attribute. If an image is being used by an internal engine. this function waits until the operation is completed.

Parameters

[in]	pyramid	A handle to the image pyramid object
[in]	lockAccessType	Determines the access type. The following access types are supported, and may be OR'd together: NVMEDIA_IMAGE_ACCESS_READ for read access. NVMEDIA_IMAGE_ACCESS_WRITE for write access. NVMEDIA_IMAGE_ACCESS_READ_WRITE for read/write access.
[out]	surfaceMap	Pointer to an array of surface descriptors per level.

Returns

A status code; NVMEDIA_STATUS_OK if the call was successful, or NVMEDIA_STATUS_ERROR otherwise.

NvMediaImagePyramidUnlock()

void NvMediaImagePyramidUnlock

(

NvMediaImagePyramid *

pyramid

)

Unlocks an image pyramid.

Internal engines cannot use a surface until it is locked.

Parameters

[in]

pyramid

A handle to the pyramid object to be unlocked.

NvMediaImageUnlock()

void NvMediaImageUnlock

(

const NvMediaImage *

image

)

Unlocks an image.

Internal engines cannot use a surface until it is locked.

Parameters

[in]

image

A pointer to the image object to be unlocked.

NvMediaTensorLock()

NvMediaStatus NvMediaTensorLock	(	NvMediaTensor *	tensor,
		NvMediaTensorLockAccess	lockAccessType,
		NvMediaTensorSurfaceMap *	surfaceMap
	)

Locks a tensor and returns the associated mapped pointers pointing to the tensor surface data.

The CPU can only access tensors created with the NVM_TENSOR_ATTR_CPU_ACCESS_UNCACHED or NVM_TENSOR_ATTR_CPU_ACCESS_CACHED attributes.

If a tensor is currently in use by an internal engine, this function waits until the operation completes.

Parameters

[in]	tensor	A pointer to the tensor object.
[in]	lockAccessType	Specifies the access type. The following access types are supported: NVMEDIA_TENSOR_ACCESS_READ Read access NVMEDIA_TENSOR_ACCESS_WRITE Write access NVMEDIA_TENSOR_ACCESS_READ_WRITE Read/Write access
[out]	surfaceMap	A pointer to the surface descriptors.

Returns

NvMediaStatus The completion status of the operation:

• NVMEDIA_STATUS_OK if the function is successful.
• NVMEDIA_STATUS_BAD_PARAMETER if any of the arguments are NULL or invalid.
• NVMEDIA_STATUS_TIMED_OUT if the syncpoint wait timed out
• NVMEDIA_STATUS_ERROR if an error occurred.

NvMediaTensorUnlock()

void NvMediaTensorUnlock

(

NvMediaTensor *

tensor

)

Unlocks a tensor.

Internal engines should not use a surface until the tensor is locked.

Parameters

[in]

tensor

The tensor object to unlock.