Functions#

This section provides information about the functions in the AR SDK.

NvAR_Create#

NvAR_Result NvAR_Create(
    NvAR_FeatureID featureID,
    NvAR_FeatureHandle *handle
);

Parameters#

featureID [in]: Type: NvAR_FeatureID

The type of feature to be created.
handle [out]: Type: NvAR_FeatureHandle*

A handle to the newly created feature instance.

Return Value#

Returns one of the following values:

NVCV_SUCCESS on success
NVCV_ERR_FEATURENOTFOUND
NVCV_ERR_INITIALIZATION

Remarks#

This function creates an instance of the specified feature type and writes a handle to the feature instance to the handle out parameter.

NvAR_Destroy#

NvAR_Result NvAR_Destroy(
    NvAR_FeatureHandle handle
);

Parameters#

handle [in]: Type: NvAR_FeatureHandle

The handle to the feature instance to be released.

Return Value#

Returns one of the following values:

NVCV_SUCCESS on success
NVCV_ERR_FEATURENOTFOUND

Remarks#

This function releases the feature instance with the specified handle. Because handles are not reference counted, the handle is invalid after this function is called.

NvAR_Load#

NvAR_Result NvAR_Load(
    NvAR_FeatureHandle handle
);

Parameters#

handle [in]: Type: NvAR_FeatureHandle

The handle to the feature instance to load.

Return Value#

Returns one of the following values:

NVCV_SUCCESS on success
NVCV_ERR_MISSINGINPUT
NVCV_ERR_FEATURENOTFOUND
NVCV_ERR_INITIALIZATION
NVCV_ERR_UNIMPLEMENTED

Remarks#

This function loads the specified feature instance and validates any configuration properties that were set for the feature instance.

NvAR_Run#

NvAR_Result NvAR_Run(
    NvAR_FeatureHandle handle
);

Parameters#

handle [in]: Type: NvAR_FeatureHandle

The handle to the feature instance to be run.

Return Value#

Returns one of the following values:

NVCV_SUCCESS on success
NVCV_ERR_GENERAL
NVCV_ERR_FEATURENOTFOUND
NVCV_ERR_MEMORY
NVCV_ERR_MISSINGINPUT
NVCV_ERR_PARAMETER

Remarks#

This function validates the input/output properties that are set by the user, runs the specified feature instance with the input properties that were set for the instance, and writes the results to the output properties set for the instance. The input and output properties are set by the accessor functions. Refer to Summary of AR SDK Accessor Functions for more information.

NvAR_GetCudaStream#

NvAR_Result NvAR_GetCudaStream(
    NvAR_FeatureHandle handle,
    const char *name,
    const CUStream *stream
);

Parameters#

handle: Type: NvAR_FeatureHandle

The handle to the feature instance from which you want to get the CUDA stream.
name: Type: const char*

The NvAR_Parameter_Config(CUDAStream) key value. Any other key value returns an error.
stream: Type: const CUStream*

Pointer to the CUDA stream where the CUDA stream retrieved is to be written.

Return Value#

Returns one of the following values:

NVCV_SUCCESS on success
NVCV_ERR_PARAMETER
NVCV_ERR_SELECTOR
NVCV_ERR_MISSINGINPUT
NVCV_ERR_GENERAL
NVCV_ERR_MISMATCH

Remarks#

This function gets the CUDA stream in which the specified feature instance will run and writes the CUDA stream to be retrieved to the location that is specified by the stream parameter.

NvAR_CudaStreamCreate#

NvCV_Status NvAR_CudaStreamCreate(
    CUstream *stream
);

Parameters#

stream [out]: Type: CUstream *

The location in which to store the newly allocated CUDA stream.

Return Value#

Returns one of the following values:

NVCV_SUCCESS on success
NVCV_ERR_CUDA_VALUE if a CUDA parameter is not within its acceptable range.

Remarks#

This function creates a CUDA stream. It is a wrapper for the CUDA Runtime API function cudaStreamCreate() that you can use to avoid linking with the NVIDIA CUDA Toolkit libraries. This function and cudaStreamCreate() are equivalent and interchangeable.

NvAR_CudaStreamDestroy#

void NvAR_CudaStreamDestroy(
    CUstream stream
);

