Multimedia Changes#

Multimedia (Such as NvMedia, NvMMM-Legacy, and IDE NvJPG)#

Target Changes

Backward Compatible

Platform

OS

IDE for VP8, VP9, MPEG-2, MPEG-4, VC-1, AV1 and IJPD will be available only for development overlay and not in production filesystem

Yes

NSR

Linux only

Migration Path

  • Orin to Thor

Migration Rationale

The update streamlines cybersecurity efforts for all codecs.

Steps to Migrate

IDE (VP8, VP9, MPEG-2, MPEG-4, VC-1, AV1) and IJPD will be supported in the debug/development profile.

nvm_ide_sci test app will only accept h264/h265 codecs in production mode. Other codecs are not supported.

IOFA and PFSD Changes#

Target Changes

Backward Compatible

Platform

OS

Changes to the existing IOFA Process Frame API

In release 7.2.3.0, support for the Input Guide surfaces is added in the structure NvMediaIofaBufArray for the API NvMediaIOFAProcessFrame. The support implements OFA permanent fault software diagnostics (PFSD) in QNX only. The change does not break general API compatibility with other OFA API functions.

Yes

NSR, SR

Linux and QNX

Migration Path

  • Orin to Thor

Migration Release Path

7.0 to 7.2

6.x to 7.x

Target Changes

Backward Compatible

Platform

OS

GroupID parameters in the OFAPFSDSubmit API to support 0,1,2 group IDs

The Thor OFA PFSD tests are evenly distributed in three groups. OFAPFSDSubmit can take argument groupID and can take 0,1,2 values as input. The Orin OFA PFSD API did not change. Only two groups are supported and argument groupID can take 0 and 1 values as input.

Yes

NSR, SR

Linux and QNX

Migration Path

  • Orin to Thor

Migration Rationale

The change supports hardware coverage for a feature introduced in Thor.

The common API supports both Orin and Thor.

IOFA Header Breaking Changes (nvmedia_iofa.h)#

Recompile all code that uses IOFA structures; do not assume binary compatibility across the previous and new layouts.

NVMEDIA_IOFA_MAX_PYD_LEVEL (5 → 7)#

The maximum pyramid level count is increased from 5 to 7. Any structure that uses NVMEDIA_IOFA_MAX_PYD_LEVEL as an array dimension grows accordingly, including (among others) NvMediaIofaInitParams, NvMediaIofaBufArray, NvMediaIofaSGMParams, and NvMediaIofaProcessParams. This changes struct sizes and is ABI-breaking.

Customer action: Recompile all IOFA users. Update array allocations, loops, and any logic that assumed five pyramid levels so they respect the new maximum of 7.

NVMEDIA_IOFA_VERSION_MAJOR (1 → 2)#

The IOFA API major version is bumped from 1 to 2, reflecting multiple incompatible structure and API additions.

Structure and type changes

  • NvMediaIofaInitParams: new field ofaDeviceId (device selection).

  • NvMediaIofaSGMParams: new fields diagP1 and diagP2.

  • NvMediaIofaBufArray: new fields extHintSurface, extHintSurfacePerLevel, and guideSurface.

  • NvMediaIofaProcessParams: new fields pydConstHintParams and pydExtHintParams.

  • New structures: NvMediaIofaWMFParams, NvMediaIofaHINTParams, NvMediaIofaConstHintParams, NvMediaIofaExtHintParams.

  • New enum NvMediaIOFAParamType and APIs NvMediaIOFAGetConfigParams / NvMediaIOFASetConfigParams.

Deprecation

  • NVMEDIA_IOFA_PYD_LEVEL_MODE is deprecated after Orin OFA. Applications targeting Thor must migrate away from it.

Customer action: Recompile all IOFA code. Revisit struct initialization and memset/zero patterns so new members are valid. On Thor, do not use NVMEDIA_IOFA_PYD_LEVEL_MODE and use the supported configuration path. Set ofaDeviceId appropriately when using the extended device model (see also NvMediaIOFAQueryDevices in this document).

Target Changes

Backward Compatible

Platform

OS

IOFA: NVMEDIA_IOFA_MAX_PYD_LEVEL increased from 5 to 7; array dimensions and struct sizes in NvMediaIofaInitParams, NvMediaIofaBufArray, NvMediaIofaSGMParams, NvMediaIofaProcessParams, and related types (ABI-breaking).

No

NSR

SR

Linux and QNX

IOFA: NVMEDIA_IOFA_VERSION_MAJOR 1 → 2; new fields and structs; NVMEDIA_IOFA_PYD_LEVEL_MODE deprecated after Orin OFA; new NvMediaIOFAParamType, NvMediaIOFAGetConfigParams / NvMediaIOFASetConfigParams; ofaDeviceId in NvMediaIofaInitParams.

No

NSR

SR

Linux and QNX

Migration Path

  • Orin to Thor

Migration Rationale

Extended pyramid support, Thor IOFA capabilities, configurable IOFA parameters, and alignment with the device-query/instance selection model.

Steps to Migrate

Recompile all IOFA clients. Account for seven pyramid levels in arrays and iteration. Update struct initialization for new members; migrate off NVMEDIA_IOFA_PYD_LEVEL_MODE on Thor. Use ofaDeviceId and the new config get/set APIs as required. See nvmedia_iofa.h for exact layouts.

IOFA, IEP, IDE, IJPE, IJPD Changes#

Target Changes

Backward Compatible

Platform

OS

Changes to the following APIs: IOFA, IEP, IDE, IJPE, IJPD

A new API queries the device properties. This data determines if a specific engine is available and the number of instances available. Additionally, the API is used to select a specific engine instance for processing.

The use of this API is optional. The API is primarily intended to ensure that the same applications can execute seamlessly on different SKUs/platform configurations. In such cases, the applications can choose the NVENC/NVDEC/OFA/NVJPG hardware instance to be used (based on the list of available instances) at runtime based on the SKU/platform on which the application is running.

Yes

NSR, SR

Linux and QNX

Migration Path

  • Orin to Thor Only

Migration Rationale

Hardware architecture changes in Thor

Architectural Changes#

There is a major internal hardware architectural change for the multimedia hardware accelerator engines (NVENC, NVDEC, NVJPG and OFA) introduced from the Thor chip family onward, resulting in these engines being integrated into the iGPU chiplet.

Specific SKUs in the Thor chip family could house multiple instances of these engines. Additionally, Drive Thor platforms include support for multi-socket configurations (Thor with NUMA configuration), where the multimedia hardware accelerator on each of the sockets needs to be addressable.

The NvMedia Multimedia APIs (NvMediaIEP, NvMediaIOFA, NvMediaIDE, NvMediaIJPE, NvMediaIJPD) are extended to support addressing combinations of hardware engines for single- and multi-socket configurations. As a result of this change, a new API is introduced in each of NvMediaIEP, NvMediaIOFA, NvMediaIDE, NvMediaIJPE, NvMediaIJPD APIs to enable querying the list of available hardware engine instances and its properties. Applications need to select the required hardware instance from this list and subsequent operations (initialization, setup, processing, de-initialization) performed on this instance.

Note

  1. The number of engines available could vary based on the chip SKU, and multiple instances of a given engine may not be available for all engines.

  2. NvMediaDeviceInfo.numaDomainId is an important attribute for the multi-socket Drive Thor configuration. Each die in this case has an associated CPU, iGPU and local physical memory. Specific instances can be addressed using the numaDomainId. Applications should use this information to select a local/preferred GPU device from the list to ensure acceptable performance.

  3. Auto instance ID is no longer supported in NvMediaIEP, NvMediaIDE, NvMediaIJPE, and NvMediaIJPD. Do not use NVMEDIA_ENCODER_INSTANCE_AUTO, NVMEDIA_DECODER_INSTANCE_AUTO, and NVMEDIA_JPEG_INSTANCE_AUTO.

APIs#

NvMediaIEP#

/**
 * @brief Queries the IEP device list
 *
 * @pre NvMediaIEPGetVersion()
 * @post NvMediaIEPCreate()
 *
 * @usage
 * - Allowed context for the API call
 * - Interrupt handler: No
 * - Signal handler: No
 * - Thread-safe: Yes
 * - Re-entrant: No
 * - Async/Sync: Sync
 * - Required privileges: None
 *
 * - API group
 *   - Init: Yes
 *   - Runtime: No
 *   - De-Init: No
 *
 * @param[in] deviceList A pointer to a @ref NvMediaDeviceList structure
 *                       of the client.
 * @return ::NvMediaStatus The status of the operation.
 *         Possible values are:
 *         - ::NVMEDIA_STATUS_OK
 *         - ::NVMEDIA_STATUS_BAD_PARAMETER if the pointer is invalid.
 */

NvMediaStatus NvMediaIEPQueryDevices(
    NvMediaDeviceList *deviceList
);

NvMediaIOFA#

