nvmedia_image.h

Go to the documentation of this file.

/*
 * Copyright (c) 2013-2022, NVIDIA CORPORATION.  All rights reserved.  All
 * information contained herein is proprietary and confidential to NVIDIA
 * Corporation.  Any use, reproduction, or disclosure without the written
 * permission of NVIDIA Corporation is prohibited.
 */
 
#ifndef NVMEDIA_IMAGE_H
#define NVMEDIA_IMAGE_H
 
#ifdef __cplusplus
extern "C" {
#endif
 
#include "nvmedia_core.h"
#include "nvmedia_surface.h"
 
#define NVMEDIA_IMAGE_VERSION_MAJOR   (1u)
 
#define NVMEDIA_IMAGE_VERSION_MINOR   (27u)
 
#define NVMEDIA_MAX_IMAGE_GROUP_SIZE   (3u)
 
#define NVMEDIA_IMAGE_TIMEOUT_INFINITE  (0xFFFFFFFFu)
 
struct NvMediaImageRec {
    NvMediaSurfaceType type;
    uint32_t width;
    uint32_t height;
    uint32_t embeddedDataTopSize;
    uint32_t embeddedDataBottomSize;
    uint32_t colorStd;
    void *tag;
    NvMediaGlobalTime captureGlobalTimeStamp;
#if (NV_IS_SAFETY == 0)
 
    uint32_t imageCount;
    uint32_t attributes;
    NvMediaTime captureTimeStamp;
#endif
 
    struct NvMediaImagePriv_ *imgPriv;
};
 
typedef struct NvMediaImageRec NvMediaImage;
 
typedef struct {
    NvMediaImage *imageList[NVMEDIA_MAX_IMAGE_GROUP_SIZE];
    uint32_t numImages;
    void *tag;
    uint64_t captureTimeStamp[NVMEDIA_MAX_IMAGE_GROUP_SIZE];
    uint64_t sofTimeStamp[NVMEDIA_MAX_IMAGE_GROUP_SIZE];
} NvMediaImageGroup;
 
NvMediaStatus
NvMediaImageGetVersion(
    NvMediaVersion *version
);
 
#if (NV_IS_SAFETY == 0)
 
NvMediaImage *
NvMediaImageCreateNew(
    NvMediaDevice *device,
    NvMediaSurfaceType type,
    const NvMediaSurfAllocAttr *attrs,
    uint32_t numAttrs,
    uint32_t flags
);
#endif
 
void
NvMediaImageDestroy(
    const NvMediaImage *image
);
 
NvMediaStatus
NvMediaImageGetEmbeddedData(
    const NvMediaImage *image,
    uint32_t imageIndex,
    uint8_t *embeddedBufTop,
    uint32_t *embeddedBufTopSize,
    uint8_t *embeddedBufBottom,
    uint32_t *embeddedBufBottomSize
);
 
NvMediaStatus
NvMediaImageGetStatus(
    const NvMediaImage *image,
    uint32_t millisecondWait,
    NvMediaTaskStatus *taskStatus
);
 
NvMediaStatus
NvMediaImageSetTag(
    NvMediaImage *image,
    void *tag
);
 
NvMediaStatus
NvMediaImageGetTag(
    const NvMediaImage *image,
    void **tag
);
 
#if (NV_IS_SAFETY == 0)
 
NvMediaStatus
NvMediaImageGetTimeStamp(
    const NvMediaImage *image,
    NvMediaTime *timeStamp
);
 
NvMediaStatus
NvMediaImageGetGlobalTimeStamp(
    const NvMediaImage *image,
    NvMediaGlobalTime *globalTimeStamp
);
 
NvMediaStatus
NvMediaImageGetTimeBase(
    const NvMediaImage *image,
    NvMediaTimeBase *timeBase
);
 
typedef enum {
    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),
} NvMediaImageLockAccess;
 
typedef struct {
    uint32_t pitch;
    void *mapping;
} NvMediaImageSurface;
 
typedef struct {
    NvMediaSurfaceType type;
    uint32_t width;
    uint32_t height;
    uint32_t surfaces;
    NvMediaImageSurface surface[6];
    void *metaData;
} NvMediaImageSurfaceMap;
 
NvMediaStatus
NvMediaImageLock(
    const NvMediaImage *image,
    NvMediaImageLockAccess lockAccessType,
    NvMediaImageSurfaceMap *surfaceMap
);
 
void
NvMediaImageUnlock(
    const NvMediaImage *image
);
 
NvMediaStatus
NvMediaImagePutBits(
    NvMediaImage *image,
    const NvMediaRect *dstRect,
    void **srcPntrs,
    const uint32_t *srcPitches
);
 
NvMediaStatus
NvMediaImageGetBits(
    const NvMediaImage *image,
    const NvMediaRect *srcRect,
    void **dstPntrs,
    const uint32_t *dstPitches
);
#endif
 