Parameters#

stream [in]: Type: CUstream

The CUDA stream to destroy.

Return Value#

Does not return a value.

Remarks#

This function destroys a CUDA stream. It is a wrapper for the CUDA Runtime API function cudaStreamDestroy() that you can use to avoid linking with the NVIDIA CUDA Toolkit libraries. This function and cudaStreamDestroy() are equivalent and interchangeable.

NvAR_GetF32#

NvAR_Result NvAR_GetF32(
    NvAR_FeatureHandle handle,
    const char *name,
    float *val
);

Parameters#

handle: Type: NvAR_FeatureHandle

The handle to the feature instance from which you want to get the specified 32-bit floating-point parameter.
name: Type: const char*

The key value that is used to access the 32-bit float parameters.
val: Type: float*

Pointer to the 32-bit floating-point number where the value retrieved is to be written.

Return Value#

Returns one of the following values:

NVCV_SUCCESS on success
NVCV_ERR_PARAMETER
NVCV_ERR_SELECTOR
NVCV_ERR_GENERAL
NVCV_ERR_MISMATCH

Remarks#

This function gets the value of the specified single-precision (32-bit) floating-point parameter for the specified feature instance and writes the value to be retrieved to the location that is specified by the val parameter.

NvAR_GetF64#

NvAR_Result NvAR_GetF64(
    NvAR_FeatureHandle handle,
    const char *name,
    double *val
);

Parameters#

handle: Type: NvAR_FeatureHandle

The handle to the feature instance from which you want to get the specified 64-bit floating-point parameter.
name: Type: const char*

The key value used to access the 64-bit double parameters.
val: Type: double*

Pointer to the 64-bit double-precision floating-point number where the retrieved value will be written.

Return Value#

Returns one of the following values:

NVCV_SUCCESS on success
NVCV_ERR_PARAMETER
NVCV_ERR_SELECTOR
NVCV_ERR_GENERAL
NVCV_ERR_MISMATCH

Remarks#

This function gets the value of the specified double-precision (64-bit) floating-point parameter for the specified feature instance and writes the retrieved value to the location that is specified by the val parameter.

NvAR_GetF32Array#

NvAR_Result NvAR_GetF32Array(
    NvAR_FeatureHandle handle,
    const char *name,
    const float **vals,
    int *count
);

Parameters#

handle: Type: NvAR_FeatureHandle

The handle to the feature instance from which you want to get the specified float array.
name: Type: const char*

Refer to Key Values in the Properties of a Feature Type for a complete list of key values.
vals: Type: const float**

Address of a floating-point pointer, where the retrieved pointer will be written.
count: Type: int*

Currently unused. The number of elements in the array specified by the vals parameter.

Return Value#

Returns one of the following values:

NVCV_SUCCESS on success
NVCV_ERR_PARAMETER
NVCV_ERR_SELECTOR
NVCV_ERR_MISSINGINPUT
NVCV_ERR_GENERAL
NVCV_ERR_MISMATCH

NvAR_GetU32Array#

NvAR_Result NvAR_GetU32Array(
    NvAR_FeatureHandle handle,
    const char *name,
    const unsigned int **vals,
    int *count
);

Parameters#

handle: Type: NvAR_FeatureHandle

The handle to the feature instance from which you want to get the specified unsigned integer array.
name: Type: const char*

Refer to Key Values in the Properties of a Feature Type for a complete list of key values.
vals: Type: const unsigned int**

Address of an unsigned integer pointer, where the retrieved pointer will be written.
count: Type: int*

Currently unused. The number of elements in the array specified by the vals parameter.

Return Value#

Returns one of the following values:

NVCV_SUCCESS on success
NVCV_ERR_PARAMETER
NVCV_ERR_SELECTOR
NVCV_ERR_MISSINGINPUT
NVCV_ERR_GENERAL
NVCV_ERR_MISMATCH

NvAR_GetObject#

NvAR_Result NvAR_GetObject(
    NvAR_FeatureHandle handle,
    const char *name,
    const void **ptr,
    unsigned long typeSize
);

Parameters#

handle: Type: NvAR_FeatureHandle

The handle to the feature instance from which you can get the specified object.
name: Type: const char*