/**
 * @brief Query OFA devices present
 *
 * @pre NvMediaIOFAGetVersion()
 * @post NvMediaIOFACreate()
 *
 * @usage
 * - Allowed context for the API call
 * - Interrupt handler: No
 * - Signal handler: No
 * - Thread-safe: Yes
 * - Re-entrant: No
 * - Async/Sync: Sync
 * - Required privileges: None
 *
 * - API group
 *   - Init: Yes
 *   - Runtime: No
 *   - De-Init: No
 *
 * @param[in] deviceList
 * A pointer to the @ref NvMediaIofaDeviceList to populate device size
 * and info
 * Non-NULL - valid pointer address
 *
 * @return The completion status of the operation:
 * - ::NVMEDIA_STATUS_OK if the call is successful.
 * - ::NVMEDIA_STATUS_ERROR if there is an internal error in processing.
 */

NvMediaStatus
NvMediaIOFAQueryDevices(
    NvMediaIofaDeviceList *deviceList
);

NvMediaIDE#

/**
 * @brief Queries the HW device list for IDE
 *
 * @pre NvMediaIDEGetVersion()
 * @post NvMediaIDECreate()
 *
 * @usage
 * - Allowed context for the API call
 * - Interrupt handler: No
 * - Signal handler: No
 * - Thread-safe: Yes
 * - Re-entrant: No
 * - Async/Sync: Sync
 * - Required privileges: None
 *
 * - API group
 *   - Init: Yes
 *   - Runtime: No
 *   - De-Init: No
 *
 * @param[in] deviceList A pointer to a @ref NvMediaDeviceList structure
 *                       of the client.
 *
 * @return ::NvMediaStatus The status of the operation.
 *         Possible values are:
 *         - ::NVMEDIA_STATUS_OK
 *         - ::NVMEDIA_STATUS_BAD_PARAMETER if the pointer is invalid.
 */

NvMediaStatus
NvMediaIDEQueryDevices(
    NvMediaDeviceList *deviceList
);

NvMediaIJPE#

/**
 * @brief Queries the IJPE device list
 *
 * @pre NvMediaIJPEGetVersion()
 * @post NvMediaIJPECreate()
 *
 * @usage
 * - Allowed context for the API call
 * - Interrupt handler: No
 * - Signal handler: No
 * - Thread-safe: Yes
 * - Re-entrant: No
 * - Async/Sync: Sync
 * - Required privileges: None
 *
 * - API group
 *   - Init: Yes
 *   - Runtime: No
 *   - De-Init: No
 *
 * @param[in] deviceList A pointer to a @ref NvMediaDeviceList structure
 *                       of the client.
 *
 * @return ::NvMediaStatus The status of the operation.
 *         Possible values are:
 *         - ::NVMEDIA_STATUS_OK
 *         - ::NVMEDIA_STATUS_BAD_PARAMETER if the pointer is invalid.
 */

NvMediaStatus
NvMediaIJPEQueryDevices(
    NvMediaDeviceList *deviceList
);

NvMediaIJPD#

/**
 * @brief Queries the IJPD device list
 *
 * @pre NvMediaIJPDGetVersion()
 * @post NvMediaIJPDCreate()
 *
 * @usage
 * - Allowed context for the API call
 * - Interrupt handler: No
 * - Signal handler: No
 * - Thread-safe: Yes
 * - Re-entrant: No
 * - Async/Sync: Sync
 * - Required privileges: None
 *
 * - API group
 *   - Init: Yes
 *   - Runtime: No
 *   - De-Init: No
 *
 * @param[in] deviceList A pointer to a @ref NvMediaDeviceList structure
 *                       of the client.
 *
 * @return ::NvMediaStatus The status of the operation.
 *         Possible values are:
 *         - ::NVMEDIA_STATUS_OK
 *         - ::NVMEDIA_STATUS_BAD_PARAMETER if the pointer is invalid.
 */

NvMediaStatus
NvMediaIJPDQueryDevices(
    NvMediaDeviceList *deviceList
);

Data Types#

/**
 * @brief The 128-bit GPU device id
 */
typedef struct {
    /** array of id */
    uint8_t id[NVMEDIA_HW_DEVICE_ID_LEN];
} NvMediaDeviceGID;

/**
 * \brief Hold information about a MM device
 */
typedef struct {
    /**
     * @brief The GPU UUID – the primary device identifier
     * \n The GPU UUID is the primary identifier of the GPU device. The
     * main purpose of the UUID is to reliably identify a device in various
     * inter-operability scenarios.
     */
    NvMediaDeviceGID uuid;

    /**
     * @brief The GPU UUID for the hardware device
     * \n This is the identifier for the hardware device. The hardware
     * device identifier may be different to the primary device identifier
     * in case the GPU is a multi-instance GPU (MIG) device.
     * \n The primary use case for the hardware identifier is cross-driver
     * interoperability, where hardware identifier is needed rather than the
     * logical identifier.
     */
    NvMediaDeviceGID hwGid;

    /**
     * @brief The NUMA domain id in which the GPU device is present.
     * \n A Non-Uniform Memory Access (NUMA) architecture partitions a
     * system into multiple domains, typically each associated with its own
     * local CPU and physical memory. Performance of memory accesses to a
     * remote domain is significantly lower than that of accesses to the
     * local domain's physical memory.
     * \n Applications need to be NUMA-aware for good performance
     * under a NUMA architecture. Application threads should use
     * domain-local hardware resources for higher throughput and lower latency.
     */
    uint32_t numaDomainId;

} NvMediaDeviceInfo;

/**
 * \brief Hold information about list of a specific MM device
 */
typedef struct {
    // @brief The size of the Device list.
    uint32_t deviceListSize;

    /* @brief MM Engine Information.
     * This struct is the main source for device info uuid, hwid, numaDomainId
     */
    NvMediaDeviceInfo deviceList[NVMEDIA_HW_DEVICE_MAX_COUNT];
} NvMediaDeviceList;

API Call Sequence#

Following is the adapted API call sequence for NvMediaIEP post the introduction of NvMediaIEPQueryDevices():

/* Query the list of NVENC HW Instances on the chip */

NvMediaDeviceList deviceList;

NvMediaIEPQueryDevices(&deviceList);

/* deviceList.deviceListSize provides the number of NVENC instances.
 * The following members provide info on the device properties:
 *   deviceList.deviceList[index].uuid.id,
 *   deviceList.deviceList[index].hwGid.id,
 *   deviceList.deviceList[index].numaDomainId
 */

/* Select the NvMediaEncoderInstanceId enumeration based on the “index”
 * selected in deviceList. For instance, if the target UUID and HW GID
 * match with the deviceList at ‘index’ 0, then the instanceId to be passed
 * to all subsequent NvMediaIEP APIs is NVMEDIA_ENCODER_INSTANCE_0.
 * Similarly, it would be NVMEDIA_ENCODER_INSTANCE_1 if ‘index’ 1 is
 * selected.
 */

NvMediaIEP *iepCtxHandle = NvMediaIEPCreate(
    encodeType,
    encoderInitParams,
    bufReconciledList,
    outBuffering,
    instanceId
);

<No change to sequence of calls/arguments for subsequent APIs>

NvMedia Encode Initialization Structures (nvmedia_common_encode.h)#

These are breaking changes (struct layout and bit-field packing differ from previous releases). Recompile all code that passes these structures across the ABI boundary; do not rely on binary compatibility for the affected types.

enableMemoryOptimization is deprecated in the H.264, H.265, and AV1 encoder initialization parameter structures. The header marks it as do not use; setting it has no effect. Use disableMemoryOptimization instead when memory optimization behavior must be controlled.

NvMediaEncodeInitializeParamsH264

  • enableMemoryOptimization: deprecated / no-op; use disableMemoryOptimization.

  • New field disableMemoryOptimization added.

  • enableExtOutBuffer repositioned within the structure; the reserved bit-field width is reduced from 23 to 22 bits (bit-field layout change).

NvMediaEncodePicParamsH264

  • New field noopMode added at the end of the structure.

NvMediaEncodeInitializeParamsH265

  • enableMemoryOptimization: deprecated / no-op; use disableMemoryOptimization.

  • New fields disableMemoryOptimization and enableExtOutBuffer added.

  • reserved bit-field width reduced from 25 to 23 bits.

NvMediaEncodeInitializeParamsAV1

  • enableMemoryOptimization: deprecated / no-op; use disableMemoryOptimization.

  • New field disableMemoryOptimization added.

  • reserved1 bit-field width reduced from 31 to 30 bits.

Target Changes

Backward Compatible

Platform

OS

Encoder init/picture parameter structures (H.264, H.265, AV1) in nvmedia_common_encode.h: deprecation of enableMemoryOptimization, addition of disableMemoryOptimization (and H.265 enableExtOutBuffer), bit-field and member layout changes; H.264 picture params gain noopMode.

No

NSR

SR

Linux and QNX

Migration Path

  • Orin to Thor (and releases shipping this header layout)

Migration Rationale

Encoder API alignment with updated memory optimization controls and extended output buffering; struct layout reflects new fields and bit-field packing.

Steps to Migrate

Stop using enableMemoryOptimization. Use disableMemoryOptimization where memory optimization must be controlled. Rebuild clients that embed or exchange these structures; review any code that depends on struct size, offsetof, or manual packing. Initialize new members explicitly.

IEP Changes#

Target Changes

Backward Compatible

Platform

OS

New API: NvMediaIEPFeedFrameEx

