GXF Core C APIs#

Context#

Create context#

type gxf_context_t#

Type for context handle.

Defined as void*.

kNullContext#

An invalid context.

Defined as nullptr.

kGxfCoreVersion#

GXF Core Version

Defined as 4.1.0.

enum gxf_result_t#

An enumeration type representing GXF error and result codes.

enumerator GXF_SUCCESS#

Operation was successful.

enumerator GXF_FAILURE#

Operation failed.

enumerator GXF_NOT_IMPLEMENTED#

Feature is not implemented.

enumerator GXF_FILE_NOT_FOUND#

File was not found.

enumerator GXF_INVALID_ENUM#

Invalid enumeration value.

enumerator GXF_NULL_POINTER#

Null pointer was passed.

enumerator GXF_UNINITIALIZED_VALUE#

Value was not initialized.

enumerator GXF_ARGUMENT_NULL#

Argument is null.

enumerator GXF_ARGUMENT_OUT_OF_RANGE#

Argument is out of range.

enumerator GXF_ARGUMENT_INVALID#

Invalid argument.

enumerator GXF_OUT_OF_MEMORY#

Out of memory.

enumerator GXF_MEMORY_INVALID_STORAGE_MODE#

Invalid memory storage mode.

enumerator GXF_CONTEXT_INVALID#

Invalid context.

enumerator GXF_EXTENSION_NOT_FOUND#

Extension was not found.

enumerator GXF_EXTENSION_FILE_NOT_FOUND#

Extension file was not found.

enumerator GXF_EXTENSION_NO_FACTORY#

Extension has no factory.

enumerator GXF_FACTORY_TOO_MANY_COMPONENTS#

Too many components in factory.

enumerator GXF_FACTORY_DUPLICATE_TID#

Duplicate type ID in a factory.

enumerator GXF_FACTORY_UNKNOWN_TID#

Unknown type ID in a factory.

enumerator GXF_FACTORY_ABSTRACT_CLASS#

Factory abstract class.

enumerator GXF_FACTORY_UNKNOWN_CLASS_NAME#

Unknown class name in factory.

enumerator GXF_FACTORY_INVALID_INFO#

Invalid factory info.

enumerator GXF_FACTORY_INCOMPATIBLE#

Factory is incompatible.

enumerator GXF_ENTITY_NOT_FOUND#

Entity was not found.

enumerator GXF_ENTITY_NAME_EXCEEDS_LIMIT#

Entity name string exceeds specified limit.

enumerator GXF_ENTITY_COMPONENT_NOT_FOUND#

Entity component was not found.

enumerator GXF_ENTITY_CAN_NOT_ADD_COMPONENT_AFTER_INITIALIZATION#

Cannot add component to entity after initialization.

enumerator GXF_ENTITY_CAN_NOT_REMOVE_COMPONENT_AFTER_INITIALIZATION#

Cannot remove component from entity after initialization.

enumerator GXF_ENTITY_MAX_COMPONENTS_LIMIT_EXCEEDED#

Maximum limit of number of components in an entity exceeded

enumerator GXF_PARAMETER_NOT_FOUND#

Parameter was not found.

enumerator GXF_PARAMETER_ALREADY_REGISTERED#

Parameter is already registered.

enumerator GXF_PARAMETER_INVALID_TYPE#

Invalid parameter type.

enumerator GXF_PARAMETER_OUT_OF_RANGE#

Parameter is out of range.

enumerator GXF_PARAMETER_NOT_INITIALIZED#

Parameter is not initialized.

enumerator GXF_PARAMETER_CAN_NOT_MODIFY_CONSTANT#

Cannot modify constant parameter.

enumerator GXF_PARAMETER_PARSER_ERROR#

Parameter parser error.

enumerator GXF_PARAMETER_NOT_NUMERIC#

Parameter is not numeric.

enumerator GXF_PARAMETER_MANDATORY_NOT_SET#

Mandatory parameter is not set.

enumerator GXF_CONTRACT_INVALID_SEQUENCE#

Invalid contract sequence.

enumerator GXF_CONTRACT_PARAMETER_NOT_SET#

Contract parameter is not set.

enumerator GXF_CONTRACT_MESSAGE_NOT_AVAILABLE#

Contract message is not available.

enumerator GXF_INVALID_LIFECYCLE_STAGE#

Invalid lifecycle stage.

enumerator GXF_INVALID_EXECUTION_SEQUENCE#

Invalid execution sequence.

enumerator GXF_REF_COUNT_NEGATIVE#

Reference count is negative.

enumerator GXF_RESULT_ARRAY_TOO_SMALL#

Result array is too small.

enumerator GXF_INVALID_DATA_FORMAT#

Invalid data format.

enumerator GXF_EXCEEDING_PREALLOCATED_SIZE#

Exceeding preallocated size.

enumerator GXF_QUERY_NOT_ENOUGH_CAPACITY#

Query does not have enough capacity.

enumerator GXF_QUERY_NOT_APPLICABLE#

Query is not applicable.

enumerator GXF_QUERY_NOT_FOUND#

Query was not found.

enumerator GXF_NOT_FINISHED#

Operation is not finished.

enumerator GXF_HTTP_GET_FAILURE#

HTTP GET request failed.

enumerator GXF_HTTP_POST_FAILURE#

HTTP POST request failed.

enumerator GXF_ENTITY_GROUP_NOT_FOUND#

Entity group was not found.

enumerator GXF_RESOURCE_NOT_INITIALIZED#

Resource is not initialized.

enumerator GXF_RESOURCE_NOT_FOUND#

Resource was not found.

enumerator GXF_CONNECTION_BROKEN#

Connection is broken.

enumerator GXF_CONNECTION_ATTEMPTS_EXCEEDED#

Connection attempts exceeded.

enumerator GXF_IPC_CONNECTION_FAILURE#

IPC connection failure.

enumerator GXF_IPC_CALL_FAILURE#

IPC call failure.

enumerator GXF_IPC_SERVICE_NOT_FOUND#

IPC service was not found.

gxf_result_t GxfContextCreate(gxf_context_t *context);#

Creates a new GXF context

A GXF context is required for all almost all GXF operations. The context must be destroyed with ‘GxfContextDestroy’. Multiple contexts can be created in the same process, however they can not communicate with each other.

Parameters:

  • context – The new GXF context is written to the given pointer.

Returns:

GXF_SUCCESS if the operation was successful, or otherwise one of the GXF error codes.

Create a context from a shared context#

gxf_result_t GxfContextCreateShared(
gxf_context_t shared,
gxf_context_t *context,
);#

Creates a new runtime context from shared context.

A shared runtime context is used for sharing entities between graphs running within the same process.

Parameters:

  • shared – A valid GXF shared context.

  • context – The new GXF context is written to the given pointer

Returns:

GXF_SUCCESS if the operation was successful, or otherwise one of the GXF error codes.

Get a shared context from a context#

gxf_result_t GxfGetSharedContext(
gxf_context_t context,
gxf_context_t *shared,
);#

Get a shared context from an existing runtime context.

Parameters:

  • context – A valid GXF shared context.

  • shared – The shared context.

Returns:

GXF_SUCCESS if the operation was successful, or otherwise one of the GXF error codes.

Destroy context#

gxf_result_t GxfContextDestroy(gxf_context_t context);#

Destroys a GXF context

Every GXF context must be destroyed by calling this function. The context must have been previously created with ‘GxfContextCreate’. This will also destroy all entities and components which were created as part of the context.

Parameters:

  • context – A valid GXF context.

Returns:

GXF_SUCCESS if the operation was successful, or otherwise one of the GXF error codes.

Extensions#

kMaxExtensions#

Maximum number of extensions in a context.

Defined as 1024.

GxfLoadExtensionsInfo#

type GxfLoadExtensionsInfo#

A structure specifying parameters for loading extensions.

const char *const *extension_filenames#

Optional list of extension filenames to load.

uint32_t extension_filenames_count#

The number of extensions to load.

const char *const *manifest_filenames#

Optional list of manifest filenames to load.

uint32_t manifest_filenames_count#

The number of manifests to load.

const char *base_directory#

An optional base directory which is prepended to all extensions filenames, including those loaded via manifests.

Load Extension libraries#

gxf_result_t GxfLoadExtensions(
gxf_context_t context,
const GxfLoadExtensionsInfo *info,
);#

Loads GXF extension libraries

Loads one or more extensions either directly by their filename or indirectly by loading manifest files. Before a component can be added to a GXF entity the GXF extension shared library providing the component must be loaded. An extensions must only be loaded once.

To simplify loading multiple extensions at once the developer can create a manifest file which lists all extensions he needs. This function will then load all extensions listed in the manifest file. Multiple manifest may be loaded, however each extensions may still be loaded only a single time.

A manifest file is a YAML file with a single top-level entry ‘extensions’ followed by a list of filenames of GXF extension shared libraries.

Example: —– START OF FILE —– extensions: - gxf/std/libgxf_std.so - gxf/npp/libgxf_npp.so —– END OF FILE —–