Refer to Key Values in the Properties of a Feature Type for a complete list of key values.
ptr: Type: const void**

A pointer to the memory that is allocated for the objects defined in Structures.
typeSize: Type: unsigned long

The size of the item to which the pointer points. If the size does not match, an NVCV_ERR_MISMATCH is returned.

Return Value#

Returns one of the following values:

NVCV_SUCCESS on success
NVCV_ERR_PARAMETER
NVCV_ERR_SELECTOR
NVCV_ERR_MISSINGINPUT
NVCV_ERR_GENERAL
NVCV_ERR_MISMATCH

Remarks#

This function gets the specified object for the specified feature instance and stores the object in the memory location that is specified by the ptr parameter.

NvAR_GetS32#

NvAR_Result NvAR_GetS32(
    NvAR_FeatureHandle handle,
    const char *name,
    int *val
);

Parameters#

handle: Type: NvAR_FeatureHandle

The handle to the feature instance from which you get the specified 32-bit signed integer parameter.
name: Type: const char*

The key value that is used to access the signed integer parameters.
val: Type: int*

Pointer to the 32-bit signed integer where the retrieved value will be written.

Return Value#

Returns one of the following values:

NVCV_SUCCESS on success
NVCV_ERR_PARAMETER
NVCV_ERR_SELECTOR
NVCV_ERR_GENERAL
NVCV_ERR_MISMATCH

Remarks#

This function gets the value of the specified 32-bit signed integer parameter for the specified feature instance and writes the retrieved value to the location that is specified by the val parameter.

NvAR_GetString#

NvAR_Result NvAR_GetString(
    NvAR_FeatureHandle handle,
    const char *name,
    const char** str
);

Parameters#

handle: Type: NvAR_FeatureHandle

The handle to the feature instance from which you get the specified character string parameter.
name: Type: const char*

Refer to Key Values in the Properties of a Feature Type for a complete list of key values.
str: Type: const char**

The address where the requested character string pointer is stored.

Return Value#

Returns one of the following values:

NVCV_SUCCESS on success
NVCV_ERR_PARAMETER
NVCV_ERR_SELECTOR
NVCV_ERR_MISSINGINPUT
NVCV_ERR_GENERAL
NVCV_ERR_MISMATCH

Remarks#

This function gets the value of the specified character string parameter for the specified feature instance and writes the retrieved string to the location that is specified by the str parameter.

NvAR_GetU32#

NvAR_Result NvAR_GetU32(
    NvAR_FeatureHandle handle,
    const char *name,
    unsigned int* val
);

Parameters#

handle: Type: NvAR_FeatureHandle

The handle to the feature instance from which you want to get the specified 32-bit unsigned integer parameter.
name: Type: const char *

The key value that is used to access the unsigned integer parameters as defined in nvAR_defs.h.
val: Type: unsigned int*

Pointer to the 32-bit unsigned integer where the retrieved value will be written.

Return Value#

Returns one of the following values:

NVCV_SUCCESS on success
NVCV_ERR_PARAMETER
NVCV_ERR_SELECTOR
NVCV_ERR_GENERAL
NVCV_ERR_MISMATCH

Remarks#

This function gets the value of the specified 32-bit unsigned integer parameter for the specified feature instance and writes the retrieved value to the location that is specified by the val parameter.

NvAR_GetU64#

NvAR_Result NvAR_GetU64(
    NvAR_FeatureHandle handle,
    const char *name,
    unsigned long long *val
);

Parameters#

handle: Type: NvAR_FeatureHandle

The handle to the returned feature instance from which you get the specified 64-bit unsigned integer parameter.
name: Type: const char *

The key value used to access the unsigned 64-bit integer parameters as defined in nvAR_defs.h.
val: Type: unsigned long long*

Pointer to the 64-bit unsigned integer where the retrieved value will be written.

Return Value#

Returns one of the following values:

NVCV_SUCCESS on success
NVCV_ERR_PARAMETER
NVCV_ERR_SELECTOR
NVCV_ERR_GENERAL
NVCV_ERR_MISMATCH

Remarks#

This function gets the value of the specified 64-bit unsigned integer parameter for the specified feature instance and writes the retrieved value to the location specified by the val parameter.