A new API NvMediaIEPFeedFrameEx is introduced that extends NvMediaIEPFeedFrame to support specifying a user allocated output bitstream buffer and a byte offset (bitstreamOffset) within that buffer where the encoded bitstream (headers + data) is written.

This enables clients to control the placement of encoded output within an externally allocated output buffer.

Yes

NSR SR

Linux and QNX

Migration Path

  • Orin to Thor

Migration Release Path

  • 7.0 to 7.2

Migration Rationale

This is a new optional API in release 7.2.4.0. Existing applications using NvMediaIEPFeedFrame are not affected and require no changes. Applications that need memcopy-free enoding support or output buffer offset control should migrate to NvMediaIEPFeedFrameEx.

Steps to Migrate

Applications that wish to use memcopy-free encoding support or the bitstream offset feature should replace calls to NvMediaIEPFeedFrame with NvMediaIEPFeedFrameEx, providing the additional outputFrame and bitstreamOffset parameters.

If no offset is needed, pass 0 for bitstreamOffset.

API Signature#

NvMediaStatus
NvMediaIEPFeedFrameEx(
    NvMediaIEP *encoder,
    const NvSciBufObj inputFrame,
    const NvSciBufObj outputFrame,
    const void *picParams,
    NvMediaEncoderInstanceId instanceId,
    uint32_t bitstreamOffset
);

Parameters#

Parameter

Description

encoder

A pointer to the NvMediaIEP object.

inputFrame

NvSciBufObj for the input image surface to be encoded.

outputFrame

NvSciBufObj for the output raw buffer where the encoded bitstream will be written.

picParams

A pointer to frame-specific picture encoding parameters (for example, NvMediaEncodePicParamsH264, NvMediaEncodePicParamsH265).

instanceId

The ID of the NvENC HW engine instance.

bitstreamOffset

Byte offset into the output buffer at which the encoded bitstream will be written. Must be less than the output buffer size. When set to 0, the bitstream is written from the start of the output buffer.

Usage Example#

/* Allocate output (raw) bitstream buffer using NvSciBuf.
 * The application is responsible for allocating this buffer. */
NvSciBufObj outputBufObj;
NvSciBufAttrList outBufAttrList, reconciledList, conflictList;
NvSciBufAttrListCreate(bufModule, &outBufAttrList);

/* Populate engine attributes */
NvMediaIEPFillNvSciBufAttrList(instanceId, outBufAttrList);

/* Set raw buffer attributes (type, size, alignment, permissions) */
/* ... compute outBufSize based on resolution ... */
NvSciBufType bufType = NvSciBufType_RawBuffer;
uint64_t bufAlign = 256U;
NvSciBufAttrValAccessPerm accessPerm = NvSciBufAccessPerm_ReadWrite;
NvSciBufAttrKeyValuePair bufAttrs[] = {
    { NvSciBufGeneralAttrKey_Types, &bufType, sizeof(bufType) },
    { NvSciBufRawBufferAttrKey_Size, &outBufSize, sizeof(outBufSize) },
    { NvSciBufRawBufferAttrKey_Align, &bufAlign, sizeof(bufAlign) },
    { NvSciBufGeneralAttrKey_RequiredPerm, &accessPerm, sizeof(accessPerm) },
};
NvSciBufAttrListSetAttrs(outBufAttrList, bufAttrs, sizeof(bufAttrs) / sizeof(bufAttrs[0]));

/* Reconcile and allocate */
NvSciBufAttrListReconcile(&outBufAttrList, 1U, &reconciledList, &conflictList);
NvSciBufObjAlloc(reconciledList, &outputBufObj);

/* Register both input and output NvSciBufObj */
NvMediaIEPRegisterNvSciBufObj(encoder, inputBufObj);
NvMediaIEPRegisterNvSciBufObj(encoder, outputBufObj);

/* Feed frame with bitstream offset */
NvMediaStatus status = NvMediaIEPFeedFrameEx(
    encoder,
    inputBufObj,        /* input YUV surface */
    outputBufObj,       /* application allocated output bitstream buffer */
    &picParams,         /* per-frame encode parameters */
    instanceId,         /* encoder instance */
    bitstreamOffset     /* byte offset into output buffer */
);

/* Retrieve encoded output as usual */
NvMediaIEPGetBits(encoder, &numBytes, ...);

Video Interlace Compositor (VIC) Changes#

Target Changes

Backward Compatible

Platform

OS

Dynamic changes, such as to the programming sequence

No

NSR, SR

Linux and QNX

Migration Path

  • Orin to Thor Only

Migration Rationale

VIC hardware change

Steps to Migrate

The LDC region parameters (NvMedia2DLdcRegionParameters type) need to be adjusted to work with the strict height alignment requirement on Thor. With warp maps, this will affect the warp map contents – the position and potentially the total count of the control points changes.

Target Changes

Backward Compatible

Platform

OS

LDC and TNR API

No. Orin supported the old API only in 7.0.1 as deprecated compatibility. The old API is removed in 7.0.2 and later, including 7.2.x.

NSR, SR

Linux and QNX

Migration Path

  • Orin to Orin

  • Orin to Thor

Migration Release Path

  • 6.5.x to 7.2.x

  • 7.0.x to 7.2.x

Migration Rationale

The 2D hardware architecture changed in Thor, and VIC operations are consolidated behind the NvMedia2D API. NvMedia2D is the supported API for LDC, TNR, compose, and combined compose operations.

Steps to Migrate

The NvMediaLDC API is removed from DriveOS 7.2.x SDKs. Applications that still include or link the old API do not build:

  • The following headers are not present: nvmedia_ldc.h, nvmedia_ldc_sci.h, and nvmedia_ldc_util.h.

  • The libnvmedialdc library is not present. Build files must remove -lnvmedialdc and link against libnvmedia2d instead.

  • NvMediaLdc* symbols are not provided by the target SDK.

The 7.0.1 Orin compatibility path for the old API does not apply to a direct migration from DRIVE OS 6.5.x to DriveOS 7.2.x. Treat this as a source migration to NvMedia2D, not as a mechanical rename.

Update source files to include the NvMedia2D headers:

#include "nvmedia_2d.h"
#include "nvmedia_2d_sci.h"

/* Include this only when using LDC utility helpers such as
 * NvMedia2DGetNumLdcControlPoints() or NvMedia2DGenLdcWarpMap().
 */
#include "nvmedia_2d_ldcutil.h"

API Mapping#

NvMediaLDC API

NvMedia2D replacement

NvMediaLdcCreate()

NvMedia2DCreate(). Configure NvMedia2DAttributes for the maximum number of LDC warp maps, LDC mask maps, and TNR states that the context creates.

NvMediaLdcDestroy()

NvMedia2DDestroy(). Destroy LDC and TNR objects and unregister NvSci objects before destroying the context.

NvMediaLdcCreateParameters()

NvMedia2DGetComposeParameters() for per-submit task parameters. Resources that were allocated with NvMediaLdcParametersAttributes, such as warp-map storage, mask-map storage, and TNR buffers, move to explicit NvMedia2D objects.

NvMediaLdcDestroyParameters()

NvMedia2DReleaseComposeParameters() only when the parameters are not submitted. NvMedia2DCompose() consumes the parameters object on any return path.

NvMediaLdcProcess()

NvMedia2DCompose() with source, destination, LDC, TNR, sync, and compose state set on an NvMedia2DComposeParameters object.

NvMediaLdcSetSrcSurface()

NvMedia2DSetSrcNvSciBufObj().

NvMediaLdcSetDstSurface()

NvMedia2DSetDstNvSciBufObj().

NvMediaLdcSetGeometry()

NvMedia2DSetSrcGeometry() for the source layer.

NvMediaLdcSetFilter()

NvMedia2DSetSrcFilter() for the source layer.

NvMediaLdcSetIptParameters()

NvMedia2DSetSrcLdcTransformMatrix().

NvMediaLdcSetWarpMapParameters()

NvMediaLdcSetWarpMapParameters() copied caller-provided control-point data into storage owned by the NvMediaLdcParameters object. In NvMedia2D, create the warp-map object with NvMedia2DCreateLdcWarpMap(), copy data into it with NvMedia2DFillLdcWarpMap(), then attach it to a source layer with NvMedia2DSetSrcLdcWarpMap().

NvMediaLdcSetMaskMapParameters()

Only on platforms that support mask maps. Thor does not support LDC mask maps. When supported, create and populate a mask map with NvMedia2DCreateLdcMaskMap() and NvMedia2DFillLdcMaskMap(), then attach it to a source layer with NvMedia2DSetSrcLdcMaskMap().

NvMediaLdcSetTnrParameters()

Create a TNR state with NvMedia2DCreateTnrState(), configure it with NvMedia2DSetTnrParameters(), and attach it with NvMedia2DSetTnrState().

NvMediaLdcResetTnr()

NvMedia2DResetTnr().

NvMediaLdcSetPreviousSurface()

NvMedia2DSetTnrPreviousNvSciBufObj().

NvMediaLdcSetXSobelDstSurface()

NvMedia2DSetXSobelOutputNvSciBufObj().

NvMediaLdcSetDownsampledXSobelDstSurface()

NvMedia2DSetXSobelDownsampledNvSciBufObj().