Parameters:

  • context – A valid GXF context

  • filename – A valid filename.

Returns:

GXF_SUCCESS if the operation was successful, or otherwise one of the GXF error codes.

Load Extension from a pointer#

gxf_result_t GxfLoadExtensionFromPointer(
gxf_context_t context,
void *extension_ptr,
);#

Loads an extension from a pointer to the Extension object.

Parameters:

  • context – A valid GXF context

  • extension_ptr – A pointer to Extension

Returns:

GXF_SUCCESS if the operation was successful, or otherwise one of the GXF error codes.

Load Metadata files#

gxf_result_t GxfLoadExtensionMetadataFiles(
gxf_context_t context,
const char *const *filenames,
uint32_t count,
);#

Loads a metadata file generated by the gxf_registry

The gxf_registry tool generates a metadata file of the contents of an extension during registration. These metadata files can be used to resolve typename and TID’s of components for other extensions which depend on them. metadata files do not contain the actual implementation of the extension and must be loaded only to run the extension query API’s on extension libraries which have the actual implementation and only depend on the metadata for type resolution.

If some components of extension B depend on some components in extension A: - Load metadata file for extension A - Load extension library for extension B using ‘GxfLoadExtensions’ - Run extension query api’s on extension B and it’s components.

Parameters:

  • context – A valid GXF context.

  • filenames – absolute paths of metadata files generated by the registry during extension registration

  • count – The number of metadata files to be loaded

Returns:

GXF_SUCCESS if the operation was successful, or otherwise one of the GXF error codes.

Register component#

gxf_result_t GxfRegisterComponent(
gxf_context_t context,
gxf_tid_t tid,
const char *name,
const char *base_name,
);#

Registers a component with a GXF extension

A GXF extension need to register all of its components in the extension factory function. For convenience the helper macros in gxf/std/extension_factory_helper.hpp can be used.

The developer must choose a unique GXF tid with two random 64-bit integers. The developer must ensure that every GXF component has a unique tid. The name of the component must be the fully qualified C++ type name of the component. A component may only have a single base class and that base class must be specified with its fully qualified C++ type name as the parameter ‘base_name’.

ref: gxf/std/extension_factory_helper.hpp ref: core/type_name.hpp

Parameters:

  • context – A valid GXF context

  • tid – The chosen GXF tid

  • name – The type name of the component

  • base_name – The type name of the base class of the component

Returns:

GXF_SUCCESS if the operation was successful, or otherwise one of the GXF error codes.

Register a component during runtime#

gxf_result_t GxfRegisterComponentInExtension(
gxf_context_t context,
gxf_tid_t component_tid,
gxf_tid_t extension_tid,
);#

Registers a new component from an extension during runtime

Once an extension is loaded any newly added components to that extension can be registered with the context using this function

Parameters:

  • context – A valid GXF context

  • component_tid – The valid GXF tid of a unregistered new component

  • extension_tid – The valid GXF tid of an extension which has already been loaded

Returns:

GXF_SUCCESS if the operation was successful, or otherwise one of the GXF error codes.

Graph Execution#

Loads a list of entities from YAML file#

gxf_result_t GxfGraphLoadFile(
gxf_context_t context,
const char *filename,
const char *parameters_override[],
const uint32_t num_overrides,
);#
Parameters:

  • context – A valid GXF context

  • filename – A valid YAML filename.

  • params_override – An optional array of strings used for override parameters in yaml file.

  • num_overrides – Number of optional override parameter strings.

Returns:

GXF_SUCCESS if the operation was successful, or otherwise one of the GXF error codes.

Set the root folder for searching YAML files during loading#

gxf_result_t GxfGraphSetRootPath(
gxf_context_t context,
const char *path,
);#
Parameters:

  • context – A valid GXF context

  • path – Path to root folder for searching YAML files during loading

Returns:

GXF_SUCCESS if the operation was successful, or otherwise one of the GXF error codes.

Loads a list of entities from YAML text#

gxf_result_t GxfGraphParseString(
gxf_context_t context,
const char *tex,
const char *parameters_override[],
const uint32_t num_overrides,
);#
Parameters:

  • context – A valid GXF context

  • text – A valid YAML text.

  • params_override – An optional array of strings used for override parameters in yaml file.

  • num_overrides – Number of optional override parameter strings.

Returns:

GXF_SUCCESS if the operation was successful, or otherwise one of the GXF error codes.

Activate all system components#

gxf_result_t GxfGraphActivate(gxf_context_t context);#
Parameters:

  • context – A valid GXF context

Returns:

GXF_SUCCESS if the operation was successful, or otherwise one of the GXF error codes.

Deactivate all System components#

gxf_result_t GxfGraphDeactivate(gxf_context_t context);#
Parameters:

  • context – A valid GXF context

Returns:

GXF_SUCCESS if the operation was successful, or otherwise one of the GXF error codes.

Starts the execution of the graph asynchronously#

gxf_result_t GxfGraphRunAsync(gxf_context_t context);#
Parameters:

  • context – A valid GXF context

Returns:

GXF_SUCCESS if the operation was successful, or otherwise one of the GXF error codes.

Interrupt the execution of the graph#

gxf_result_t GxfGraphInterrupt(gxf_context_t context);#
Parameters:

  • context – A valid GXF context

Returns:

GXF_SUCCESS if the operation was successful, or otherwise one of the GXF error codes.

Waits for the graph to complete execution#

gxf_result_t GxfGraphWait(gxf_context_t context);#
Parameters:

  • context – A valid GXF context

Returns:

GXF_SUCCESS if the operation was successful, or otherwise one of the GXF error codes.`

Runs all System components and waits for their completion#

gxf_result_t GxfGraphRun(gxf_context_t context);#
Parameters:

  • context – A valid GXF context

Returns:

GXF_SUCCESS if the operation was successful, or otherwise one of the GXF error codes.

Entities#

type gxf_uid_t#

Type of unique GXF object identifiers (UID/uid).

Uids are used to reference entities and components throughout the GXF API.

Defined as int64_t.

kNullUid#

A GXF UID which can be used to indicate an invalid or unused GXF UID.

Defined as 0L.

kUnspecifiedUid#

A GXF UID which can be used to indicate an unspecified component during graph load operation. This component should be updated in a subsequent graph/parameters file. Failing to do so will result in an error during graph activation.

Defined as -1L.

type gxf_tid_t#

Type of unique GXF type identifier (TID/tid)

Tids are used to uniquely identify the type of a component, instead of for example using a string with the type name.

uint64_t hash1#

The first part of the hash.

uint64_t hash2#

The second part of the hash.

kMaxEntities#

Maximum number of entities in a context.

Defined as 1024.

enum gxf_entity_status_t#

An enumeration representing various lifecycle states of an entity.

enumerator GXF_ENTITY_STATUS_NOT_STARTED#

Entity has not started.

enumerator GXF_ENTITY_STATUS_START_PENDING#

Entity start is pending.

enumerator GXF_ENTITY_STATUS_STARTED#

Entity has started.

enumerator GXF_ENTITY_STATUS_TICK_PENDING#

Entity tick is pending.

enumerator GXF_ENTITY_STATUS_TICKING#

Entity is ticking.

enumerator GXF_ENTITY_STATUS_IDLE#

Entity is idle.

enumerator GXF_ENTITY_STATUS_STOP_PENDING#

Entity stop is pending.

enumerator GXF_ENTITY_MAX#

Entity max

type GxfFlags#

GXF bitmasks.

Defined as uint32_t.

type GxfEntityCreateFlags#

Bitmask of GxfEntityCreateFlagBits.

type GxfEntityCreateFlagBits#

Bitmask specifying storage mode for an entity.

type GXF_ENTITY_CREATE_PROGRAM_BIT#

specifies that the entity will be added to the program entities. Program entities are kept alive for the duration of the program. They are activated automatically when the program is activated and deactivated when the program is deactivated. If the program was already activated when the entity is created the entity must still be activated manually.

type GxfEntityCreateInfo#

A structure specifying parameters for creating entities.

const char *entity_name#

the name of the entity which is created. If this is a nullptr an undefined unique name is chosen. The name must not start with a double underscore.

GxfEntityCreateFlags flags#

Bitmask of GxfEntityCreateFlagsBits indicating storage method and usage behavior for the created entity.

Create an entity#

gxf_result_t GxfCreateEntity(
gxf_context_t context,
const GxfEntityCreateInfo *info,
gxf_uid_t *eid,
);#

Create a new GXF entity.

Entities are light-weight containers to hold components and form the basic building blocks of a GXF application. Entities are created when a GXF file is loaded, or they can be created manually using this function. Entities created with this function must be destroyed using ‘GxfEntityDestroy’. After the entity was created components can be added to it with ‘GxfComponentAdd’. To start execution of codelets on an entity the entity needs to be activated first. This can happen automatically using ‘GXF_ENTITY_CREATE_PROGRAM_BIT’ or manually using ‘GxfEntityActivate’.

Parameters:

  • context – GXF context that creates the entity.

  • info – pointer to a GxfEntityCreateInfo structure containing parameters affecting the creation of the entity.

  • eid – pointer to a gxf_uid_t handle in which the resulting entity is returned.

Returns:

GXF_SUCCESS if the operation was successful, or otherwise one of the GXF error codes.

gxf_result_t GxfCreateEntityAndGetItem(
gxf_context_t context,
const GxfEntityCreateInfo *info,
gxf_uid_t *eid,
void **item_ptr,
);#

Create a new GXF entity and return the entity item ptr

Entities are light-weight containers to hold components and form the basic building blocks of a GXF application. Entities are created when a GXF file is loaded, or they can be created manually using this function. Entities created with this function must be destroyed using ‘GxfEntityDestroy’. After the entity was created components can be added to it with ‘GxfComponentAdd’. To start execution of codelets on an entity the entity needs to be activated first. This can happen automatically using ‘GXF_ENTITY_CREATE_PROGRAM_BIT’ or manually using ‘GxfEntityActivate’. This function also returns the pointer entity item which can be used to create C++ nvidia::gxf::Entity type objects.

Parameters:

  • context – is the GXF context that creates the entity.

  • info – is a pointer to a GxfEntityCreateInfo structure containing parameters affecting the creation of the entity.

  • eid – is a pointer to a gxf_uid_t handle in which the resulting entity is returned.

  • item_ptr – is a pointer to pointer to entity item which is created

Returns:

On success the function returns GXF_SUCCESS.

Activate an entity#

gxf_result_t GxfEntityActivate(gxf_context_t context, gxf_uid_t eid);#

Activates a previously created and inactive entity

Activating an entity generally marks the official start of its lifetime and has multiple implications: - If mandatory parameters, i.e. parameter which do not hav the flag “optional”, are not set the operation will fail.

  • All components on the entity are initialized.

  • All codelets on the entity are scheduled for execution. The scheduler will start calling start, tick and stop functions as specified by scheduling terms.

  • After activation trying to change a dynamic parameters will result in a failure.

  • Adding or removing components of an entity after activation will result in a failure.

Parameters:

  • context – A valid GXF context

  • eid – UID of a valid entity

Returns:

GXF error code

Deactivate an entity#

gxf_result_t GxfEntityDeactivate(
gxf_context_t context,
gxf_uid_t eid,
);#

Deactivates a previously activated entity

Deactivating an entity generally marks the official end of its lifetime and has multiple implications:

  • All codelets are removed from the schedule. Already running entities are run to completion.

  • All components on the entity are deinitialized.

  • Components can be added or removed again once the entity was deactivated.

  • Mandatory and non-dynamic parameters can be changed again.

Note: In case that the entity is currently executing this function will wait and block until

the current execution is finished.

Parameters:

  • context – A valid GXF context

  • eid – UID of a valid entity

Returns:

GXF error code

Destroy an entity#

gxf_result_t GxfEntityDestroy(gxf_context_t context, gxf_uid_t eid);#

Destroys a previously created entity

Destroys an entity immediately. The entity is destroyed even if the reference count has not yet reached 0. If the entity is active it is deactivated first.

Note: This function can block for the same reasons as ‘GxfEntityDeactivate’.

Parameters:

  • context – A valid GXF context

  • eid – The returned UID of the created entity

Returns:

GXF_SUCCESS if the operation was successful, or otherwise one of the GXF error codes.

Find an entity#

gxf_result_t GxfEntityFind(
gxf_context_t context,
const char *name,
gxf_uid_t *eid,
);#

Finds an entity by its name

Parameters:

  • context – A valid GXF context

  • name – A C string with the name of the entity. Ownership is not transferred.

  • eid – The returned UID of the entity

Returns:

GXF_SUCCESS if the operation was successful, or otherwise one of the GXF error codes.

Find all entities#

gxf_result_t GxfEntityFindAll(
gxf_context_t context,
uint64_t *num_entities,
gxf_uid_t *entities,
);#

Finds all entities in the current application

Finds and returns all entity ids for the current application. If more than max_entities exist only max_entities will be returned. The order and selection of entities returned is abritrary.

Parameters:

  • context – A valid GXF context

  • num_entities – In/Out: the max number of entities that can fit in the buffer/the number of entities that exist in the application

  • entities – A buffer allocated by the caller for returned UIDs of all entities, with capacity for num_entities.

Returns:

GXF_SUCCESS if the operation was successful, GXF_QUERY_NOT_ENOUGH_CAPACITY if more entites exist in the application than max_entities, or otherwise one of the GXF error codes.

Increase reference count of an entity#

gxf_result_t GxfEntityRefCountInc(
gxf_context_t context,
gxf_uid_t eid,
);#

Increases the reference count for an entity by 1.

By default reference counting is disabled for an entity. This means that entities created with ‘GxfEntityCreate’ are not automatically destroyed. If this function is called for an entity with disabled reference count, reference counting is enabled and the reference count is set to 1. Once reference counting is enabled an entity will be automatically destroyed if the reference count reaches zero, or if ‘GxfEntityCreate’ is called explicitely.

Parameters:

  • context – A valid GXF context

  • eid – The UID of a valid entity

Returns:

GXF_SUCCESS if the operation was successful, or otherwise one of the GXF error codes.

Decrease reference count of an entity#

gxf_result_t GxfEntityRefCountDec(
gxf_context_t context,
gxf_uid_t eid,
);#

Decreases the reference count for an entity by 1.

See ‘GxfEntityRefCountInc’ for more details on reference counting.

Parameters:

  • context – A valid GXF context

  • eid – The UID of a valid entity

Returns:

GXF_SUCCESS if the operation was successful, or otherwise one of the GXF error codes.

Get the reference count of an entity#

gxf_result_t GxfEntityGetRefCount(
gxf_context_t context,
gxf_uid_t eid,
int64_t *count,
);#

Provides the reference count for an entity.

See ‘GxfEntityRefCountInc’ for more details on reference counting.

Parameters:

  • context – A valid GXF context

  • eid – The unique object ID (UID) of a valid entity

  • count – The reference count of a valid entity

Returns:

GXF_SUCCESS if the operation was successful, or otherwise one of the GXF error codes.

Get status of an entity#

gxf_result_t GxfEntityGetStatus(
gxf_context_t context,
gxf_uid_t eid,
gxf_entity_status_t *entity_status,
);#

Gets the status of the entity.

See ‘gxf_entity_status_t’ for the various status.

Parameters:

  • context – A valid GXF context

  • eid – The UID of a valid entity

  • entity_status – output; status of an entity eid

Returns:

GXF_SUCCESS if the operation was successful, or otherwise one of the GXF error codes.

const char *GxfEntityStatusStr(gxf_entity_status_t status);#

Gets a string describing an GXF entity status.

The caller does not get ownership of the return C string and must not delete it.

Parameters:

  • status – A GXF entity status

Returns:

A pointer to a C string with the entity status description.

Gets the name of the entity#

gxf_result_t GxfEntityGetName(
gxf_context_t context,
gxf_uid_t eid,
const char **entity_name,
);#
Parameters:

  • context – A valid GXF context

  • eid – The unique object ID (UID) of a valid entity

  • entity_name – output; name of the entity

Returns:

GXF_SUCCESS if the operation was successful, or otherwise one of the GXF error codes.

Get state of an entity#

enum entity_state_t#

An enumeration used by behavior parent codelet in Behavior Tree denoting the result of codelet::tick().

enumerator GXF_BEHAVIOR_INIT#

For codelet that have not yet started running.

enumerator GXF_BEHAVIOR_SUCCESS#

For codelet that terminates with success after ticking.

enumerator GXF_BEHAVIOR_RUNNING#

For codelet that needs multiple ticks to complete.

enumerator GXF_BEHAVIOR_FAILURE#

For codelet that terminates with failure after ticking.

enumerator GXF_BEHAVIOR_UNKNOWN#

For non-behavior-tree codelet because we don’t care about the behavior status returned by controller if it is not a BT codelet.

gxf_result_t GxfEntityGetState(
gxf_context_t context,
gxf_uid_t eid,
entity_state_t *entity_state,
);#

Gets the state of the entity.

See ‘gxf_entity_status_t’ for the various status.

Parameters:

  • context – A valid GXF context

  • eid – The UID of a valid entity

  • entity_state – output; behavior status of an entity eid used by the behavior tree parent codelet

Returns:

GXF_SUCCESS if the operation was successful, or otherwise one of the GXF error codes.

Notify entity of an event#

gxf_result_t GxfEntityEventNotify(
gxf_context_t context,
gxf_uid_t eid,
);#

Notifies the occurrence of an event and inform the scheduler to check the status of the entity

The entity must have an ‘AsynchronousSchedulingTerm’ scheduling term component and it must be in “EVENT_WAITING” state for the notification to be acknowledged.

See ‘AsynchronousEventState’ for various states

Parameters:

  • context – A valid GXF context

  • eid – The UID of a valid entity

Returns:

GXF_SUCCESS if the operation was successful, or otherwise one of the GXF error codes.

Notify entity of an event including the event type#

enum gxf_event_t#

An enumeration of various types of events used to communicate with a GXF scheduler.

GXF_EVENT_EXTERNAL is supported by all GXF schedulers and the rest of the event types are supported by event based scheduler only. GXF_EVENT_EXTERNAL is typically intended to be used by events originating outside of the GXF framework by threads which are not owned by GXF. All other event types occur within GXF and each of them describe a specific event trigger scenario

enumerator GXF_EVENT_CUSTOM#
enumerator GXF_EVENT_EXTERNAL#
enumerator GXF_EVENT_MEMORY_FREE#
enumerator GXF_EVENT_MESSAGE_SYNC#
enumerator GXF_EVENT_TIME_UPDATE#
enumerator GXF_EVENT_STATE_UPDATE#
gxf_result_t GxfEntityNotifyEventType(
gxf_context_t context,
gxf_uid_t eid,
gxf_event_t event,
);#

Notifies the occurrence of an event with event type and inform the scheduler to check the status of the entity

GXF_EVENT_EXTERNAL is supported by all GXF schedulers and the rest of the event types are supported by event based scheduler only.

Parameters:

  • context – A valid GXF context

  • eid – The UID of a valid entity

  • event – The type of event. Can be GXF_EVENT_CUSTOM, GXF_EVENT_EXTERNAL, GXF_EVENT_MEMORY_FREE, GXF_EVENT_MESSAGE_SYNC, GXF_EVENT_TIME_UPDATE, GXF_EVENT_STATE_UPDATE.

Returns:

GXF_SUCCESS if the operation was successful, or otherwise one of the GXF error codes.

const char *GxfEventStr(gxf_event_t event);#

Gets a string describing an GXF event type.

The caller does not get ownership of the return C string and must not delete it.

Parameters:

  • result – A GXF error code

Returns:

A pointer to a C string with the error code description.

Check if an entity is valid#

gxf_result_t GxfEntityIsValid(
gxf_context_t context,
gxf_uid_t eid,
bool *valid,
);#

Check if an entity id is valid currently in GXF runtime.

Parameters:

  • context – A valid GXF context

  • eid – eid of an Entity to check

  • valid – returned boolean indicating if the entity is valid in Gxf runtime(warden)

Returns:

GXF_SUCCESS if the operation was successful, or otherwise one of the GXF error codes.

Components#

kMaxComponents#

Maximum number of components in an entity or extension.

Defined as 1024.

kMaxEntityNameSize#

Maximum number of characters in the name of an entity.

Defined as 2048.

kMaxComponentNameSize#

Maximum number of characters in the name of a component.

Defined as 256.

Get component type identifier#

gxf_result_t GxfComponentTypeId(
gxf_context_t context,
const char *name,
gxf_tid_t *tid,
);#

Gets the GXF unique type ID (TID) of a component

Get the unique type ID which was used to register the component with GXF. The function expects the fully qualified C++ type name of the component including namespaces.

Example of a valid component type name: “nvidia::gxf::test::PingTx”

Parameters:

  • context – A valid GXF context

  • name – The fully qualified C++ type name of the component

  • tid – The returned TID of the component

Returns:

GXF_SUCCESS if the operation was successful, or otherwise one of the GXF error codes.

Get component type name#

gxf_result_t GxfComponentTypeName(
gxf_context_t context,
gxf_tid_t tid,
const char **name,
);#

Gets the fully qualified C++ type name GXF component typename

Get the unique typename of the component with which it was registered using one of the GXF_EXT_FACTORY_ADD*() macros

Parameters:

  • context – A valid GXF context

  • tid – The unique type ID (TID) of the component with which the component was registered

  • name – The returned name of the component

Returns:

GXF_SUCCESS if the operation was successful, or otherwise one of the GXF error codes.

Get component type name from component UID#

gxf_result_t GxfComponentTypeNameFromUID(
gxf_context_t context,
gxf_uid_t cid,
const char **name,
);#

Gets the fully qualified C++ type name GXF component typename from the component UID

Get the unique typename of the component with which it was registered using one of the GXF_EXT_FACTORY_ADD*() macros

Parameters:

  • context – A valid GXF context

  • cid – The UID of a valid component

  • name – The returned name of the component

Returns:

GXF_SUCCESS if the operation was successful, or otherwise one of the GXF error codes.

Get component name#

gxf_result_t GxfComponentName(
gxf_context_t context,
gxf_uid_t cid,
const char **name,
);#

Gets the name of a component

Each component has a user-defined name which was used in the call to ‘GxfComponentAdd’. Usually the name is specified in the GXF application file.

Parameters:

  • context – A valid GXF context

  • cid – The unique object ID (UID) of the component

  • name – The returned name of the component

Returns:

GXF_SUCCESS if the operation was successful, or otherwise one of the GXF error codes.

Get unique identifier of the entity of given component#

gxf_result_t GxfComponentEntity(
gxf_context_t context,
gxf_uid_t cid,
gxf_uid_t *eid,
);#

Gets the unique object ID of the entity of a component

Each component has a unique ID with respect to the context and is stored in one entity. This function can be used to retreive the ID of the entity to which a given component belongs.

Parameters:

  • context – A valid GXF context

  • cid – The unique object ID (UID) of the component

  • eid – The returned UID of the entity

Returns:

GXF_SUCCESS if the operation was successful, or otherwise one of the GXF error codes.

Gets the pointer to an entity item#

gxf_result_t GxfEntityGetItemPtr(
gxf_context_t context,
gxf_uid_t eid,
void **ptr,
);#

Each entity has a unique ID with respect to the context and is stored in the entity warden. This function can be used to retrieve the pointer to entity item stored in the entity warden for a given entity id.

Parameters:

  • context – A valid GXF context

  • eid – The unique object ID (UID) of the entity

  • ptr – The returned pointer to the entity item

Returns:

GXF_SUCCESS if the operation was successful, or otherwise one of the GXF error codes.

Add a new component#

gxf_result_t GxfComponentAdd(
gxf_context_t context,
gxf_uid_t eid,
gxf_tid_t tid,
const char *name,
gxf_uid_t *cid,
);#

Adds a new component to an entity

An entity can contain multiple components and this function can be used to add a new component to an entity. A component must be added before an entity is activated, or after it was deactivated. Components must not be added to active entities. The order of components is stable and identical to the order in which components are added (see ‘GxfComponentFind’).

Parameters:

  • context – A valid GXF context

  • eid – The unique object ID (UID) of the entity to which the component is added.

  • tid – The unique type ID (TID) of the component to be added to the entity.

  • name – The name of the new component. Ownership is not transferred.

  • cid – The returned UID of the created component

Returns:

GXF_SUCCESS if the operation was successful, or otherwise one of the GXF error codes.

Adds a new component to an entity and returns the pointer to the component#

gxf_result_t GxfComponentAddAndGetPtr(
gxf_context_t context,
void *item_ptr,
gxf_tid_t tid,
const char *name,
gxf_uid_t *cid,
void **comp_ptr,
);#

An entity can contain multiple components and this function can be used to add a new component to an Entity. A component must be added before an entity is activated, or after it was deactivated. Components must not be added to active entities. The order of components is stable and identical to the order in which components are added (see ‘GxfComponentFind’).

Parameters:

  • context – A valid GXF context

  • item_ptr – The pointer to entity item

  • tid – The unique type ID (TID) of the component to be added to the entity.

  • name – The name of the new component. Ownership is not transferred.

  • cid – The returned UID of the created component

  • comp_ptr – The returned pointer to the created component object

Returns:

GXF_SUCCESS if the operation was successful, or otherwise one of the GXF error codes.

Remove a component#

gxf_result_t GxfComponentRemoveWithUID(
gxf_context_t context,
gxf_uid_t cid,
);#

Removes a component from an entity

An entity can contain multiple components and this function can be used to remove a component from an entity. A component must be removed before an entity is activated, or after it was deactivated. Components must not be removed from active entities.

Parameters:

  • context – A valid GXF context

  • cid – The UID of the component

Returns:

GXF_SUCCESS if the operation was successful, or otherwise one of the GXF error codes.

gxf_result_t GxfComponentRemove(
gxf_context_t context,
gxf_uid_t eid,
gxf_tid_t tid,
const char *name,
);#

Removes a component from an entity

An entity can contain multiple components and this function can be used to remove a component from an entity. A component must be removed before an entity is activated, or after it was deactivated. Components must not be removed from active entities.

Parameters:

  • context – A valid GXF context

  • eid – The unique object ID (UID) of the entity to which the component is added.

  • tid – The unique type ID (TID) of the component to be added to the entity.

  • name – The name of the new component. Ownership is not transferred.

Returns:

GXF_SUCCESS if the operation was successful, or otherwise one of the GXF error codes.

Add component to entity interface#

gxf_result_t GxfComponentAddToInterface(
gxf_context_t context,
gxf_uid_t eid,
gxf_uid_t cid,
const char *name,
);#

Adds an existing component to the interface of an entity

An entity can holds references to other components in its interface, so that when finding a component in an entity, both the component this entity holds and those it refers to will be returned. This supports the case when an entity contains a subgraph, then those components that has been declared in the subgraph interface will be put to the interface of the parent entity.

Parameters:

  • context – A valid GXF context

  • eid – The unique object ID (UID) of the entity to which the component is added.

  • cid – The unique object ID of the component.

  • name – The name of the new component. Ownership is not transferred.

Returns:

GXF_SUCCESS if the operation was successful, or otherwise one of the GXF error codes.

Find a component in an entity#

gxf_result_t GxfComponentFind(
gxf_context_t context,
gxf_uid_t eid,
gxf_tid_t tid,
const char *name,
int32_t *offset,
gxf_uid_t *cid,
);#

Finds a component in an entity

Searches components in an entity which satisfy certain criteria: component type, component name, and component min index. All three criteria are optional; in case no criteria is given the first component is returned. The main use case for “component min index” is a repeated search which continues at the index which was returned by a previous search.

In case no entity with the given criteria was found GXF_ENTITY_NOT_FOUND is returned.

Parameters:

  • context – A valid GXF context

  • eid – The unique object ID (UID) of the entity which is searched.

  • tid – The component type ID (TID) of the component to find (optional)

  • name – The component name of the component to find (optional). Ownership not transferred.

  • offset – The index of the first component in the entity to search. Also contains the index of the component which was found.

  • cid – The returned UID of the searched component

Returns:

GXF_SUCCESS if a component matching the criteria was found, GXF_ENTITY_NOT_FOUND if no component matching the criteria was found, or otherwise one of the GXF error codes.

Finds a component in an entity and returns pointer to component#

gxf_result_t GxfComponentFindAndGetPtr(
gxf_context_t context,
gxf_uid_t eid,
void *item_ptr,
gxf_tid_t tid,
const char *name,
int32_t *offset,
gxf_uid_t *cid,
void **ptr,
);#

Searches components in an entity which satisfy certain criteria: component type, component name. All two criteria are optional; in case no criteria is given the first component is returned. The main use case for “component min index” is a repeated search which continues at the index which was returned by a previous search.

In case no entity with the given criteria was found GXF_ENTITY_NOT_FOUND is returned.

Parameters:

  • context – A valid GXF context

  • eid – The unique object ID (UID) of the entity which is searched.

  • item_ptr – The pointer to entity item

  • tid – The component type ID (TID) of the component to find (optional)

  • name – The component name of the component to find (optional). Ownership not transferred.

  • offset – The index of the first component in the entity to search. Also contains the index of the component which was found.

  • cid – The returned UID of the searched component

  • ptr – The returned pointer of the searched component

Returns:

GXF_SUCCESS if a component matching the criteria was found, GXF_ENTITY_NOT_FOUND if no component matching the criteria was found, or otherwise one of the GXF error codes.

Find all components in an entity#

gxf_result_t GxfComponentFindAll(
gxf_context_t context,
gxf_uid_t eid,
uint64_t *num_cids,
gxf_uid_t *cids,
);#

Finds all components in an entity

Finds and returns all component ids for the given entity. If more than num_cids exist GXF_QUERY_NOT_ENOUGH_CAPACITY will be returned and num_cids will be updated to the actual number of components in the entity.

Parameters:

  • context – A valid GXF context

  • eid – The unique object ID (UID) of the entity which is searched.

  • num_cids – In/Out: the max number of components that can fit in the buffer/the number of components that exist in the entity

  • cids – A buffer allocated by the caller for returned UIDs of all components, with capacity for num_cids.

Returns:

GXF_SUCCESS if the operation was successful, GXF_QUERY_NOT_ENOUGH_CAPACITY if more components exist in the entity than num_cids, or otherwise one of the GXF error codes.

Get type identifier for a component#

gxf_result_t GxfComponentType(
gxf_context_t context,
gxf_uid_t cid,
gxf_tid_t *tid,
);#

Gets the component type ID (TID) of a component

Parameters:

  • context – A valid GXF context

  • cid – The component object ID (UID) for which the component type is requested.

  • tid – The returned TID of the component

Returns:

GXF_SUCCESS if the operation was successful, or otherwise one of the GXF error codes.

Gets pointer to component#

gxf_result_t GxfComponentPointer(
gxf_context_t context,
gxf_uid_t uid,
gxf_tid_t tid,
void **pointer,
);#

Verifies that a component exists, has the given type, gets a pointer to it.

Parameters:

  • context – A valid GXF context

  • uid – The component object ID (UID).

  • tid – The expected component type ID (TID) of the component

  • pointer – The returned pointer to the component object.

Returns:

GXF_SUCCESS if the operation was successful, or otherwise one of the GXF error codes.

Check if a component is derived from another component#

gxf_result_t GxfComponentIsBase(
gxf_context_t context,
gxf_tid_t derived,
gxf_tid_t base,
bool *result,
);#

Check if a registered type in an extension is derived from another registered type from the same or any other extension.

This is useful query the component hierarchies using their type id’s. Both the derived and base types have to be registered in an extension via one of the registered via GXF_EXT_FACTORY_ADD* macros.

Parameters:

  • context – A valid GXF context

  • derived – The type ID (TID) of a derived type

  • base – The type ID (TID) of a base type

Returns:

GXF_SUCCESS if the operation was successful, or otherwise one of the GXF error codes.

Parameter#

kMaxParameters#

Maximum number of parameters in a component.

Defined as 1024.

enum gxf_parameter_flags_t_#

Flags describing the behavior of a parameter. Parameter flags are specified when a parameter is registered as part of the component interface. Multiple flags can be OR combined.

enumerator GXF_PARAMETER_FLAGS_NONE#

No additional flags are set (the default). This means the parameter is mandatory and static. The parameter must be set before entity activation and can not be changed after entity activation.

enumerator GXF_PARAMETER_FLAGS_OPTIONAL#

The parameter value is optional and might not be available after entity activation. This implies that it is not allowed to access the parameter with ‘get()’ in the C++ API. Instead ‘try_get’ must be used.

enumerator GXF_PARAMETER_FLAGS_DYNAMIC#

The parameter is dynamic an might change after entity activation. However it is still guaranteed that parameters do not change during the initialize, deinitialize, start, tick, or stop functions.

type gxf_parameter_flags_t#

typedef uint32_t gxf_parameter_flags_t

Type used for parameter flags. See gxf_parameter_flags_t_.

64-bit floating point#

Set#

gxf_result_t GxfParameterSetFloat64(
gxf_context_t context,
gxf_uid_t uid,
const char *key,
double value,
);#
Parameters:

  • context – A valid GXF context.

  • uid – A valid component identifier.

  • key – A valid name of a component to set.

  • value – a double value

Returns:

GXF_SUCCESS if the operation was successful, or otherwise one of the GXF error codes.

Get#

gxf_result_t GxfParameterGetFloat64(
gxf_context_t context,
gxf_uid_t uid,
const char *key,
double *value,
);#
Parameters:

  • context – A valid GXF context.

  • uid – A valid component identifier.

  • key – A valid name of a component to set.

  • value – pointer to get the double value.

Returns:

GXF_SUCCESS if the operation was successful, or otherwise one of the GXF error codes.

64-bit signed integer#

Set#

gxf_result_t GxfParameterSetInt64(
gxf_context_t context,
gxf_uid_t uid,
const char *key,
int64_t value,
);#
Parameters:

  • context – A valid GXF context.

  • uid – A valid component identifier.

  • key – A valid name of a component to set.

  • value – 64-bit integer value to set.

Returns:

GXF_SUCCESS if the operation was successful, or otherwise one of the GXF error codes.

Get#

gxf_result_t GxfParameterGetInt64(
gxf_context_t context,
gxf_uid_t uid,
const char *key,
int64_t *value,
);#
Parameters:

  • context – A valid GXF context.

  • uid – A valid component identifier.

  • key – A valid name of a component to set.

  • value – pointer to get the 64-bit integer value.

Returns:

GXF_SUCCESS if the operation was successful, or otherwise one of the GXF error codes.

64-bit unsigned integer#

Set#

gxf_result_t GxfParameterSetUInt64(
gxf_context_t context,
gxf_uid_t uid,
const char *key,
uint64_t value,
);#
Parameters:

  • context – A valid GXF context.

  • uid – A valid component identifier.

  • key – A valid name of a component to set.

  • value – unsigned 64-bit integet value to set.

Returns:

GXF_SUCCESS if the operation was successful, or otherwise one of the GXF error codes.

Get#

gxf_result_t GxfParameterGetUInt64(
gxf_context_t context,
gxf_uid_t uid,
const char *key,
uint64_t *value,
);#
Parameters:

  • context – A valid GXF context.

  • uid – A valid component identifier.

  • key – A valid name of a component to set.

  • value – pointer to get the unsigned 64-bit integer value.

Returns:

GXF_SUCCESS if the operation was successful, or otherwise one of the GXF error codes.

32-bit signed integer#

Set#

gxf_result_t GxfParameterSetInt32(
gxf_context_t context,
gxf_uid_t uid,
const char *key,
int32_t value,
);#
Parameters:

  • context – A valid GXF context.

  • uid – A valid component identifier.

  • key – A valid name of a component to set.

  • value – 32-bit integer value to set.

Returns:

GXF_SUCCESS if the operation was successful, or otherwise one of the GXF error codes.

Get#

gxf_result_t GxfParameterGetInt32(
gxf_context_t context,
gxf_uid_t uid,
const char *key,
int32_t *value,
);#
Parameters:

  • context – A valid GXF context.

  • uid – A valid component identifier.

  • key – A valid name of a component to set.

  • value – pointer to get the 32-bit integer value.

Returns:

GXF_SUCCESS if the operation was successful, or otherwise one of the GXF error codes.

32-bit unsigned integer#

Set#

gxf_result_t GxfParameterSetUInt32(
gxf_context_t context,
gxf_uid_t uid,
const char *key,
uint32_t value,
);#
Parameters:

  • context – A valid GXF context.

  • uid – A valid component identifier.

  • key – A valid name of a component to set.

  • value – 32-bit unsigned integer value to set.

Returns:

GXF_SUCCESS if the operation was successful, or otherwise one of the GXF error codes.

Get#

gxf_result_t GxfParameterGetUInt32(
gxf_context_t context,
gxf_uid_t uid,
const char *key,
uint32_t *value,
);#
Parameters:

  • context – A valid GXF context.

  • uid – A valid component identifier.

  • key – A valid name of a component to set.

  • value – pointer to get the 32-bit unsigned integer value.

Returns:

GXF_SUCCESS if the operation was successful, or otherwise one of the GXF error codes.

16-bit unsigned integer#

Set#

gxf_result_t GxfParameterSetUInt16(
gxf_context_t context,
gxf_uid_t uid,
const char *key,
uint16_t value,
);#
Parameters:

  • context – A valid GXF context.

  • uid – A valid component identifier.

  • key – A valid name of a component to set.

  • value – 16-bit unsigned integer value to set.

Returns:

GXF_SUCCESS if the operation was successful, or otherwise one of the GXF error codes.

Get#

gxf_result_t GxfParameterGetUInt16(
gxf_context_t context,
gxf_uid_t uid,
const char *key,
uint16_t *value,
);#
Parameters:

  • context – A valid GXF context.

  • uid – A valid component identifier.

  • key – A valid name of a component to set.

  • value – pointer to get the 16-bit unsigned integer value.

Returns:

GXF_SUCCESS if the operation was successful, or otherwise one of the GXF error codes.

16-bit signed integer#

Set#

gxf_result_t GxfParameterSetInt16(
gxf_context_t context,
gxf_uid_t uid,
const char *key,
int16_t value,
);#
Parameters:

  • context – A valid GXF context.

  • uid – A valid component identifier.

  • key – A valid name of a component to set.

  • value – 16-bit signed integer value to set.

Returns:

GXF_SUCCESS if the operation was successful, or otherwise one of the GXF error codes.

8-bit unsigned integer#

Set#

gxf_result_t GxfParameterSetUInt8(
gxf_context_t context,
gxf_uid_t uid,
const char *key,
uint8_t value,
);#
Parameters:

  • context – A valid GXF context.

  • uid – A valid component identifier.

  • key – A valid name of a component to set.

  • value – 8-bit unsigned integer value to set.

Returns:

GXF_SUCCESS if the operation was successful, or otherwise one of the GXF error codes.

8-bit signed integer#

Set#

gxf_result_t GxfParameterSetInt8(
gxf_context_t context,
gxf_uid_t uid,
const char *key,
int8_t value,
);#
Parameters:

  • context – A valid GXF context.

  • uid – A valid component identifier.

  • key – A valid name of a component to set.

  • value – 8-bit signed integer value to set.

Returns:

GXF_SUCCESS if the operation was successful, or otherwise one of the GXF error codes.

String parameter#

Set#

gxf_result_t GxfParameterSetStr(
gxf_context_t context,
gxf_uid_t uid,
const char *key,
const char *value,
);#
Parameters:

  • context – A valid GXF context.

  • uid – A valid component identifier.

  • key – A valid name of a component to set.

  • value – A char array containing value to set.

Returns:

GXF_SUCCESS if the operation was successful, or otherwise one of the GXF error codes.

Get#

gxf_result_t GxfParameterGetStr(
gxf_context_t context,
gxf_uid_t uid,
const char *key,
const char **value,
);#
Parameters:

  • context – A valid GXF context.

  • uid – A valid component identifier.

  • key – A valid name of a component to set.

  • value – pointer to a char* array to get the value.

Returns:

GXF_SUCCESS if the operation was successful, or otherwise one of the GXF error codes.

Boolean#

Set#

gxf_result_t GxfParameterSetBool(
gxf_context_t context,
gxf_uid_t uid,
const char *key,
bool value,
);#
Parameters:

  • context – A valid GXF context.

  • uid – A valid component identifier.

  • key – A valid name of a component to set.

  • value – A boolean value to set.

Returns:

GXF_SUCCESS if the operation was successful, or otherwise one of the GXF error codes.

Get#

gxf_result_t GxfParameterGetBool(
gxf_context_t context,
gxf_uid_t uid,
const char *key,
bool *value,
);#
Parameters:

  • context – A valid GXF context.

  • uid – A valid component identifier.

  • key – A valid name of a component to set.

  • value – pointer to get the boolean value.

Returns:

GXF_SUCCESS if the operation was successful, or otherwise one of the GXF error codes.

Handle#

Set#

gxf_result_t GxfParameterSetHandle(
gxf_context_t context,
gxf_uid_t uid,
const char *key,
gxf_uid_t cid,
);#
Parameters:

  • context – A valid GXF context.

  • uid – A valid component identifier.

  • key – A valid name of a component to set.

  • cid – Unique identifier to set.

Returns:

GXF_SUCCESS if the operation was successful, or otherwise one of the GXF error codes.

Get#

gxf_result_t GxfParameterGetHandle(
gxf_context_t context,
gxf_uid_t uid,
const char *key,
gxf_uid_t *cid,
);#
Parameters:

  • context – A valid GXF context.

  • uid – A valid component identifier.

  • key – A valid name of a component to set.

  • value – Pointer to a unique identifier to get the value.

Returns:

GXF_SUCCESS if the operation was successful, or otherwise one of the GXF error codes.

Vector Parameters#

To set/get the vector parameters of a component, users can use the following C-APIs for various data types:

Set 1-D Vetor Parameters#

gxf_result_t GxfParameterSet1DDataTypeVector(
gxf_context_t context,
gxf_uid_t uid,
const char *key,
data_type *value,
uint64_t length,
);#

value should point to an array of the data to be set of the corresponding type. The size of the stored array should match the length argument passed.

See the table below for all the supported data types and their corresponding function signatures.

Parameters:

  • key – The name of the parameter

  • value – The value to set of the parameter

  • length – The length of the vector parameter

Returns:

GXF_SUCCESS if the operation was successful, or otherwise one of the GXF error codes.

Supported Data Types to Set 1D Vector Parameters#

Function Name

data_type

GxfParameterSet1DFloat64Vector(...)

double

GxfParameterSet1DInt64Vector(...)

int64_t

GxfParameterSet1DUInt64Vector(...)

uint64_t

GxfParameterSet1DInt32Vector(...)

int32_t

Set 2-D Vetor Parameters#

gxf_result_t GxfParameterSet2DDataTypeVector(
gxf_context_t context,
gxf_uid_t uid,
const char *key,
data_type **value,
uint64_t height,
uint64_t width,
);#

value should point to an array of array (and not to the address of a contiguous array of data) of the data to be set of the corresponding type. The length of the first dimension of the array should match the height argument passed and similarly the length of the second dimension of the array should match the width passed.

See the table below for all the supported data types and their corresponding function signatures.

Parameters:

  • key – The name of the parameter

  • value – The value to set of the parameter

  • height – The height of the 2-D vector parameter

  • width – The width of the 2-D vector parameter

Returns:

GXF_SUCCESS if the operation was successful, or otherwise one of the GXF error codes.

Supported Data Types to Set 2D Vector Parameters#

Function Name

data_type

GxfParameterSet2DFloat64Vector(...)

double

GxfParameterSet2DInt64Vector(...)

int64_t

GxfParameterSet2DUInt64Vector(...)

uint64_t

GxfParameterSet2DInt32Vector(...)

int32_t

Get 1-D Vetor Parameters#

Use gxf_result_t GxfParameterGet1D"DataType"Vector(gxf_context_t context, gxf_uid_t uid, const char* key, data_type** value, uint64_t* length) to get the value of a 1-D vector.

Before calling this method, use GxfParameterGet1D"DataType"VectorInfo(gxf_context_t context, gxf_uid_t uid, const char* key, uint64_t* length) to obtain the length of the vector param and then allocate at least that much memory to retrieve the value.

value should point to an array of size greater than or equal to length allocated by user of the corresponding type to retrieve the data. If the length doesn’t match the size of stored vector then it will be updated with the expected size.

See the table below for all the supported data types and their corresponding function signatures.

param key:

The name of the parameter

param value:

The value to set of the parameter

param length:

The length of the 1-D vector parameter obtained by calling GxfParameterGet1D"DataType"VectorInfo(...)

Supported Data Types to Get the Value of 1D Vector Parameters#

Function Name

data_type

GxfParameterGet1DFloat64Vector(...)

double

GxfParameterGet1DInt64Vector(...)

int64_t

GxfParameterGet1DUInt64Vector(...)

uint64_t

GxfParameterGet1DInt32Vector(...)

int32_t

Get 2-D Vetor Parameters#

Use gxf_result_t GxfParameterGet2D"DataType"Vector(gxf_context_t context, gxf_uid_t uid, const char* key, data_type** value, uint64_t* height, uint64_t* width) to get the value of a -2D vector.

Before calling this method, users should call GxfParameterGet1D"DataType"VectorInfo(gxf_context_t context, gxf_uid_t uid, const char* key, uint64_t* height, uint64_t* width) to obtain the height and width of the 2D-vector param and then allocate at least that much memory to retrieve the value.

value should point to an array of array of height (size of first dimension) greater than or equal to height and width (size of the second dimension) greater than or equal to width allocated by user of the corresponding type to get the data. If the height or width don’t match the height and width of the stored vector then they will be updated with the expected values.

See the table below for all the supported data types and their corresponding function signatures.

parameter”: key The name of the parameter

parameter”: value Allocated array to get the value of the parameter

parameter”: height The height of the 2-D vector parameter obtained by calling GxfParameterGet2D"DataType"VectorInfo(...)

parameter”: width The width of the 2-D vector parameter obtained by calling GxfParameterGet2D"DataType"VectorInfo(...)

Supported Data Types to Get the Value of 2D Vector Parameters#

Function Name

data_type

GxfParameterGet2DFloat64Vector(...)

double

GxfParameterGet2DInt64Vector(...)

int64_t

GxfParameterGet2DUInt64Vector(...)

uint64_t

GxfParameterGet2DInt32Vector(...)

int32_t

YAML Parameters#

Sets a parameter from YAML#

gxf_result_t GxfParameterSetFromYamlNode(
gxf_context_t context,
gxf_uid_t uid,
const char *key,
void *yaml_node,
const char *prefix,
);#

Sets a parameter from YAML. The YAML node pointer should be a type of ‘YAML::Node*’.

Parameters:

  • context – A valid GXF context.

  • uid – A valid component identifier.

  • key – A valid name of a component to set.

  • yaml_node – a yaml node pointer

  • prefix – prefix

Returns:

GXF_SUCCESS if the operation was successful, or otherwise one of the GXF error codes.

File Parameters#

Sets a FilePath parameter#

gxf_result_t GxfParameterSetPath(
gxf_context_t context,
gxf_uid_t uid,
const char *key,
const char *value,
);#

Sets a FilePath parameter.

Parameters:

  • context – A valid GXF context.

  • uid – A valid component identifier.

  • key – A valid name of a component to set.

  • value – a file path

Returns:

GXF_SUCCESS if the operation was successful, or otherwise one of the GXF error codes.

EntityGroup#

kDefaultEntityGroupName#

kDefaultEntityGroupName#

Name of default entity group.

Defined as “default_entity_group”.

Create an entity group#

gxf_result_t GxfCreateEntityGroup(
gxf_context_t context,
const char *name,
gxf_uid_t *gid,
);#

Create a new GXF EntityGroup.

EntityGroup is a group of EntityItems, such that these entities are bonded to some common properties. For now the common property is all kinds of resources.

Parameters:

  • context – A valid GXF context

  • name – name to create the EntityGroup

  • gid – pointer to returned uid for the created EntityGroup, abbreviation for group id

Returns:

GXF_SUCCESS if the operation was successful, or otherwise one of the GXF error codes.

Update entity’s EntityGroup#

gxf_result_t GxfUpdateEntityGroup(
gxf_context_t context,
gxf_uid_t gid,
gxf_uid_t eid,
);#

Update entity’s EntityGroup by adding the entity eid into the target EntityGroup; and remove the entity eid from previous EntityGroup.

Each entity always has one and only one EntityGroup. The entity holds the entity group gid, and the EntityGroup holds a set of entity eids that has this entity eid. Each entity is created with default EntityGroup. When update an entity’s EntityGroup: 1. updates EntityGroup uid in current EntityItem, to new group id gid; 2. Remove eid from its previous EntityGroup; 3. add eid to its new EntityGroup

Parameters:

  • context – A valid GXF context

  • gid – UID of an existing (new) EntityGroup

  • eid – eid of an Entity

Returns:

GXF_SUCCESS if the operation was successful, or otherwise one of the GXF error codes.

Find all resources from an EntityGroup#

gxf_result_t GxfEntityGroupFindResources(
gxf_context_t context,
gxf_uid_t eid,
uint64_t *num_resource_cids,
gxf_uid_t *resource_cids,
);#

Find all resources from an EntityGroup

Finds and returns all resource component cids for EntityGroup pointed by eid. If more than max_entities exist only max_entities will be returned.

Parameters:

  • context – A valid GXF context

  • eid – eid of an Entity

  • num_resource_cids – In/Out: the max number of components that can fit in the buffer/the number of resources in eid’s EntityGroup

  • resource_cids – A buffer allocated by the caller for returned UIDs of all resources, with capacity for num_resource_cids.

Returns:

GXF_SUCCESS if the operation was successful, GXF_QUERY_NOT_ENOUGH_CAPACITY if more resources exist in eid’s EntityGroup, or otherwise one of the GXF error codes.

Find the EntityGroup gid that the entity belongs to#

gxf_result_t GxfEntityGroupId(
gxf_context_t context,
gxf_uid_t eid,
gxf_uid_t *gid,
);#

EntityGroup is a group of EntityItems, such that these entities are bonded to some common properties. For now the common property is all kinds of resources. Through life time of each entity, it always corresponds to an EntityGroup. Eg, newly created EntityItem points to Default EntityGroup, and user can update its EntityGroup to valid one only.

Parameters:

  • context – A valid GXF context

  • eid – eid of an EntityItem, whose EntityGroup id field is used find EntityGroup name

  • gid – The returned id of the entity group.

Returns:

GXF_SUCCESS if the operation was successful, or otherwise one of the GXF error codes.

Get name of an EntityGroup#

gxf_result_t GxfEntityGroupName(
gxf_context_t context,
gxf_uid_t eid,
const char **name,
);#

Get name of EntityGroup held by entity

EntityGroup is a group of EntityItems, such that these entities are bonded to some common properties. For now the common property is all kinds of resources. Through life time of each entity, it always corresponds to an EntityGroup. Eg, newly created Entity item points to Default EntityGroup, and user can update its EntityGroup to valid one only.

Parameters:

  • context – A valid GXF context

  • eid – eid of an Entity item, whose EntityGroup id field is used find EntityGroup name

  • name – The returned name of the EntityGroup

Returns:

GXF_SUCCESS if the operation was successful, or otherwise one of the GXF error codes.

Get resource component id from EntityGroup#

gxf_result_t GxfEntityResourceGetHandle(
gxf_context_t context,
gxf_uid_t eid,
const char *type,
const char *resource_key,
gxf_uid_t *resource_cid,
);#

Gets cid of a resource component that is grouped with the given entity

Parameters:

  • context – A valid GXF context

  • eid – eid of an Entity

  • type – The fully qualified C++ type name of the component

  • resource_key – the key or name of the resource

  • resource_cid – The returned cid of the resource component

Returns:

GXF_SUCCESS if the operation was successful, or otherwise one of the GXF error codes.

Information Queries#

Get Meta Data about the GXF Runtime#

type gxf_runtime_info#

A structure representing version of GXF Runtime and list of loaded extensions.

const char *version#

GXF Runtime version.

uint64_t num_extensions#

In-out capacity of extensions/Number of extension types.

gxf_tid_t *extensions#

List of extension IDs.

gxf_result_t GxfRuntimeInfo(
gxf_context_t context,
gxf_runtime_info *info,
);#
Parameters:

  • context – A valid GXF context.

  • info – pointer to gxf_runtime_info object to get the meta data.

Returns:

GXF_SUCCESS if the operation was successful, or otherwise one of the GXF error codes.

Get description and list of components in loaded Extension#

type gxf_extension_info_t#

A structure representing description and list of components for a loaded extension.

gxf_tid_t id#

Extension ID (UUID) registered via GXF_EXT_FACTORY_SET_INFO.

const char *name#

Extension name registered via GXF_EXT_FACTORY_SET_INFO.

const char *description#

Description registered via GXF_EXT_FACTORY_SET_INFO.

const char *version#

Extension version registered via GXF_EXT_FACTORY_SET_INFO.

const char *runtime_version#

GXF Core version the extension was compiled with.

const char *license#

Extension license registered via GXF_EXT_FACTORY_SET_INFO.

const char *author#

Extension author registered via GXF_EXT_FACTORY_SET_INFO.

const char *display_name#

Extension display name registered via GXF_EXT_FACTORY_SET_DISPLAY_INFO.

const char *category#

Extension category registered via GXF_EXT_FACTORY_SET_DISPLAY_INFO.

const char *brief#

Extension brief registered via GXF_EXT_FACTORY_SET_DISPLAY_INFO.

uint64_t num_components#

In-out capacity of components/Number of components.

gxf_tid_t *components#

List of IDs of provided components.

gxf_result_t GxfExtensionInfo(
gxf_context_t context,
gxf_tid_t tid,
gxf_extension_info_t *info,
);#
Parameters:

  • context – A valid GXF context.

  • tid – The unique identifier of the extension.

  • info – pointer to gxf_extension_info_t object to get the meta data.

Returns:

GXF_SUCCESS if the operation was successful, or otherwise one of the GXF error codes.

Get description and list of parameters of Component#

type gxf_component_info_t#

A structure representing description and list of parameters of a component.

gxf_tid_t cid#

Component ID registered via GXF_EXT_FACTORY_ADD.

const char *base_name#

Base class name registered via GXF_EXT_FACTORY_ADD.

int is_abstract#

Whether the component is abstract and cannot be instantiated.

const char *type_name#

Component name registered via GXF_EXT_FACTORY_ADD.

const char *display_name#

Component display name registered via GXF_EXT_FACTORY_SET_DISPLAY_INFO, maximum 30 characters.

const char *brief#

Component brief registered via GXF_EXT_FACTORY_SET_DISPLAY_INFO, maximum 50 characters.

const char *description#

Description registered via GXF_EXT_FACTORY_ADD.

uint64_t num_parameters#

In-out capacity of parameters/Number of parameters.

const char **parameters#

List of names for parameters.

gxf_result_t GxfComponentInfo(
gxf_context_t context,
gxf_tid_t tid,
gxf_component_info_t *info,
);#

Note: Parameters are only available after at least one instance is created for the Component.

Parameters:

  • context – A valid GXF context.

  • tid – The unique identifier of the component.

  • info – pointer to gxf_component_info_t object to get the meta data.

Returns:

GXF_SUCCESS if the operation was successful, or otherwise one of the GXF error codes.

Get parameter type description#

enum gxf_parameter_type_t#

An enumeration representing the type of a parameter.

enumerator GXF_PARAMETER_TYPE_CUSTOM#

A custom type not natively supported by GXF.

enumerator GXF_PARAMETER_TYPE_HANDLE#

A GXF handle. The handle type is specified separately.

enumerator GXF_PARAMETER_TYPE_STRING#

A null-terminated character string (const char*).

enumerator GXF_PARAMETER_TYPE_INT64#

A 64-bit signed integer (int64_t).

enumerator GXF_PARAMETER_TYPE_UINT64#

A 64-bit unsigned integer (uint64_t).

enumerator GXF_PARAMETER_TYPE_FLOAT64#

A 64-bit floating point (double).

enumerator GXF_PARAMETER_TYPE_BOOL#

A boolean type (bool).

enumerator GXF_PARAMETER_TYPE_INT32#

A 32-bit signed integer (int32_t).

enumerator GXF_PARAMETER_TYPE_FILE#

A file system path (string).

enumerator GXF_PARAMETER_TYPE_INT8#

A 8-bit signed integer (int8_t).

enumerator GXF_PARAMETER_TYPE_INT16#

A 16-bit signed integer (int16_t).

enumerator GXF_PARAMETER_TYPE_UINT8#

A 8-bit unsigned integer (uint8_t).

enumerator GXF_PARAMETER_TYPE_UINT16#

A 16-bit unsigned integer (uint16_t).

enumerator GXF_PARAMETER_TYPE_UINT32#

A 32-bit unsigned integer (uint32_t).

enumerator GXF_PARAMETER_TYPE_FLOAT32#

A 32-bit floating point (float).

enumerator GXF_PARAMETER_TYPE_COMPLEX64#

A 64-bit complex floating point (float).

enumerator GXF_PARAMETER_TYPE_COMPLEX128#

A 128-bit complex floating point (double).

Gets a string describing the parameter type

const char *GxfParameterTypeStr(gxf_parameter_type_t param_type);#
Parameters:

  • param_type – Type of parameter to get info about.

Returns:

C-style string description of the parameter type.

Get flag type description#

Gets a string describing the flag type

const char *GxfParameterFlagTypeStr(gxf_parameter_flags_t_ flag_type);#
Parameters:

  • flag_type – Type of flag to get info about.

Returns:

C-style string description of the flag type.

Get parameter description#

type gxf_parameter_info_t#

A structure holding metadata information about a parameter which was registered as part of the component interface.

const char *key#

The name of the parameter as it appears in the GXF file.

const char *headline#

A short headline used to display the parameter to a human.

const char *description#

A longer text describing the usage of the parameter.

gxf_parameter_flags_t flags#

Parameter flags for example to make a parameter optional.

gxf_parameter_type_t type#

The type of the parameter

gxf_tid_t handle_tid#

In case the parameter is a handle the TID of the component.

const void *default_value#

Default value of parameter, N/A for handle and custom params.

const void *numeric_min#

Min value of range for numeric parameters, N/A for other types.

const void *numeric_max#

Max value of range for numeric parameters, N/A for other types.

const void *numeric_step#

Step value of range for numeric parameters, N/A for other types.

const char *platform_information#

Platforms separated by comma. Empty means all platforms.

int32_t rank#

Rank of the parameter. 0-scalar, 1-list etc. Max rank is 8.

int32_t shape[8]#

Sizes of multi dimensional parameters if it is of fixed length. Shape of a dimension is -1 for scalar and variable length arrays.

Gets description of specific parameter. Fails if the component is not instantiated yet.

gxf_result_t GxfGetParameterInfo(
gxf_context_t context,
gxf_tid_t cid,
const char *key,
gxf_parameter_info_t *info,
);#
Parameters:

  • context – A valid GXF context.

  • cid – The unique identifier of the component.

  • key – The name of the parameter.

  • info – Pointer to a gxf_parameter_info_t object to get the value.

Returns:

GXF_SUCCESS if the operation was successful, or otherwise one of the GXF error codes.

Redirect logs to a file#

Redirect console logs to the provided file.

gxf_result_t GxfRedirectLog(gxf_context_t context, FILE *fp);#
Parameters:

  • context – A valid GXF context.

  • fp – File path for the redirected logs.

Returns:

GXF_SUCCESS if the operation was successful, or otherwise one of the GXF error codes.

Miscellaneous#

Get string description of error#

const char *GxfResultStr(gxf_result_t result);#

Gets a string describing an GXF error code.

The caller does not get ownership of the return C string and must not delete it.

Parameters:

  • result – A GXF error code

Returns:

A pointer to a C string with the error code description.

Check if a result is successful#

bool isSuccessful(gxf_result_t result);#

Checks if a result code is GXF_SUCCESS or not.

Parameters:

  • result – A GXF result code

Returns:

A boolean value indicating if the result code is GXF_SUCCESS.

Set log severity#

type gxf_severity_t#

An enumeration of severity levels for GXF_LOG_* logging macros.

type GXF_SEVERITY_NONE#
type GXF_SEVERITY_ERROR#
type GXF_SEVERITY_WARNING#
type GXF_SEVERITY_INFO#
type GXF_SEVERITY_DEBUG#
type GXF_SEVERITY_VERBOSE#
gxf_result_t GxfSetSeverity(
gxf_context_t context,
gxf_severity_t severity,
);#

Sets the severity level of the logs (corresponding to GXF_LOG_* logging macros) for the entire application.

Parameters:

  • context – a valid GXF context

  • severity – a valid severity level as defined in gxf_severity_t. Logs corresponding to any level <= severity will be logged.

Returns:

GXF_SUCCESS if the operation was successful, or otherwise one of the GXF error codes.

Get log severity#

gxf_result_t GxfGetSeverity(
gxf_context_t context,
gxf_severity_t severity,
);#

Returns the current severity level of the logs.

Parameters:

  • context – a valid GXF context

  • severity – a pointer to a gxf_severity_t in which the resulting severity is returned.

Returns:

GXF_SUCCESS if the operation was successful, or otherwise one of the GXF error codes.

On this page