NvAR_SetCudaStream#

NvAR_Result NvAR_SetCudaStream(
    NvAR_FeatureHandle handle,
    const char *name,
    CUStream stream
);

Parameters#

handle: Type: NvAR_FeatureHandle

The handle to the feature instance that is returned for which you want to set the CUDA stream.
name: Type: const char *

The NvAR_Parameter_Config(CUDAStream) key value. Any other key value returns an error.
stream: Type: CUStream

The CUDA stream in which to run the feature instance on the GPU.

Return Value#

Returns one of the following values:

NVCV_SUCCESS on success
NVCV_ERR_PARAMETER
NVCV_ERR_SELECTOR
NVCV_ERR_GENERAL
NVCV_ERR_MISMATCH

Remarks#

This function sets the CUDA stream, in which the specified feature instance will run, to the parameter stream.

Defined in: nvAR.h

NvAR_SetF32#

NvAR_Result NvAR_SetF32(
    NvAR_FeatureHandle handle,
    const char *name,
    float val
);

Parameters#

handle: Type: NvAR_FeatureHandle

The handle to the feature instance for which you want to set the specified 32-bit floating-point parameter.
name: Type: const char *

The key value used to access the 32-bit float parameters as defined in nvAR_defs.h.
val: Type: float

The 32-bit floating-point number to which the parameter is to be set.

Return Value#

Returns one of the following values:

NVCV_SUCCESS on success
NVCV_ERR_PARAMETER
NVCV_ERR_SELECTOR
NVCV_ERR_GENERAL
NVCV_ERR_MISMATCH

Remarks#

This function sets the specified single-precision (32-bit) floating-point parameter for the specified feature instance to the val parameter.

NvAR_SetF64#

NvAR_Result NvAR_SetF64(
    NvAR_FeatureHandle handle,
    const char *name,
    double val
);

Parameters#

handle: Type: NvAR_FeatureHandle

The handle to the feature instance for which you want to set the specified 64-bit floating-point parameter.
name: Type: const char *

The key value used to access the 64-bit float parameters as defined in nvAR_defs.h.
val: Type: double

The 64-bit double-precision floating-point number to which the parameter will be set.

Return Value#

Returns one of the following values:

NVCV_SUCCESS on success
NVCV_ERR_PARAMETER
NVCV_ERR_SELECTOR
NVCV_ERR_GENERAL
NVCV_ERR_MISMATCH

Remarks#

This function sets the specified double-precision (64-bit) floating-point parameter for the specified feature instance to the val parameter.

NvAR_SetF32Array#

NvAR_Result NvAR_SetF32Array(
    NvAR_FeatureHandle handle,
    const char *name,
    float* vals,
    int count
);

Parameters#

handle: Type: NvAR_FeatureHandle

The handle to the feature instance for which you want to set the specified float array.
name: Type: const char *

The key value used to access the float array parameters as defined in nvAR_defs.h.
vals: Type: float*

An array of floating-point numbers to which the parameter will be set.
count: Type: int

Currently unused. The number of elements in the array that is specified by the vals parameter.

Return Value#

Returns one of the following values:

NVCV_SUCCESS on success
NVCV_ERR_PARAMETER
NVCV_ERR_SELECTOR
NVCV_ERR_GENERAL
NVCV_ERR_MISMATCH

Remarks#

This function assigns the array of floating-point numbers that are defined by the vals parameter to the specified floating-point-array parameter for the specified feature instance.

NvAR_SetU32Array#

NvAR_Result NvAR_SetU32Array(
    NvAR_FeatureHandle handle,
    const char *name,
    unsigned int* vals,
    int count
);

Parameters#

handle: Type: NvAR_FeatureHandle

The handle to the feature instance for which you want to set the specified unsigned int array.
name: Type: const char *

The key value used to access the unsigned integer array parameters as defined in nvAR_defs.h.
vals: Type: unsigned int*

An array of unsigned integers to which the parameter will be set.
count: Type: int

Currently unused. The number of elements in the array that is specified by the vals parameter.

Return Value#

Returns one of the following values:

NVCV_SUCCESS on success
NVCV_ERR_PARAMETER
NVCV_ERR_SELECTOR
NVCV_ERR_GENERAL
NVCV_ERR_MISMATCH