NvMediaLdcFillNvSciBufAttrList()

NvMedia2DFillNvSciBufAttrList().

NvMediaLdcFillNvSciSyncAttrList()

NvMedia2DFillNvSciSyncAttrList().

NvMediaLdcRegisterNvSciBufObj()

NvMedia2DRegisterNvSciBufObj().

NvMediaLdcUnregisterNvSciBufObj()

NvMedia2DUnregisterNvSciBufObj().

NvMediaLdcRegisterNvSciSyncObj()

NvMedia2DRegisterNvSciSyncObj().

NvMediaLdcUnregisterNvSciSyncObj()

NvMedia2DUnregisterNvSciSyncObj().

NvMediaLdcSetNvSciSyncObjforEOF()

NvMedia2DSetNvSciSyncObjforEOF().

NvMediaLdcInsertPreNvSciSyncFence()

NvMedia2DInsertPreNvSciSyncFence().

NvMediaLdcGetEOFNvSciSyncFence()

NvMedia2DGetEOFNvSciSyncFence().

NvMediaLdcSetChecksumMode()

NvMedia2DSetChecksumMode().

NvMediaLdcGetChecksum()

NvMedia2DGetChecksum().

Task Parameters and Object Ownership#

The key programming model difference is the split between persistent objects and per-submit parameters. With NvMediaLDC, an NvMediaLdcParameters object could be updated and reused across multiple NvMediaLdcProcess() task submissions. The same parameters object also owned per-parameters resources allocated from NvMediaLdcParametersAttributes, including warp-map storage, mask-map storage, and TNR buffers. NvMediaLdcSetWarpMapParameters() copied the caller-provided control-point data into the params-owned internal warp-map storage.

With NvMedia2D, NvMedia2DComposeParameters is a per-submit object. Acquire a new compose-parameters object with NvMedia2DGetComposeParameters() for each NvMedia2DCompose() task, set the source, destination, LDC, TNR, and sync state for that task, and do not reuse the object after any NvMedia2DCompose() call, regardless of whether the call succeeds or fails. Use NvMedia2DReleaseComposeParameters() only for a parameters object that is not submitted.

Move reusable operation resources out of the per-submit parameters. For warp maps, create an NvMedia2DLdcWarpMap object, populate it with NvMedia2DFillLdcWarpMap(), and attach that object to each relevant compose submission with NvMedia2DSetSrcLdcWarpMap().

For TNR, NvMedia2D uses a separate NvMedia2DTnrState object. Create the state with NvMedia2DCreateTnrState(), configure algorithm parameters with NvMedia2DSetTnrParameters(), attach the state to each relevant compose submission with NvMedia2DSetTnrState(), and destroy the state with NvMedia2DDestroyTnrState() after pending work is complete. Set TNR output and previous surfaces on the per-submit compose parameters with NvMedia2DSetTnrOutputNvSciBufObj() and NvMedia2DSetTnrPreviousNvSciBufObj() as needed.

Example Migration#

Existing DRIVE OS 6.5.x LDC-only code commonly follows this pattern:

#include "nvmedia_ldc.h"
#include "nvmedia_ldc_sci.h"

NvMediaLdc *ldc = NULL;
NvMediaLdcCreate(&ldc, &ldcAttr);

NvMediaLdcRegisterNvSciBufObj(ldc, srcSurface);
NvMediaLdcRegisterNvSciBufObj(ldc, dstSurface);
NvMediaLdcRegisterNvSciSyncObj(ldc, NVMEDIA_EOFSYNCOBJ, eofSyncObj);

NvMediaLdcParameters params = 0U;
NvMediaLdcCreateParameters(ldc, NULL, &params);
NvMediaLdcSetWarpMapParameters(ldc, params, &warpMapParams);
NvMediaLdcSetSrcSurface(ldc, params, srcSurface);
NvMediaLdcSetDstSurface(ldc, params, dstSurface);
NvMediaLdcSetNvSciSyncObjforEOF(ldc, params, eofSyncObj);

NvMediaLdcResult result;
NvMediaLdcProcess(ldc, params, &result);

NvSciSyncFence eofFence;
NvMediaLdcGetEOFNvSciSyncFence(ldc, &result, &eofFence);
NvSciSyncFenceWait(&eofFence, waitCtx, -1);

NvMediaLdcDestroyParameters(ldc, params);
NvMediaLdcUnregisterNvSciSyncObj(ldc, eofSyncObj);
NvMediaLdcUnregisterNvSciBufObj(ldc, srcSurface);
NvMediaLdcUnregisterNvSciBufObj(ldc, dstSurface);
NvMediaLdcDestroy(ldc);

In DriveOS 7.2.x, port the flow to NvMedia2D:

#include "nvmedia_2d.h"
#include "nvmedia_2d_sci.h"

NvMedia2DAttributes attr = NvMedia2DGetDefaultAttributes();
attr.maxLdcWarpMaps = 1U;
attr.maxLdcMaskMaps = 0U;
attr.maxTnrStates = 0U;

NvMedia2D *nvm2d = NULL;
NvMedia2DCreate(&nvm2d, &attr);

NvMedia2DRegisterNvSciBufObj(nvm2d, srcSurface);
NvMedia2DRegisterNvSciBufObj(nvm2d, dstSurface);
NvMedia2DRegisterNvSciSyncObj(nvm2d, NVMEDIA_EOFSYNCOBJ, eofSyncObj);

NvMedia2DLdcWarpMapAttributes warpAttrs =
    NvMedia2DGetDefaultLdcWarpMapAttributes();
warpAttrs.maxWarpMapWidth = warpMapWidth;
warpAttrs.maxWarpMapHeight = warpMapHeight;

NvMedia2DLdcWarpMap warpMap = 0U;
NvMedia2DCreateLdcWarpMap(nvm2d, &warpAttrs, &warpMap);
NvMedia2DFillLdcWarpMap(nvm2d, warpMap, &warpMapParams);

/* Acquire a fresh compose-parameters object for this task submit. */
NvMedia2DComposeParameters params = 0U;
NvMedia2DGetComposeParameters(nvm2d, &params);
NvMedia2DSetSrcLdcWarpMap(nvm2d, params, 0U, warpMap);
NvMedia2DSetSrcNvSciBufObj(nvm2d, params, 0U, srcSurface);
NvMedia2DSetDstNvSciBufObj(nvm2d, params, dstSurface);
NvMedia2DSetNvSciSyncObjforEOF(nvm2d, params, eofSyncObj);

NvMedia2DComposeResult result;
NvMedia2DCompose(nvm2d, params, &result);

NvSciSyncFence eofFence;
NvMedia2DGetEOFNvSciSyncFence(nvm2d, &result, &eofFence);
NvSciSyncFenceWait(&eofFence, waitCtx, -1);

NvMedia2DDestroyLdcWarpMap(nvm2d, warpMap);
NvMedia2DUnregisterNvSciSyncObj(nvm2d, eofSyncObj);
NvMedia2DUnregisterNvSciBufObj(nvm2d, srcSurface);
NvMedia2DUnregisterNvSciBufObj(nvm2d, dstSurface);
NvMedia2DDestroy(nvm2d);

When porting the warp-map data, change old NvMediaLdc* types to their NvMedia2D* equivalents, such as NvMedia2DLdcWarpMapParameters and NvMedia2DLdcControlPoint. On Thor, also review the LDC region height alignment change above because the region configuration can change the control-point layout.

Combined Compose, LDC, and TNR#

NvMedia2D can combine operations that were previously programmed through separate APIs. Query the context capabilities before selecting a combined path:

NvMedia2DCapabilities const *caps;
caps = NvMedia2DGetCapabilities(handle);

if ((caps != NULL) && caps->supportsComposeLdc)
{
    NvMedia2DGetComposeParameters(handle, &params);
    NvMedia2DSetSrcBlendMode(handle, params, 0U, blendMode, constantAlpha);
    NvMedia2DSetSrcLdcWarpMap(handle, params, 0U, warpMap);
    NvMedia2DSetSrcNvSciBufObj(handle, params, 0U, srcSurface);
    NvMedia2DSetDstNvSciBufObj(handle, params, dstSurface);
    NvMedia2DCompose(handle, params, &result);
}
else
{
    /* Run LDC and compose as separate NvMedia2DCompose() submissions. */
}

The combined Compose+LDC path is supported only when NvMedia2DCapabilities.supportsComposeLdc is true. On platforms where it is false, including Orin, submit the LDC and compose operations separately. Use supportsTnr and supportsComposeTnrOutput in the same way when porting pipelines that used NvMediaLdcSetTnrParameters().

NvMedia2D ProcAmp API Changes#

Target Changes

Backward Compatible

Platform

OS

NvMedia2D ProcAmp API

No for DriveOS 7.2.5.0. The ProcAmp API is not present in DriveOS 7.2.5.0 and is added back in DriveOS 7.2.6.0.

NSR, SR

Linux and QNX

Migration Path

  • Orin to Orin

  • Orin to Thor

Migration Release Path

  • 6.x to 7.2.5.0

  • 6.x to 7.2.6.0

Migration Rationale

The NvMedia2D ProcAmp API was temporarily absent from DriveOS 7.2.5.0. It is restored in DriveOS 7.2.6.0 with API compatibility for applications that used the DRIVE OS 6.x API.

