NVIDIA DRIVE OS Linux SDK API Reference

5.2.0 Release
For Test and Development only
nvmedia_image.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2013-2020, NVIDIA CORPORATION. All rights reserved. All
3  * information contained herein is proprietary and confidential to NVIDIA
4  * Corporation. Any use, reproduction, or disclosure without the written
5  * permission of NVIDIA Corporation is prohibited.
6  */
7 
16 #ifndef NVMEDIA_IMAGE_H
17 #define NVMEDIA_IMAGE_H
18 
19 #ifdef __cplusplus
20 extern "C" {
21 #endif
22 
23 #include "nvmedia_core.h"
24 #include "nvmedia_surface.h"
25 
38 #define NVMEDIA_IMAGE_VERSION_MAJOR (1u)
39 
40 #define NVMEDIA_IMAGE_VERSION_MINOR (24u)
41 
60 #define NVMEDIA_MAX_IMAGE_GROUP_SIZE (3u)
61 
66 #define NVMEDIA_IMAGE_TIMEOUT_INFINITE (0xFFFFFFFFu)
67 
77  uint32_t width;
80  uint32_t height;
91  uint32_t colorStd;
94  void *tag;
97 #if (NV_IS_SAFETY == 0)
98 
99  uint32_t imageCount;
101  uint32_t attributes;
104 #endif
105 
107  struct NvMediaImagePriv_ *imgPriv;
108 };
109 
111 
115 typedef struct {
119  uint32_t numImages;
122  void *tag;
127 
137  NvMediaVersion *version
138 );
139 
140 #if (NV_IS_SAFETY == 0)
141 
152 NvMediaImage *
154  NvMediaDevice *device,
156  const NvMediaSurfAllocAttr *attrs,
157  uint32_t numAttrs,
158  uint32_t flags
159 );
160 #endif
161 
167 void
169  const NvMediaImage *image
170 );
171 
236  const NvMediaImage *image,
237  uint32_t imageIndex,
238  uint8_t *embeddedBufTop,
239  uint32_t *embeddedBufTopSize,
240  uint8_t *embeddedBufBottom,
241  uint32_t *embeddedBufBottomSize
242 );
243 
264  const NvMediaImage *image,
265  uint32_t millisecondWait,
266  NvMediaTaskStatus *taskStatus
267 );
268 
286  NvMediaImage *image,
287  void *tag
288 );
289 
306  const NvMediaImage *image,
307  void **tag
308 );
309 
310 #if (NV_IS_SAFETY == 0)
311 
322  const NvMediaImage *image,
323  NvMediaTime *timeStamp
324 );
325 
340  const NvMediaImage *image,
341  NvMediaGlobalTime *globalTimeStamp
342 );
343 
356 typedef enum {
364 
369 typedef struct {
371  uint32_t pitch;
373  void *mapping;
375 
382 typedef struct {
386  uint32_t width;
388  uint32_t height;
390  uint32_t surfaces;
395  void *metaData;
397 
421  const NvMediaImage *image,
422  NvMediaImageLockAccess lockAccessType,
423  NvMediaImageSurfaceMap *surfaceMap
424 );
425 
432 void
434  const NvMediaImage *image
435 );
436 
512  NvMediaImage *image,
513  const NvMediaRect *dstRect,
514  void **srcPntrs,
515  const uint32_t *srcPitches
516 );
517 
580  const NvMediaImage *image,
581  const NvMediaRect *srcRect,
582  void **dstPntrs,
583  const uint32_t *dstPitches
584 );
585 #endif
586 
589 /*
590  * \defgroup history_nvmedia_image History
591  * Provides change history for the NvMedia Image API.
592  *
593  * \section history_nvmedia_image Version History
594  *
595  * <b> Version 1.1 </b> March 3, 2016
596  * - Initial release
597  *
598  * <b> Version 1.2 </b> May 11, 2016
599  * - Added \ref NvMediaImageCheckVersion API
600  *
601  * <b> Version 1.3 </b> Jan 17, 2017
602  * - Added atrribute NVMEDIA_IMAGE_ATTRIBUTE_CAPTURE in \ref NvMediaImageAttributes
603  *
604  * <b> Version 1.4 </b> Feb 9, 2017
605  * - Added new APIs
606  * NvMediaImageCreateNew()
607  *
608  * <b> Version 1.5 </b> March 16, 2017
609  * - Added \ref NVMEDIA_BITS_PER_PIXEL_16 in \ref NvMediaBitsPerPixel
610  *
611  * <b> Version 1.6 </b> May 9, 2017
612  * - Deprecated the following APIs
613  * - NvMediaImageAcquire
614  * - NvMediaImageRelease
615  * - NvMediaImageWaitForIdle
616  * - NvMediaImageWaitForCompletion
617  * - NvMediaImageCheckVersion
618  * - NvMediaImageGetVersion() is added to get the version of NvMedia Image library
619  * - All NvMedia data types are moved to standard data types
620  *
621  * <b> Version 1.7 </b> May 14, 2017
622  * - Added API to get status of operation on an image. \ref NvMediaImageGetStatus
623  *
624  * <b> Version 1.8 </b> May 15, 2017
625  * - Added deprecated warning message for \ref NvMediaImageCreate,
626  * \ref NvMediaImageSiblingCreate, \ref NvMediaImageSiblingDestroy,
627  * \ref NvMediaVideoCreateImageSibling, \ref NvMediaImageCreateVideoSibling
628  *
629  * <b> Version 1.9 </b> May 18, 2017
630  * - Added colorStd member in \ref NvMediaImage
631  *
632  * <b> Version 1.10 </b> June 12, 2017
633  * - Added \ref NvMediaImageGroup to hold a list of NvMediaImages.
634  *
635  * <b> Version 1.11 </b> September 12, 2017
636  * - Deprecated \ref NvMediaImageClass, \ref NvMediaImageAttributes, \ref NvMediaImageAdvancedConfig
637  * - Deprecated \ref NvMediaImageCreate, \ref NvMediaImageSiblingCreate,
638  * \ref NvMediaVideoCreateImageSibling, \ref NvMediaImageSiblingDestroy,
639  * \ref NvMediaImageCreateVideoSibling, \ref NvMediaVideoSurfaceSiblingDestroy
640  *
641  * <b> Version 1.12 </b> Dec 06, 2018
642  * - Fixed MISRA-C rule 10.4, 20.7 and 21.1 violations
643  * resulting from this header.
644  *
645  * <b> Version 1.13 </b> January 16, 2019
646  * Updated desciption for \ref NvMediaImageGetBits and \ref NvMediaImagePutBits
647  *
648  * <b> Version 1.14 </b> March 13, 2019
649  * - Data type of lockAcessType in NvMediaImageLock Api
650  is changed from unit32_t to NvMediaImageLockAccess.
651  *
652  * <b> Version 1.15 </b> March 16, 2019
653  * - Add required header include nvmedia_surface.h
654  *
655  * <b> Version 1.16 </b> March 20, 2019
656  * - Added \ref NvMediaImageSetTag and \ref NvMediaImageGetTag APIs
657  * - Tag member of NvMedia Image will be deprecated in later release.
658  *
659  * <b> Version 1.17 </b> March 22, 2019
660  * - Added \ref NVMEDIA_RAW_PIXEL_ORDER_RCCB, \ref NVMEDIA_RAW_PIXEL_ORDER_BCCR,
661  * \ref NVMEDIA_RAW_PIXEL_ORDER_CRBC, \ref NVMEDIA_RAW_PIXEL_ORDER_CBRC, and
662  * \ref NVMEDIA_RAW_PIXEL_ORDER_COUNT
663  * in \ref NvMediaRawPixelOrder
664  *
665  * <b> Version 1.18 </b> March 25, 2019
666  * - Added opaque pointer for image structure
667  * - Fixed MISRA-C rule 8.13 violations resulting from this header.
668  *
669  *<b> Version 1.19 </b> March 28, 2019
670  * - Unnecessary header include nvmedia_video.h has been removed
671  *
672  * <b> Version 1.20 </b> March 29, 2019
673  * - Added captureTimeStamp to \ref NvMediaImageGroup to hold timestamps
674  *
675  *<b> Version 1.21 </b> March 28, 2019
676  * - Move NvMediaBitsPerPixel and NVMEDIA_MAX_AGGREGATE_IMAGES to nvmedia_icp.h
677  * - Move NvMediaRawPixelOrder to nvmedia_ipp.h
678  *
679  *<b> Version 1.22 </b> Dec 24, 2019
680  * - Bypassed non-safety functions and non-safety NvMediaImage struct members
681  * using NV_IS_SAFETY macro to resolve MISRA-C rule 8.6 violations
682  * - Fixed MISRA 2.4 for unused NvMediaImageRec tag.
683  * - Changed arg type of NvMediaImageGetEmbeddedData from void* to unit8_t*.
684  *
685  *<b> Version 1.23 </b> Jan 23, 2020
686  * Modify comments: Add warning for lock/unlock APIs and format support info in
687  * GetEmbeddedData
688  *
689  *<b> Version 1.24 </b> Feb 7, 2020
690  * Removed non-safety debug APIs on safety build
691  *
692  */
693 
694 #ifdef __cplusplus
695 }; /* extern "C" */
696 #endif
697 
698 #endif /* NVMEDIA_IMAGE_H */
NvMediaTime
struct timespec NvMediaTime
Holds the media time in timespec format as defined by the POSIX specification.
Definition: nvmedia_core.h:85
NvMediaImageRec::height
uint32_t height
Holds image height.
Definition: nvmedia_image.h:80
nvmedia_surface.h
NVIDIA Media Interface: Surface Handling
NVMEDIA_IMAGE_ACCESS_READ
@ NVMEDIA_IMAGE_ACCESS_READ
Specifies read access.
Definition: nvmedia_image.h:358
NvMediaImageRec::colorStd
uint32_t colorStd
Holds an image color standard type.
Definition: nvmedia_image.h:91
NvMediaImageRec::captureGlobalTimeStamp
NvMediaGlobalTime captureGlobalTimeStamp
Holds an image capture global timestamp in microseconds.
Definition: nvmedia_image.h:96
NvMediaGlobalTime
uint64_t NvMediaGlobalTime
Media global time, measured in microseconds.
Definition: nvmedia_core.h:90
NvMediaImageGetBits
NvMediaStatus NvMediaImageGetBits(const NvMediaImage *image, const NvMediaRect *srcRect, void **dstPntrs, const uint32_t *dstPitches)
Reads an NvMedia image and writes the content into a client memory buffer.
NvMediaImageRec::imageCount
uint32_t imageCount
Holds the number of images stored in this image container.
Definition: nvmedia_image.h:99
NvMediaImageRec::captureTimeStamp
NvMediaTime captureTimeStamp
Holds an image capture timestamp.
Definition: nvmedia_image.h:103
NvMediaImageGetTag
NvMediaStatus NvMediaImageGetTag(const NvMediaImage *image, void **tag)
Gets the tag from an NvMediaImage.
NvMediaImageGetGlobalTimeStamp
NvMediaStatus NvMediaImageGetGlobalTimeStamp(const NvMediaImage *image, NvMediaGlobalTime *globalTimeStamp)
Gets the global capture timestamp of the image.
NvMediaImageDestroy
void NvMediaImageDestroy(const NvMediaImage *image)
Destroys an NvMediaImage object.
NvMediaImageUnlock
void NvMediaImageUnlock(const NvMediaImage *image)
Unlocks an image.
NvMediaImagePutBits
NvMediaStatus NvMediaImagePutBits(NvMediaImage *image, const NvMediaRect *dstRect, void **srcPntrs, const uint32_t *srcPitches)
Reads a client memory buffer and writes the content into an NvMedia image surface.
NvMediaDevice
struct NvMediaDevice NvMediaDevice
An opaque handle representing an NvMediaDevice object.
Definition: nvmedia_core.h:348
NvMediaImageSurface::pitch
uint32_t pitch
Holds pitch of the surface.
Definition: nvmedia_image.h:371
NvMediaImageLockAccess
NvMediaImageLockAccess
Specifies image lock access types.
Definition: nvmedia_image.h:356
NVMEDIA_MAX_IMAGE_GROUP_SIZE
#define NVMEDIA_MAX_IMAGE_GROUP_SIZE
Maximum number of images in an image group.
Definition: nvmedia_image.h:60
NvMediaVersion
Holds NvMedia version information.
Definition: nvmedia_core.h:237
NvMediaImageRec::embeddedDataBottomSize
uint32_t embeddedDataBottomSize
Holds the size of the bottom embedded data.
Definition: nvmedia_image.h:88
NvMediaImageSurfaceMap::type
NvMediaSurfaceType type
Holds image surface type.
Definition: nvmedia_image.h:384
NVMEDIA_IMAGE_ACCESS_READ_WRITE
@ NVMEDIA_IMAGE_ACCESS_READ_WRITE
Specifies read/write access.
Definition: nvmedia_image.h:362
NvMediaImageSurface
Holds an image surface descriptor used by NvMediaImageLock().
Definition: nvmedia_image.h:369
type
int const char int type
Definition: drm-nvdc-docs.h:1479
NvMediaImageRec
Holds a handle representing image objects.
Definition: nvmedia_image.h:71
NvMediaImageRec::tag
void * tag
Definition: nvmedia_image.h:94
NvMediaImageSurfaceMap::metaData
void * metaData
Holds a pointer to metadata associated with the surface.
Definition: nvmedia_image.h:395
NVMEDIA_IMAGE_ACCESS_WRITE
@ NVMEDIA_IMAGE_ACCESS_WRITE
Specifies write access.
Definition: nvmedia_image.h:360
NvMediaImageGetVersion
NvMediaStatus NvMediaImageGetVersion(NvMediaVersion *version)
Gets the version of the NvMedia Image library.
NvMediaImageSurfaceMap
Holds an image surface map descriptor used by NvMediaImageLock().
Definition: nvmedia_image.h:382
NvMediaImageRec::embeddedDataTopSize
uint32_t embeddedDataTopSize
Holds the size of the top embedded data.
Definition: nvmedia_image.h:84
NvMediaRect
Holds a rectangular region of a surface.
Definition: nvmedia_core.h:133
nvmedia_core.h
NVIDIA Media Interface: Core
NvMediaSurfaceType
#define NvMediaSurfaceType
Defines the set of NvMedia surface types.
Definition: nvmedia_surface.h:550
NvMediaImageRec::type
NvMediaSurfaceType type
Holds image surface type.
Definition: nvmedia_image.h:74
NvMediaImageCreateNew
NvMediaImage * NvMediaImageCreateNew(NvMediaDevice *device, NvMediaSurfaceType type, const NvMediaSurfAllocAttr *attrs, uint32_t numAttrs, uint32_t flags)
Allocates an image object.
NvMediaStatus
NvMediaStatus
Defines all possible error codes.
Definition: nvmedia_core.h:180
NvMediaImageRec::imgPriv
struct NvMediaImagePriv_ * imgPriv
Holds an opaque pointer for internal use.
Definition: nvmedia_image.h:107
NvMediaImageSurfaceMap::surfaces
uint32_t surfaces
Holds the number of surfaces in the image.
Definition: nvmedia_image.h:390
NvMediaImageSurfaceMap::width
uint32_t width
Holds image width.
Definition: nvmedia_image.h:386
NvMediaImageLock
NvMediaStatus NvMediaImageLock(const NvMediaImage *image, NvMediaImageLockAccess lockAccessType, NvMediaImageSurfaceMap *surfaceMap)
Locks an image and returns the associated mapped pointers to the image surface data.
NvMediaImageGroup::numImages
uint32_t numImages
Holds the number of NvMedia images in the group.
Definition: nvmedia_image.h:119
NvMediaImageRec::width
uint32_t width
Holds image width.
Definition: nvmedia_image.h:77
NvMediaImageGroup::tag
void * tag
Holds a tag for use by the application.
Definition: nvmedia_image.h:122
NvMediaSurfAllocAttr
Holds NvMedia Surface allocation attributes.
Definition: nvmedia_surface.h:540
NvMediaImageGetTimeStamp
NvMediaStatus NvMediaImageGetTimeStamp(const NvMediaImage *image, NvMediaTime *timeStamp)
Gets the capture timestamp of the image.
NvMediaImageSurfaceMap::height
uint32_t height
Holds image height.
Definition: nvmedia_image.h:388
NvMediaImageGroup
Holds a handle representing an image group.
Definition: nvmedia_image.h:115
NvMediaImageSetTag
NvMediaStatus NvMediaImageSetTag(NvMediaImage *image, void *tag)
Sets a tag for an NvMediaImage.
NvMediaTaskStatus
Holds status of latest operation for NvMedia managed data structure.
Definition: nvmedia_core.h:220
NvMediaImageGetStatus
NvMediaStatus NvMediaImageGetStatus(const NvMediaImage *image, uint32_t millisecondWait, NvMediaTaskStatus *taskStatus)
Gets status of the current or most recent operation for an image; optionally waits for the current op...
NvMediaImageGetEmbeddedData
NvMediaStatus NvMediaImageGetEmbeddedData(const NvMediaImage *image, uint32_t imageIndex, uint8_t *embeddedBufTop, uint32_t *embeddedBufTopSize, uint8_t *embeddedBufBottom, uint32_t *embeddedBufBottomSize)
Returns embedded data stored in a captured image.
NvMediaImageSurface::mapping
void * mapping
Holds a CPU accessible memory pointer to the surface.
Definition: nvmedia_image.h:373
NvMediaImageRec::attributes
uint32_t attributes
Holds image attributes.
Definition: nvmedia_image.h:101