/*
 * \defgroup history_nvmedia_image History
 * Provides change history for the NvMedia Image API.
 *
 * \section history_nvmedia_image Version History
 *
 * <b> Version 1.1 </b> March 3, 2016
 * - Initial release
 *
 * <b> Version 1.2 </b> May 11, 2016
 * - Added \ref NvMediaImageCheckVersion API
 *
 * <b> Version 1.3 </b> Jan 17, 2017
 * - Added atrribute NVMEDIA_IMAGE_ATTRIBUTE_CAPTURE in \ref NvMediaImageAttributes
 *
 * <b> Version 1.4 </b> Feb 9, 2017
 * - Added new APIs
 *       NvMediaImageCreateNew()
 *
 * <b> Version 1.5 </b> March 16, 2017
 * - Added \ref NVMEDIA_BITS_PER_PIXEL_16 in \ref NvMediaBitsPerPixel
 *
 * <b> Version 1.6 </b> May 9, 2017
 * - Deprecated the following APIs
 *     - NvMediaImageAcquire
 *     - NvMediaImageRelease
 *     - NvMediaImageWaitForIdle
 *     - NvMediaImageWaitForCompletion
 *     - NvMediaImageCheckVersion
 * - NvMediaImageGetVersion() is added to get the version of NvMedia Image library
 * - All NvMedia data types are moved to standard data types
 *
 * <b> Version 1.7 </b> May 14, 2017
 * - Added API to get status of operation on an image. \ref NvMediaImageGetStatus
 *
 * <b> Version 1.8 </b> May 15, 2017
 * - Added deprecated warning message for \ref NvMediaImageCreate,
 *   \ref NvMediaImageSiblingCreate, \ref NvMediaImageSiblingDestroy,
 *   \ref NvMediaVideoCreateImageSibling, \ref NvMediaImageCreateVideoSibling
 *
 * <b> Version 1.9 </b> May 18, 2017
 * - Added colorStd member in \ref NvMediaImage
 *
 * <b> Version 1.10 </b> June 12, 2017
 * - Added \ref NvMediaImageGroup to hold a list of NvMediaImages.
 *
 * <b> Version 1.11 </b> September 12, 2017
 * - Deprecated \ref NvMediaImageClass, \ref NvMediaImageAttributes, \ref NvMediaImageAdvancedConfig
 * - Deprecated \ref NvMediaImageCreate, \ref NvMediaImageSiblingCreate,
 *   \ref NvMediaVideoCreateImageSibling, \ref NvMediaImageSiblingDestroy,
 *   \ref NvMediaImageCreateVideoSibling, \ref NvMediaVideoSurfaceSiblingDestroy
 *
 * <b> Version 1.12 </b> Dec 06, 2018
 * - Fixed MISRA-C rule 10.4, 20.7 and 21.1 violations
 *   resulting from this header.
 *
 * <b> Version 1.13 </b> January 16, 2019
 * Updated desciption for \ref NvMediaImageGetBits and \ref NvMediaImagePutBits
 *
 * <b> Version 1.14 </b> March 13, 2019
 * - Data type of lockAcessType in NvMediaImageLock Api
     is changed from unit32_t to NvMediaImageLockAccess.
 *
 * <b> Version 1.15 </b> March 16, 2019
 * - Add required header include nvmedia_surface.h
 *
 * <b> Version 1.16 </b> March 20, 2019
 * - Added \ref NvMediaImageSetTag and \ref NvMediaImageGetTag APIs
 * - Tag member of NvMedia Image will be deprecated in later release.
 *
 * <b> Version 1.17 </b> March 22, 2019
 * - Added \ref NVMEDIA_RAW_PIXEL_ORDER_RCCB, \ref NVMEDIA_RAW_PIXEL_ORDER_BCCR,
 *   \ref NVMEDIA_RAW_PIXEL_ORDER_CRBC, \ref NVMEDIA_RAW_PIXEL_ORDER_CBRC, and
 *   \ref NVMEDIA_RAW_PIXEL_ORDER_COUNT
 *   in \ref NvMediaRawPixelOrder
 *
 * <b> Version 1.18 </b> March 25, 2019
 * - Added opaque pointer for image structure
 * - Fixed MISRA-C rule 8.13 violations resulting from this header.
 *
 *<b> Version 1.19 </b> March 28, 2019
 * - Unnecessary header include nvmedia_video.h has been removed
 *
 * <b> Version 1.20 </b> March 29, 2019
 * - Added captureTimeStamp to \ref NvMediaImageGroup to hold timestamps
 *
 *<b> Version 1.21 </b> March 28, 2019
 * - Move NvMediaBitsPerPixel and NVMEDIA_MAX_AGGREGATE_IMAGES to nvmedia_icp.h
 * - Move NvMediaRawPixelOrder to nvmedia_ipp.h
 *
 *<b> Version 1.22 </b> Dec 24, 2019
 * - Bypassed non-safety functions and non-safety NvMediaImage struct members
 *   using NV_IS_SAFETY macro to resolve MISRA-C rule 8.6 violations
 * - Fixed MISRA 2.4 for unused NvMediaImageRec tag.
 * - Changed arg type of NvMediaImageGetEmbeddedData from void*  to unit8_t*.
 *
 *<b> Version 1.23 </b> Jan 23, 2020
 *    Modify comments: Add warning for lock/unlock APIs and format support info in
 *    GetEmbeddedData
 *
 *<b> Version 1.24 </b> Feb 7, 2020
 *    Removed non-safety debug APIs on safety build
 *
 * <b> Version 1.25 </b> Sept 23, 2020
 *  - Added API to time base from NvMediaImage. \ref NvMediaImageGetTimeBase
 *
 * <b> Version 1.26 </b> August 27, 2021
 * - Update doxygen comments for all APIs to have Thread safety information and API Group information
 *
 * <b> Version 1.27 </b> April 4, 2022
 * - Added start of frame timestamp to \ref NvMediaImageGroup
 */
 
#ifdef __cplusplus
}     /* extern "C" */
#endif
 
#endif /* NVMEDIA_IMAGE_H */