Steps to Migrate

DriveOS 7.2.5.0 does not provide NvMedia2DProcAmp, NvMedia2DSetSrcProcAmp(), or NvMedia2DGetDefaultProcAmp(). Code that includes those types or functions does not compile against the DriveOS 7.2.5.0 SDK. There is no replacement ProcAmp API in DriveOS 7.2.5.0.

For DriveOS 7.2.6.0 and later, use the restored NvMedia2D ProcAmp API. The restored API is compatible with the DRIVE OS 6.x ProcAmp API, so ProcAmp-dependent source code does not require a ProcAmp-specific migration when moving from DRIVE OS 6.x to DriveOS 7.2.6.0 or later.

If an application must target DriveOS 7.2.5.0, remove or conditionally disable ProcAmp-dependent code for that build. Re-enable the existing DRIVE OS 6.x ProcAmp code path when building against DriveOS 7.2.6.0 or later.

VIC Diagnostics API Changes#

Target Changes

Backward Compatible

Platform

OS

VIC Diagnostics API

No, the VicDiagnostics API is deprecated in 7.2.4.0 and removed in 7.2.6.0

NSR, SR

Linux and QNX

Migration Path

  • Orin to Thor

Migration Rationale

Unified API for all VIC operations through NvMedia2D

Steps to Migrate

Use the NvMedia2D API for diagnostics operations. Create NvMedia2D context with enableDiagnostics attribute set to true. Use NvMedia2DSetDiagnosticsTest() to configure diagnostics test and NvMedia2DCompose() to execute. Refer to the following details.

The VicDiagnostics API is consolidated into the NvMedia2D API to provide a unified interface for all VIC operations. The diagnostics functionality is now accessed through the standard NvMedia2D context with diagnostics enabled.

API Mapping#

VicDiagnostics API (Deprecated)

NvMedia2D API (Replacement)

VicDiagnosticsCreate()

NvMedia2DCreate() with attr.enableDiagnostics = true

VicDiagnosticsDestroy()

NvMedia2DDestroy()

VicDiagnosticsGetParameters()

NvMedia2DGetComposeParameters()

VicDiagnosticsGetNumTests()

NvMedia2DGetCapabilities()->numDiagnosticsTests

VicDiagnosticsSetTest()

NvMedia2DSetDiagnosticsTest()

VicDiagnosticsExecute()

NvMedia2DCompose()

VicDiagnosticsFillNvSciSyncAttrList()

NvMedia2DFillNvSciSyncAttrList()

VicDiagnosticsRegisterNvSciSyncObj()

NvMedia2DRegisterNvSciSyncObj()

VicDiagnosticsUnregisterNvSciSyncObj()

NvMedia2DUnregisterNvSciSyncObj()

VicDiagnosticsSetNvSciSyncObjforEOF()

NvMedia2DSetNvSciSyncObjforEOF()

VicDiagnosticsInsertPreNvSciSyncFence()

NvMedia2DInsertPreNvSciSyncFence()

VicDiagnosticsGetEOFNvSciSyncFence()

NvMedia2DGetEOFNvSciSyncFence()

Key Differences#

  • The NvMedia2D context must be created with NvMedia2DAttributes.enableDiagnostics set to true.

  • The number of available diagnostics tests is obtained from NvMedia2DCapabilities.numDiagnosticsTests instead of calling a separate function.

  • The diagnostics test is executed through NvMedia2DCompose() after setting the test ID with NvMedia2DSetDiagnosticsTest().

  • The task status indicating test result is still obtained from the EOF fence using NvSciSyncFenceGetTaskStatus().

Example Migration#

Old VicDiagnostics API usage:

// Create VicDiagnostics context
VicDiagnostics *handle = NULL;
VicDiagnosticsCreate(&handle, NULL);

// Get number of available tests
uint32_t numTests = 0;
VicDiagnosticsGetNumTests(handle, &numTests);

// Create and register EOF sync object
VicDiagnosticsFillNvSciSyncAttrList(handle, attrList, NVMEDIA_SIGNALER);
// ... create NvSciSyncObj ...
VicDiagnosticsRegisterNvSciSyncObj(handle, NVMEDIA_EOFSYNCOBJ, eofSyncObj);

// Run diagnostics test
VicDiagnosticsParameters params;
VicDiagnosticsGetParameters(handle, &params);
VicDiagnosticsSetTest(handle, params, testId);
VicDiagnosticsSetNvSciSyncObjforEOF(handle, params, eofSyncObj);

VicDiagnosticsResult result;
VicDiagnosticsExecute(handle, params, &result);

// Get EOF fence and wait
NvSciSyncFence eofFence;
VicDiagnosticsGetEOFNvSciSyncFence(handle, &result, &eofFence);
NvSciSyncFenceWait(&eofFence, waitCtx, -1);

// Check test result
NvSciSyncTaskStatus status;
NvSciSyncFenceGetTaskStatus(&eofFence, &status);
// status.status == NvSciSyncTaskStatus_Success indicates test passed

// Cleanup
VicDiagnosticsUnregisterNvSciSyncObj(handle, eofSyncObj);
VicDiagnosticsDestroy(handle);

New NvMedia2D API usage:

// Create NvMedia2D context with diagnostics enabled
NvMedia2DAttributes attr = NvMedia2DGetDefaultAttributes();
attr.enableDiagnostics = true;

NvMedia2D *handle = NULL;
NvMedia2DCreate(&handle, &attr);

// Get number of available tests from capabilities
NvMedia2DCapabilities const *caps = NvMedia2DGetCapabilities(handle);
uint32_t numTests = caps->numDiagnosticsTests;

// Create and register EOF sync object
NvMedia2DFillNvSciSyncAttrList(handle, attrList, NVMEDIA_SIGNALER);
// ... create NvSciSyncObj ...
NvMedia2DRegisterNvSciSyncObj(handle, NVMEDIA_EOFSYNCOBJ, eofSyncObj);

// Run diagnostics test
NvMedia2DComposeParameters params;
NvMedia2DGetComposeParameters(handle, &params);
NvMedia2DSetDiagnosticsTest(handle, params, testId);
NvMedia2DSetNvSciSyncObjforEOF(handle, params, eofSyncObj);

NvMedia2DComposeResult result;
NvMedia2DCompose(handle, params, &result);

// Get EOF fence and wait
NvSciSyncFence eofFence;
NvMedia2DGetEOFNvSciSyncFence(handle, &result, &eofFence);
NvSciSyncFenceWait(&eofFence, waitCtx, -1);

// Check test result
NvSciSyncTaskStatus status;
NvSciSyncFenceGetTaskStatus(&eofFence, &status);
// status.status == NvSciSyncTaskStatus_Success indicates test passed

// Cleanup
NvMedia2DUnregisterNvSciSyncObj(handle, eofSyncObj);
NvMedia2DDestroy(handle);

NvMediaJPEG and NvMediaEncoder Instance Enum Refresh#

Target Changes

Backward Compatible

Platform

OS

  • NvMediaJPEGInstanceId: NVMEDIA_JPEG_INSTANCE_AUTO was removed and two new explicit instance IDs NVMEDIA_JPEG_INSTANCE_2 (= 2) and NVMEDIA_JPEG_INSTANCE_3 (= 3) were added.

  • NvMediaEncoderInstanceId: NVMEDIA_ENCODER_INSTANCE_AUTO was removed and two new explicit instance IDs NVMEDIA_ENCODER_INSTANCE_2 (= 2) and NVMEDIA_ENCODER_INSTANCE_3 (= 3) were added.

  • The documented instanceId input range across NvMediaIEPCreate, NvMediaIEPCreateEx, NvMediaIEPInit, NvMediaIEPFeedFrame and NvMediaIEPFillNvSciBufAttrList was updated to the explicit-instance-only set {INSTANCE_0, INSTANCE_1, INSTANCE_2, INSTANCE_3}. The per-API documentation also notes that the instanceId argument of NvMediaIEPFeedFrame is itself going to be deprecated and is currently not consumed.

No. Source changes are required.

SR

QNX

Migration Path

  • Orin to Thor

Migration Release Path

  • 6.5.4.2 to 7.2.5.0

Migration Rationale

Newer platforms expose additional NVJPG and NvENC hardware instances; the previous AUTO sentinel (which on T194 spread the workload across all instances) is no longer supported. The API now requires explicit instance selection and exposes the new instances 2 and 3.

Steps to Migrate

  1. Replace any reference to NVMEDIA_JPEG_INSTANCE_AUTO with an explicit instance ID. Compile-time signal of this break: 'NVMEDIA_JPEG_INSTANCE_AUTO' undeclared.

    NvMediaJPEGInstanceId inst = NVMEDIA_JPEG_INSTANCE_AUTO;

    becomes:

    // Choose an explicit instance:
NvMediaJPEGInstanceId inst = NVMEDIA_JPEG_INSTANCE_0;
// Or, on platforms with more instances:
// NvMediaJPEGInstanceId inst = NVMEDIA_JPEG_INSTANCE_2;

  2. Replace any reference to NVMEDIA_ENCODER_INSTANCE_AUTO with an explicit instance ID. Compile-time signal of this break: 'NVMEDIA_ENCODER_INSTANCE_AUTO' undeclared.

    NvMediaIEP *enc = NvMediaIEPCreate(
    attrList, codec, ipNvm, NULL, 0, params,
    NVMEDIA_ENCODER_INSTANCE_AUTO);

    becomes:

    NvMediaIEP *enc = NvMediaIEPCreate(
    attrList, codec, ipNvm, NULL, 0, params,
    NVMEDIA_ENCODER_INSTANCE_0);

  3. Audit any code that passes instanceId to NvMediaIEPFeedFrame - the value is documented as no longer consumed by that entry point.

NvMedia Encoder Init-Params Bit-Field Refresh (H.264 / H.265 / AV1)#

Target Changes

Backward Compatible

Platform

OS

  • NvMediaEncodeInitializeParamsH264: enableMemoryOptimization is now documented as a deprecated no-op; new 1-bit flags disableMemoryOptimization (opt-out of the now-default optimization) and enableAutoFullRange (auto-detect VUI videoFullRangeFlag) were added. Trailing reserved shrinks from 23 to 21 bits. Struct size and preceding-field offsets are preserved.

  • NvMediaEncodeInitializeParamsH265: same enableMemoryOptimization deprecation; four new 1-bit flags disableMemoryOptimization, enableExtOutBuffer (zero-copy bitstream), enableAnonEncode (PII-region anonymization), and enableAutoFullRange. Trailing reserved shrinks from 25 to 21 bits.

  • NvMediaEncodeInitializeParamsAV1: same enableMemoryOptimization deprecation; new 1-bit flag disableMemoryOptimization added. Trailing reserved1 shrinks from 31 to 30 bits.

No. Persisted data / wire values may differ.

SR

QNX

Migration Path

  • Orin to Thor

Migration Release Path

  • 6.5.4.2 to 7.2.5.0

Migration Rationale

Memory-optimization is now on by default, so the legacy enable-flag is retired and only an opt-out remains. The new H.265 flags expose external bitstream buffer, PII anonymization and auto VUI full-range; H.264 / AV1 gain a subset of the same controls for parity.

Steps to Migrate

  1. Stop relying on enableMemoryOptimization; it is a no-op. If you need the legacy non-optimized memory behavior, set disableMemoryOptimization = 1.

    NvMediaEncodeInitializeParamsH264 p = {0};
p.enableMemoryOptimization = 1; // enabled the optimization in 6.5.4.2

    becomes:

    NvMediaEncodeInitializeParamsH264 p = {0};
// enableMemoryOptimization is now a deprecated no-op.
// The optimization is on by default; opt out only if needed:
// p.disableMemoryOptimization = 1;
p.enableAutoFullRange = 1; // optional new auto VUI full-range

  2. For H.265, optionally adopt the new feature flags:

    NvMediaEncodeInitializeParamsH265 p = {0};
// enableMemoryOptimization is now a deprecated no-op.
// p.disableMemoryOptimization = 1; // opt out if needed
// p.enableExtOutBuffer = 1;         // optional zero-copy out
// p.enableAnonEncode  = 1;          // optional PII anonymization
// p.enableAutoFullRange = 1;        // optional auto VUI full-range

  3. For AV1, the only addition is the opt-out flag:

    NvMediaEncodeInitializeParamsAV1 p = {0};
// enableMemoryOptimization is now a deprecated no-op.
// p.disableMemoryOptimization = 1; // opt out only if needed

NvMediaIEPFillNvSciSyncAttrList Now Accepts a NULL Encoder#

Target Changes

Backward Compatible

Platform

OS

The documented input range for the encoder parameter of NvMediaIEPFillNvSciSyncAttrList was widened from “Non-NULL - valid pointer address” to “Can be NULL or Non-NULL valid pointer address”. The API now formally accepts a NULL encoder handle for filling sync attributes ahead of encoder creation.

No. The source rebuilds, but runtime behavior changed.

SR

QNX

Migration Path

  • Orin to Thor

Migration Release Path

  • 6.5.4.2 to 7.2.5.0

Migration Rationale

Allows applications to construct NvSciSync attribute lists for IEP before the IEP handle is created, which is required to satisfy the DriveOS NvSciSync object-creation ordering.

Steps to Migrate

Where the prior NvSciSync object-creation ordering forced the call to be deferred until after NvMediaIEPCreate, you may now perform it earlier with a NULL handle:

// Required Non-NULL encoder:
NvMediaIEP *enc = NvMediaIEPCreate(...);
NvMediaIEPFillNvSciSyncAttrList(enc, attrList, type);

becomes:

// Now also accepted: NULL encoder before NvMediaIEPCreate
NvMediaIEPFillNvSciSyncAttrList(NULL, attrList, type);

NvMedia IEP Library Version Bumped to 1.1.0#

Target Changes

Backward Compatible

Platform

OS

NVMEDIA_IEP_VERSION_MINOR changed from 0 to 1 and NVMEDIA_IEP_VERSION_PATCH changed from 2 to 0, taking the IEP library version from 1.0.2 to 1.1.0. Code that compared the version macros against hardcoded numeric tuples will silently take the wrong branch after a rebuild.

No. Persisted data/wire values may differ.

SR

QNX

Migration Path

  • Orin to Thor

Migration Release Path

  • 6.5.4.2 to 7.2.5.0

Migration Rationale

The new public API NvMediaIEPQueryDevices and the refreshed contract across IEP bumped the minor version per the IEP versioning policy.

Steps to Migrate

Replace any hardcoded (1, 0, 2) comparison with a symbolic reference to the macros:

if (NVMEDIA_IEP_VERSION_MINOR == 0 && NVMEDIA_IEP_VERSION_PATCH == 2) {
    // ... assume 1.0.2 baseline ...
}

becomes:

// Compare against the macros symbolically; do not assume a tuple.
// The 7.2.5.0 release ships IEP 1.1.0.

NvMedia IOFA Version 2 and Pyramid-Depth Expansion (5 to 7)#

Note

For the higher-level architectural overview of the multimedia API changes (multi-socket support, NvMediaIOFAQueryDevices, instance selection) refer to IOFA, IEP, IDE, IJPE, IJPD Changes.

Target Changes

Backward Compatible

Platform

OS

  • NVMEDIA_IOFA_VERSION_MAJOR was bumped from 1 to 2 and NVMEDIA_IOFA_MAX_PYD_LEVEL was bumped from 5U to 7U.

  • NvMediaIofaInitParams gained a trailing ofaDeviceId (uint8_t) selecting the engine returned by NvMediaIOFAQueryDevices. All NVMEDIA_IOFA_MAX_PYD_LEVEL-sized arrays in this struct (width[], height[], gridSize[], outWidth[], outHeight[]) grow from 5 to 7 slots. Documented width / height ranges become “queryable via NvMediaIOFAGetCapability”.

  • NvMediaIofaSGMParams gained per-pyramid-level diagP1[] and diagP2[] diagonal SGM penalty arrays; penalty1[], penalty2[] and numPasses[] grow from 5 to 7 slots. Penalty ranges: Stereo / Epipolar SGM P2 <= 217 - P1 and P2 >= P1; Pyramidal SGM P2 <= 108 and P2 >= P1.

  • NvMediaIofaBufArray gained extHintSurface[] (NvSciBufObj[NVMEDIA_IOFA_MAX_EXTERNAL_HINTS]), extHintSurfacePerLevel[][...] (permanent-fault diagnostic mode only) and guideSurface[] (NvSciBufObj[NVMEDIA_IOFA_MAX_PYD_LEVEL]); costSurface[] grows from 5 to 7 slots; the prior YUV400 color-format restriction on pyramid bufObjs above level 0 is lifted.

No. Persisted data / wire values may differ.

SR

QNX

Migration Path

  • Orin to Thor

Migration Release Path

  • 6.5.4.2 to 7.2.5.0

Migration Rationale

Newer OFA hardware supports up to 7 pyramid levels and exposes diagonal SGM penalties, external hint and guide surfaces. The major-version bump signals the package of breaking changes; ofaDeviceId is required for multi-OFA-device platforms.

Steps to Migrate

  1. Reference NVMEDIA_IOFA_MAX_PYD_LEVEL symbolically rather than the literal 5, set ofaDeviceId, and revisit any sized-buffer allocations because the struct sizes have grown:

    NvMediaIofaInitParams init = {0};
// Implicit assumption: 5 pyramid slots

    becomes:

    NvMediaIofaInitParams init = {0};
init.ofaDeviceId = 0; // index into NvMediaIOFAQueryDevices() list
// Pyramid arrays now have NVMEDIA_IOFA_MAX_PYD_LEVEL == 7 slots.

  2. For NvMediaIofaSGMParams, populate the new diagonal penalty arrays alongside the existing penalty arrays:

    NvMediaIofaSGMParams sgm = {0};
for (int i = 0; i < 5; ++i) sgm.penalty1[i] = ...;

    becomes:

    NvMediaIofaSGMParams sgm = {0};
