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.

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_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_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 Extensions from a file

gxf_result_t GxfLoadExtension(gxf_context_t context, const char *filename);

Loads extension in the given context from 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.

This function will be deprecated.

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.

gxf_result_t GxfLoadExtensionManifest(gxf_context_t context, const char *manifest_filename);

Loads extensions from manifest 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.

This function will be deprecated.

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 nvgraph_registry

The nvgraph_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 GxfEntityCreate(gxf_context_t context, gxf_uid_t *eid);

Creates a new entity and updates the eid to the unique identifier of the newly created entitiy.

This method will be deprecated.

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.

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 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.

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.

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 10240.

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.

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.

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.

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.

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.