Remarks#

This function assigns the array of unsigned integers that are defined by the vals parameter to the specified unsigned integer-array parameter for the specified feature instance.

NvAR_SetObject#

NvAR_Result NvAR_SetObject(
    NvAR_FeatureHandle handle,
    const char *name,
    void *ptr,
    unsigned long typeSize
);

Parameters#

handle: Type: NvAR_FeatureHandle

The handle to the feature instance for which you want to set the specified object.
name: Type: const char *

The key value used to access the object parameters as defined in nvAR_defs.h.
ptr: Type: void *

A pointer to memory that was allocated to the objects that were defined in Structures.
typeSize: Type: unsigned long

The size of the item to which the pointer points. If the size does not match, an NVCV_ERR_MISMATCH is returned.

Return Value#

Returns one of the following values:

NVCV_SUCCESS on success
NVCV_ERR_PARAMETER
NVCV_ERR_SELECTOR
NVCV_ERR_GENERAL
NVCV_ERR_MISMATCH

Remarks#

This function assigns the memory of the object that was specified by the ptr parameter to the specified object parameter for the specified feature instance.

NvAR_SetS32#

NvAR_Result NvAR_SetS32(
    NvAR_FeatureHandle handle,
    const char *name,
    int val
);

Parameters#

handle: Type: NvAR_FeatureHandle

The handle to the feature instance for which you want to set the specified 32-bit signed integer parameter.
name: Type: const char *

The key value used to access the signed 32-bit integer parameters as defined in nvAR_defs.h.
val: Type: int

The 32-bit signed integer to which the parameter will be set.

Return Value#

Returns one of the following values:

NVCV_SUCCESS on success
NVCV_ERR_PARAMETER
NVCV_ERR_SELECTOR
NVCV_ERR_GENERAL
NVCV_ERR_MISMATCH

Remarks#

This function sets the specified 32-bit signed integer parameter for the specified feature instance to the val parameter.

NvAR_SetString#

NvAR_Result NvAR_SetString(
    NvAR_FeatureHandle handle,
    const char *name,
    const char* str
);

Parameters#

handle: Type: NvAR_FeatureHandle

The handle to the feature instance for which you want to set the specified character string parameter.
name: Type: const char *

The key value used to access the string parameters as defined in nvAR_defs.h.
str: Type: const char*

Pointer to the character string to which you want to set the parameter.

Return Value#

Returns one of the following values:

NVCV_SUCCESS on success
NVCV_ERR_PARAMETER
NVCV_ERR_SELECTOR
NVCV_ERR_GENERAL
NVCV_ERR_MISMATCH

Remarks#

This function sets the value of the specified character string parameter for the specified feature instance to the str parameter.

NvAR_SetU32#

NvAR_Result NvAR_SetU32(
    NvAR_FeatureHandle handle,
    const char *name,
    unsigned int val
);

Parameters#

handle: Type: NvAR_FeatureHandle

The handle to the feature instance for which you want to set the specified 32-bit unsigned integer parameter.
name: Type: const char *

The key value used to access the unsigned 32-bit integer parameters as defined in nvAR_defs.h.
val: Type: unsigned int

The 32-bit unsigned integer to which you want to set the parameter.

Return Value#

Returns one of the following values:

NVCV_SUCCESS on success
NVCV_ERR_PARAMETER
NVCV_ERR_SELECTOR
NVCV_ERR_GENERAL
NVCV_ERR_MISMATCH

Remarks#

This function sets the value of the specified 32-bit unsigned integer parameter for the specified feature instance to the val parameter.

NvAR_SetU64#

NvAR_Result NvAR_SetU64(
    NvAR_FeatureHandle handle,
    const char *name,
    unsigned long long val
);

Parameters#

handle: Type: NvAR_FeatureHandle

The handle to the feature instance for which you want to set the specified 64-bit unsigned integer parameter.
name: Type: const char *

The key value used to access the unsigned 64-bit integer parameters as defined in nvAR_defs.h.
val: Type: unsigned long long

The 64-bit unsigned integer to which you want to set the parameter.

Return Value#

Returns one of the following values:

NVCV_SUCCESS on success
NVCV_ERR_PARAMETER
NVCV_ERR_SELECTOR
NVCV_ERR_GENERAL
NVCV_ERR_MISMATCH

Remarks#

This function sets the value of the specified 64-bit unsigned integer parameter for the specified feature instance to the val parameter.

NvAR_ConfigureLogger#

NvCV_Status NvAR_ConfigureLogger(
    int verbosity,
    const char *file,
    void (*cb)(void*, const char*),
    void *cb_data
);

Parameters#

verbosity: Type: int

The maximum level of verbosity to be recorded into the log:

* NVCV_LOG_FATAL (0) - Message printed before aborting due to unrecoverable error

* NVCV_LOG_ERROR (1) - Operation failed, but not fatal

* NVCV_LOG_WARNING (2) - Issue fixed with potential performance impact

* NVCV_LOG_INFO (3) - Informational message

Higher level verbosity includes logs from lower levels.
file: Type: const char*

Used only for stderr/file logging, otherwise NULL. Examples:

* “stderr” - Log to stderr

* “/path/to/log.txt” - Log to specified file
cb: Type: void (*)(void * data, const char * msg)

Callback function pointer with arguments:

* data - Pointer to callback data

* msg - Message to log
cb_data: Type: void*

Pointer provided as first argument to callback function

Return Value#

Returns one of the following values:

NVCV_SUCCESS on success
NVCV_ERR_FILE if specified log file cannot be opened

Logger Types#

The SDK provides several logger implementations in nvCVLoggerExamples.c:

MemLogger: Collects logs into a memory string buffer
StderrLogger: Logs directly to stderr
FileLogger: Logs to a single file
FileThreadLogger: Logs to file in separate thread for better performance
MultifileLogger: Logs to multiple files in rotation

Usage Examples#

Basic Logging

// Log to stderr
NvAR_ConfigureLogger(LOG_ERROR, "stderr", NULL, NULL);

// Log to file
NvAR_ConfigureLogger(LOG_ERROR, "/logs/ar.log", NULL, NULL);

// Disable logging
NvAR_ConfigureLogger(LOG_ERROR, NULL, NULL, NULL);

Custom Logger Examples

// Memory logger
MemLogger memLog;
NvAR_ConfigureLogger(LOG_ERROR, NULL, &MemLogger::Callback, &memLog);

// File logger with append
FileLogger flog("/path/to/ar.log", "a");
NvAR_ConfigureLogger(LOG_ERROR, NULL, &FileLogger::Callback, &flog);

// Multi-file logger (12 files, 64KB each)
MultifileLogger mflog("/path/to/log%02d.log", 65536, 12, 0);
NvAR_ConfigureLogger(LOG_ERROR, NULL, &MultifileLogger::Callback, &mflog);

Dynamic Verbosity

// Save and restore verbosity
int saved_verbosity;
NvAR_ConfigureLogger(LOG_INFO, "same", NULL, &saved_verbosity);
// ... code logged at INFO level ...
NvAR_ConfigureLogger(saved_verbosity, "same", NULL, NULL);

Remarks#

The StderrLogger and FileLogger are compiled into the SDK for easy configuration
FileThreadLogger reduces performance impact compared to standard FileLogger
MultifileLogger is useful for long-running services to prevent unbounded log growth
Custom loggers can be implemented to suit specific application needs
Use “same” as the file parameter to change verbosity while keeping the same logger configuration

NvAR_ResetState#

NvAR_Result NvAR_ResetState(
    NvAR_FeatureHandle handle,
    nvAR_StateHandle state
);

Parameters#

handle [in]: Type: NvAR_FeatureHandle

The handle to the feature instance to be reset.
state [in]: Type: NvAR_StateHandle

The handle to the state object to be reset (nullptr for default state).

Return Value#

Returns one of the following values:

NVCV_SUCCESS on success
NVCV_ERR_MISSINGINPUT
NVCV_ERR_FEATURENOTFOUND
NVCV_ERR_UNIMPLEMENTED

Remarks#

This function resets the input state object of the feature instance with the specified handle. When the state object handle is set to nullptr, the default state is reset. This function is only implemented for the Eye Contact feature and returns NVCV_ERR_UNIMPLEMENTED error for other features.