for (int i = 0; i < NVMEDIA_IOFA_MAX_PYD_LEVEL; ++i) {
    sgm.penalty1[i] = ...;
    sgm.diagP1[i]   = ...;  // new
    sgm.diagP2[i]   = ...;  // new
}

  3. For NvMediaIofaBufArray, account for the larger costSurface[] and optionally populate the new external-hint / guide surfaces:

    NvMediaIofaBufArray buf = {0};
// No external-hint / guide surfaces; costSurface has 5 slots.

    becomes:

    NvMediaIofaBufArray buf = {0};
// costSurface now has NVMEDIA_IOFA_MAX_PYD_LEVEL == 7 slots.
// Optionally populate buf.extHintSurface[] / buf.guideSurface[]
// for the new external-hint and guide-surface flows.

NvMedia IOFA Doc Contract Changes (EPIOF, PYD_LEVEL_MODE, Range Querying)#

Target Changes

Backward Compatible

Platform

OS

  • NVMEDIA_IOFA_PYD_LEVEL_MODE is now documented as “applicable for Orin OFA only - deprecated after Orin OFA”.

  • The “Epipolar OF support will be added in next release” note on NVMEDIA_IOFA_MODE_EPIOF was removed; the documented contract for NvMediaIOFAProcessFrame no longer instructs the caller to set pEpipolarInfo to NULL - epipolar OF is now functional.

  • NvMediaIOFAFillNvSciBufAttrList previously documented PeerHwEngine NvSciBufPlatformName as Orin; it is now stated as the current platform.

  • The NvMediaIofaInitParams width / height ranges previously documented as 32 to 8192 are now documented as queryable via NvMediaIOFAGetCapability.

No. The source rebuilds, but runtime behavior changed.

SR

QNX

Migration Path

  • Orin to Thor

Migration Release Path

  • 6.5.4.2 to 7.2.5.0

Migration Rationale

Reflects the actual hardware support added since 6.5.4.2 and the expansion of supported platforms beyond Orin.

Steps to Migrate

  1. NVMEDIA_IOFA_MODE_EPIOF is now usable; pass valid epipolar info:

    // Pre-7.2.5.0: NVMEDIA_IOFA_MODE_EPIOF was documented as not yet
// functional; pEpipolarInfo was required to be NULL.
NvMediaIOFAProcessFrame(ofa, &bufs, NULL, NULL, &params, NULL, NULL);

    becomes:

    // 7.2.5.0: EPIOF is supported; pass valid pEpipolarInfo.
NvMediaIofaEpipolarInfo epi = { ... };
NvMediaIOFAProcessFrame(ofa, &bufs, NULL, NULL, &params, NULL, &epi);

  2. Replace any compile-time 32..8192 range assumptions for width / height on NvMediaIofaInitParams with a runtime call to NvMediaIOFAGetCapability. Code paths that target Orin specifically should review the NVMEDIA_IOFA_PYD_LEVEL_MODE deprecation note.

NVM_DEPRECATED Compiler-Version Guard Tightened#

Target Changes

Backward Compatible

Platform

OS

The NVM_DEPRECATED macro guard in nvmedia_6x/nvmedia_core.h changed from defined(__GNUC__) && (__GNUC__ >= 4) && (__GNUC_MINOR__ >= 6) to defined(__GNUC__) && (__GNUC__ > 6). With GCC 7 or newer, NVM_DEPRECATED continues to expand to __attribute__((deprecated)); with GCC 4.x-6.x it now expands to nothing, so legacy NvMedia APIs that previously emitted deprecation warnings will compile silently on those toolchains.

No. The source rebuilds, but runtime behavior changed.

SR

QNX

Migration Path

  • Orin to Thor

Migration Release Path

  • 6.5.4.2 to 7.2.5.0

Migration Rationale

Tightens the deprecation-warning enablement to modern compilers and avoids a brittle minor-version comparison that misbehaves for GCC versions where __GNUC_MINOR__ resets.

Steps to Migrate

Build systems that relied on deprecation warnings being emitted on GCC 4.x-6.x must move to GCC 7 or newer to retain the diagnostic path:

// GCC 4.6+: NVM_DEPRECATED expands to __attribute__((deprecated))

becomes:

// GCC 7+:  NVM_DEPRECATED expands to __attribute__((deprecated))
// GCC <7:  NVM_DEPRECATED expands to nothing (no warning)

NvMedia 2D Header-Level Version Macros and NvMedia2DGetVersion Removed#

Target Changes

Backward Compatible

Platform

OS

  • The header-level version macros NVMEDIA_2D_VERSION_MAJOR / MINOR / PATCH were removed from nvmedia_6x/nvmedia_2d.h.

  • The NvMedia2DGetVersion() runtime version-query function was removed.

No. Source changes are required.

SR

QNX

Migration Path

  • Orin to Thor

Migration Release Path

  • 6.5.4.2 to 7.2.5.0

Migration Rationale

The NvMedia 2D library no longer exposes a header-level version number; capability discovery is now performed at runtime via NvMedia2DGetCapabilities() and the new attribute-defaults helpers.

Steps to Migrate

  1. Remove any compile-time version-macro check. Compile-time signal of this break: 'NVMEDIA_2D_VERSION_MAJOR' undeclared.

    #if NVMEDIA_2D_VERSION_MAJOR < 8
#error "NvMedia 2D too old"
#endif

    becomes:

    // No replacement; remove the version-check block. Use
// NvMedia2DGetCapabilities() at runtime to discover capabilities.

  2. Replace any NvMedia2DGetVersion() call site with a runtime capability query. Compile-time signal of this break: implicit declaration of function 'NvMedia2DGetVersion'.

    NvMediaVersion v;
NvMedia2DGetVersion(&v);

    becomes:

    // No replacement; use NvMedia2DGetCapabilities() to discover
// platform-specific capabilities of the NvMedia2D context.
NvMedia2DCapabilities const *caps = NvMedia2DGetCapabilities(handle);

NvMedia 2D Per-Source ProcAmp Interface Removed#

Target Changes

Backward Compatible

Platform

OS

The per-source-layer ProcAmp (color-correction) interface was removed in its entirety: the NvMedia2DProcAmp struct, the NvMedia2DGetDefaultProcAmp() default-attribute helper and the NvMedia2DSetSrcProcAmp() per-source-layer setter were all deleted. The driver no longer offers per-layer gain / bias / saturation adjustment as part of an NvMedia2DCompose() operation.

No. Source changes are required.

SR

QNX

Migration Path

  • Orin to Thor

Migration Release Path

  • 6.5.4.2 to 7.2.5.0

Migration Rationale

Per-layer ProcAmp is no longer offered by the NvMedia 2D API. ProcAmp adjustments must be applied outside NvMedia2DCompose() (for example, in an upstream image-processing pipeline).

Steps to Migrate

Remove any code that touches NvMedia2DProcAmp, NvMedia2DGetDefaultProcAmp or NvMedia2DSetSrcProcAmp. Compile-time signal of this break: 'NvMedia2DProcAmp' undeclared / 'NvMedia2DSetSrcProcAmp' undeclared.

NvMedia2DProcAmp pa = NvMedia2DGetDefaultProcAmp();
pa.enabled    = true;
pa.gain       = 1.2f;
pa.bias       = 0.0f;
pa.saturation = 1.0f;
NvMedia2DSetSrcProcAmp(handle, params, index, &pa);

becomes:

// No replacement; ProcAmp adjustments must be applied outside
// NvMedia2DCompose() (e.g. in upstream image-processing pipeline).

NvMedia 2D Attributes Refresh and Default-Initialization Requirement#

Target Changes

Backward Compatible

Platform

OS

  • NvMedia2DAttributes gained five new fields: maxLdcWarpMaps (uint32_t), maxLdcMaskMaps (uint32_t), maxTnrStates (uint32_t), enableDiagnostics (bool) and numaNodeId (uint32_t).

  • NvMedia2DCreate() now requires that any caller-supplied NvMedia2DAttributes be initialized via NvMedia2DGetDefaultAttributes() (new precondition); designated-initializer or zero-initialized structs are no longer guaranteed to satisfy the contract.

  • Four attribute-defaults helpers were added: NvMedia2DGetDefaultAttributes(), NvMedia2DGetDefaultLdcWarpMapAttributes(), NvMedia2DGetDefaultLdcMaskMapAttributes() and NvMedia2DGetDefaultTnrStateAttributes(). The latter three are required by the new resource-Create functions for the same forward-compatibility reason.

No. Source changes are required.

SR

QNX

Migration Path

  • Orin to Thor

Migration Release Path

  • 6.5.4.2 to 7.2.5.0

Migration Rationale

Supports new LDC, TNR, diagnostics and multi-NUMA features. Routing attribute initialization through the GetDefault* helpers preserves forward compatibility as new fields are added.

Steps to Migrate

  1. Replace any designated-initializer or zero-initialized NvMedia2DAttributes with a call to NvMedia2DGetDefaultAttributes() and override only the fields you actually want to change.

    NvMedia2DAttributes attr = {
    .numComposeParameters = 1,
    .maxRegisteredBuffers = 64,
    .maxRegisteredSyncs = 16,
    .maxFilterBuffers = 0,
    .flags = 0,
};
NvMedia2DCreate(&handle, &attr);

    becomes:

    NvMedia2DAttributes attr = NvMedia2DGetDefaultAttributes();
// override any non-default fields:
attr.maxLdcWarpMaps     = 16;
attr.maxLdcMaskMaps     = 16;
attr.maxTnrStates       = 16;
attr.enableDiagnostics  = false;
attr.numaNodeId         = 0;
NvMedia2DCreate(&handle, &attr);

  2. For the new resource Create functions, do the same:

    NvMedia2DLdcWarpMapAttributes wmAttr =
    NvMedia2DGetDefaultLdcWarpMapAttributes();

NvMedia 2D NvSci Doc-Contract Refresh (NUMA, Fence-Clear, NOT_SUPPORTED Status)#

Target Changes

Backward Compatible

Platform

OS

  • NvMedia2DFillNvSciSyncAttrList may now set NvSciSyncAttrKey_Numa to the numaNodeId from NvMedia2DAttributes on systems with multiple NUMA nodes and cross-die-synchronization limitations. Callers must not set NvSciSyncAttrKey_Numa themselves on the same attribute list.

  • NvMedia2DGetEOFNvSciSyncFence now explicitly clears syncFence before updating and returning its new value.

  • NvMedia2DSetSrcNvSciBufObj and NvMedia2DSetDstNvSciBufObj now document NVMEDIA_STATUS_NOT_SUPPORTED as a valid return value, indicating the requested operation is not supported on the current platform; callers must handle this status in addition to the existing return values.

No. The source rebuilds, but runtime behavior changed.

SR

QNX

Migration Path

  • Orin to Thor

Migration Release Path

  • 6.5.4.2 to 7.2.5.0

Migration Rationale

Documents the new NUMA-aware fence behavior introduced for multi-die systems, formalizes the long-standing fence-clear behavior of GetEOFNvSciSyncFence, and surfaces platform support gaps via a defined status code rather than a generic error.

Steps to Migrate

  1. Stop setting NvSciSyncAttrKey_Numa in code that calls NvMedia2DFillNvSciSyncAttrList; the function now sets it for you on multi-NUMA systems.

  2. Treat the contents of the syncFence argument to NvMedia2DGetEOFNvSciSyncFence as scratch input: the function now formally clears it before assigning the new value.

  3. Add a NVMEDIA_STATUS_NOT_SUPPORTED branch to call sites of NvMedia2DSetSrcNvSciBufObj / NvMedia2DSetDstNvSciBufObj:

    NvMediaStatus s = NvMedia2DSetSrcNvSciBufObj(handle, params, idx, buf);
if (s == NVMEDIA_STATUS_NOT_SUPPORTED) {
    // operation not supported on this platform
} else if (s != NVMEDIA_STATUS_OK) {
    // handle other error
}

NvMedia 2D Compose / Destroy / FilterBuffer Doc-Contract Refresh#

Target Changes

Backward Compatible

Platform

OS

  • NvMedia2DDestroy now also requires that there are no NvMedia2DFilterBuffer objects still alive at the time of the call; NVMEDIA_STATUS_PENDING is now also returned when filter buffers have not been destroyed (previously documented only for outstanding NvSciSync / NvSciBuf registrations).

  • NvMedia2DCompose doc contract substantially clarified: several previously hard-coded restrictions (16-bit YUV-only path, hardware tile size of 64x16, 16-bit destination top-left = 0, chroma sub-sampled corners aligned to 2) are now expressed conditionally on runtime capabilities (NvMedia2DCapabilities::supports16BitYUVNatively, NvMedia2DCapabilities::supportsNonAlignedRects, the dynamic tileWidth / tileHeight, NvMedia2DCapabilities::maxComposeLayers). Default-rectangle and default-filter behavior were formalized: source / destination / clip rectangles default to surface dimensions; filter mode is auto-selected when not set.

  • NvMedia2DSetFilterBuffer and NvMedia2DCreateFilterBuffer doc clarified: the filter buffer object’s lifetime must extend beyond the duration of any compose operation referring to it; updates to the filter buffer are reflected in subsequent compose operations; the filter-buffer instance must be destroyed before NvMedia2DDestroy is called.

No. Source rebuilds, but runtime behavior changed.

SR

QNX

Migration Path

  • Orin to Thor

Migration Release Path

  • 6.5.4.2 to 7.2.5.0

Migration Rationale

Replaces static restrictions with runtime-capability-driven contracts so a single header can describe multiple platforms with different VIC capabilities, and makes filter-buffer and context lifetime obligations explicit to avoid use-after-destroy.

Steps to Migrate

  1. Destroy all filter buffers before destroying the context:

    // Destroy all filter buffers before destroying the context:
NvMedia2DDestroyFilterBuffer(handle, filterBuf);
NvMedia2DDestroy(handle);

  2. Replace any compile-time assumption about 16-bit YUV size limits, tile size or maximum compose-layer count with a runtime query:

    // 64x16 tiles; 16-bit YUV restricted to <= 8192x8192; etc.
// (assumed statically)

    becomes:

    NvMedia2DCapabilities const *caps = NvMedia2DGetCapabilities(handle);
// align to caps->tileWidth x caps->tileHeight
// check caps->supports16BitYUVNatively, caps->supportsNonAlignedRects
// bound source-layer count to caps->maxComposeLayers

  3. Treat the filter-buffer object as caller-owned for the entire span of any compose operation that references it; re-using a buffer is supported but destroying it before the compose completes is not.

VicDiagnostics Library-Version Macros and GetVersion Removed#

Target Changes

Backward Compatible

Platform

OS

  • The VICDIAGNOSTICS_VERSION_MAJOR / MINOR / PATCH version macros were removed from nvmedia_6x/vicdiagnostics.h.

  • VicDiagnosticsGetVersion() was removed.

No. Source changes are required.

SR

QNX

Migration Path

  • Orin to Thor

Migration Release Path

  • 6.5.4.2 to 7.2.5.0

Migration Rationale

The VicDiagnostics API is being deprecated in favor of NvMedia2D; header-level and runtime version validation are no longer maintained for this API.

Steps to Migrate

  1. Remove the VICDIAGNOSTICS_VERSION_* compile-time check. Compile-time signal of this break: 'VICDIAGNOSTICS_VERSION_MAJOR' undeclared.

    #if VICDIAGNOSTICS_VERSION_MAJOR != 1
#error "Unsupported VicDiagnostics version"
#endif

    becomes:

    // No replacement; remove the version-check block. Migrate to the
// NvMedia2D API.

  2. Remove the VicDiagnosticsGetVersion() runtime call. Compile-time signal of this break: implicit declaration of function 'VicDiagnosticsGetVersion'.

    NvMediaVersion v;
VicDiagnosticsGetVersion(&v);

    becomes:

    // No replacement; migrate the diagnostics path to the NvMedia2D API
// (see NvMedia2DSetDiagnosticsTest()).

VicDiagnosticsGetEOFNvSciSyncFence Clears Fence on Entry#

Target Changes

Backward Compatible

Platform

OS

VicDiagnosticsGetEOFNvSciSyncFence doc contract was clarified to explicitly state that the function clears syncFence before updating and returning its new value. Callers passing a non-cleared NvSciSyncFence will have it cleared by the function.

No. The source rebuilds, but runtime behavior changed.

SR

QNX

Migration Path

  • Orin to Thor

Migration Release Path

  • 6.5.4.2 to 7.2.5.0

Migration Rationale

Documentation alignment with implementation; existing callers that pass uninitialized or previously-used fences are now formally guaranteed that the fence is cleared by the call.

Steps to Migrate

Treat the contents of the syncFence argument as scratch input; do not rely on the prior fence state being preserved across the call.

IDE API Changes (nvmedia_ide.h)#

Target Changes

Backward Compatible

Platform

OS

const qualifier is removed from the NvMediaIDE *decoder handle parameter in NvMediaIDEDestroy and NvMediaIDEDecoderRender in nvmedia_ide.h.

No

NSR

SR

Linux and QNX

Migration Path

  • Orin to Thor

Migration Release Path

  • 7.2.6.0

Migration Rationale

The const qualifier on the decoder handle in NvMediaIDEDestroy and NvMediaIDEDecoderRender did not reflect the actual behavior of these APIs and the update decoder state during normal operation. Removing const aligns the public API contract with the implementation and eliminates a MISRA C Rule 11.8 violation caused by casting away const internally.

Steps to Migrate

Recompile all code that uses NvMediaIDEDestroy or NvMediaIDEDecoderRender with the updated nvmedia_ide.h header.

If your application declares or stores the decoder handle as const NvMediaIDE * for use with these two APIs, remove the const qualifier so the declaration reads NvMediaIDE *, and then recompile.

API Signatures#

NvMediaStatus
NvMediaIDEDestroy(
    NvMediaIDE *decoder
);

NvMediaStatus
NvMediaIDEDecoderRender(
    NvMediaIDE                      *decoder,
    NvSciBufObj                      targetbufObj,
    const NvMediaPictureInfo        *pictureInfo,
    const void                      *encryptParams,
    uint32_t                         numBitstreamBuffers,
    const NvMediaBitstreamBuffer    *bitstreams,
    NvMediaIDEFrameStats            *FrameStatsDump,
    NvMediaDecoderInstanceId         instanceId
);
On this page