genvid.h

Macros

GENVID_FAILED
Parameters:

  • status – The code to check.

A utility macro which indicates whether or not the status code is a terminal failure. (The situation can’t lead to a success state given enough time.)

GENVID_STATUS_FAILED

Enums

enum GenvidPixelFormat

The different pixel formats used for non auto-capture video frames.

enumerator GenvidPixelFormat_UNKNOWN

Unknown pixel format.

enumerator GenvidPixelFormat_R8G8B8

RGB 24 bits, 8 bits per channel.

enumerator GenvidPixelFormat_R8G8B8A8

RGBA 32 bits, 8 bits per channel.

enumerator GenvidPixelFormat_R10G10B10A2

RGBA 32 bits, 10 bits per color channel, with 2 bits for alpha.

enumerator GenvidPixelFormat_NV12

NV12 Planar format: Y plane, followed by a combined UV plane.

enumerator GenvidPixelFormat_B8G8R8A8

BGRA 32 bits, 8 bits per channel.

enumerator GENVID_NUM_PIXELFORMAT

Number of pixel formats supported.

enum GenvidAudioFormat

The different audio sample formats used.

enumerator GenvidAudioFormat_UNKNOWN

The audio format is unknown.

enumerator GenvidAudioFormat_S16LE

The audio format is 16 bits signed.

enumerator GenvidAudioFormat_F32LE

The audio format is 32 bits floating point.

enumerator GenvidAudioFormat_NUM_AUDIOFORMAT
enum GenvidStatus

The various error codes that the various Genvid routines can return.

enumerator GenvidStatus_Success

Success.

enumerator GenvidStatus_ConnectionInProgress

A connection is in progress.

enumerator GenvidStatus_Incomplete

The call cannot be completed.

enumerator GenvidStatus_UnknownError

An unexpected error has occured.

enumerator GenvidStatus_InvalidState

The SDK is in an invalid state for this call to complete.

enumerator GenvidStatus_InvalidParameter

A parameter is invalid.

enumerator GenvidStatus_AllocationFailed

Failed to allocate memory.

enumerator GenvidStatus_AlreadyExists

A resource with the same name already exists.

enumerator GenvidStatus_ConnectionFailed

The SDK failed to connect to the services.

enumerator GenvidStatus_ConnectionTimeout

A connection operation timed out.

enumerator GenvidStatus_Disconnected

The SDK was disconnected from the service.

enumerator GenvidStatus_UninitializedSDK

Genvid_Initialize() have not been called.

enumerator GenvidStatus_InvalidImageFormat

The image format is unknown.

enum GenvidReduceOp

The various Reduce operations supported.

GENVID_NUM_REDUCE_OP is not a valid type. It corresponds to the total number of different operations possible.

enumerator GenvidReduceOp_Min
enumerator GenvidReduceOp_Max
enumerator GenvidReduceOp_Count
enumerator GenvidReduceOp_Sum
enumerator GENVID_NUM_REDUCE_OP

The total number of operations. Not a real type.

enum [anonymous]
enumerator GENVID_MAX_KEY_FIELDS

The maximum number of strings allowed in a key.

enumerator GENVID_MAX_RESULTS

The maximum number of results allowed in a single GenvidEventSummary.

Typedefs

typedef int64_t GenvidTimecode

A timecode value used to specify a location in the stream.

typedef void (*GenvidEventSummaryCallback)(const GenvidEventSummary *summary, void *userData)

A callback invoked when event summaries are ready.

Param summary:

The GenvidEventSummary structure that list all results available for a specific key.

Param userData:

The userData that was set when subscribing. See Genvid_Subscribe() for more information.

Any memory held by summary is invalidated when the callback returns.

typedef void (*GenvidCommandCallback)(const GenvidCommandResult *result, void *userData)

A callback invoked when a command is ready.

Any memory held by result is invalidated when the callback returns.

typedef void (*GenvidRequestCallback)(const GenvidRequestResult *result, void *userData)

A callback invoked when a request is ready.

Any memory held by result is invalidated when the callback returns.

Structs

struct GenvidCommandResult

The structure for commands sent to the game.

const char *id

A string identifying the command operation.

const char *value

A string representing the command parameters.

struct GenvidEventKey

A structure representing the event key used in a GenvidEventSummary report.

const char *fields[GENVID_MAX_KEY_FIELDS]

A list of strings composing the key.

int numFields

The number of valid strings in fields.

struct GenvidEventResult

The structure summarizing a single result of a Reduce operation.

GenvidEventKey key

An array of strings forming the key.

int numValues

The number of valid entries in values.

GenvidEventValue values[GENVID_NUM_REDUCE_OP]

A series of values, each for a different reduce operation.

struct GenvidEventSummary

The structure summarizing all of the results of a Reduce operation.

const char *id

A string identifying the Reduce operation.

int isFinal

0 if the results are partial, otherwise they are final.

New in version 1.47.0.

int numResults

The number of valid entries in results.

GenvidEventResult results[GENVID_MAX_RESULTS]

A series of results.

struct GenvidEventValue

A structure representing the event value returned in a GenvidEventSummary report.

GenvidReduceOp reduce

The reduce operation used to generate the value.

double value

A 64-bit floating-point number generated by the reduce operation.

struct GenvidRequestResult

The structure for requests sent to the game.

New in version 1.42.0.

const void *data

A buffer containing the data.

uint32_t dataSize

The size of the data buffer.

const char *replyTo

An opaque null-terminated string identifying the reply address.

const char *topic

A string identifying the command operation.

Functions

const char *Genvid_GetVersion(uint32_t *major, uint32_t *minor, uint32_t *version, uint32_t *build)

Returns the parsed version number of the Genvid library. A NULL pointer ignores that value.

Parameters:

  • major – A pointer where to assign the major part of the library version.

  • minor – A pointer where to assign the minor part of the library version.

  • patch – A pointer where to assign the patch part of the library version.

  • build – A pointer where to assign the build part of the library version.

Returns:

a string representation of the version.

const char *Genvid_StatusToString(const GenvidStatus status)

Returns a string representation of the GenvidStatus code.

Parameters:

status – The status code to describe.

Returns:

A human-readable description of the status code.

GenvidStatus Genvid_Initialize()

Initializes the Genvid library.

This function must be called once prior to any other call, any subsequent calls will return an error.

It will start the initialization of the asynchronous handler.

When you are done with the library, call Genvid_Terminate().

Return values:

  • GenvidStatus_Success – The library has been successfully initialized.

  • GenvidStatus_InvalidState – The library has already been initialized.

  • GenvidStatus_Incomplete – The initialization did not fully succeed.

GenvidStatus Genvid_Terminate()

Deallocates any internal data used by the Genvid library.

Calling this function invalidates all previous settings.

You must call Genvid_Initialize() before using any function again.

Return values:

  • GenvidStatus_Success – The library has been successfully terminated.

  • GenvidStatus_Incomplete – The termination did not fully succeed.

GenvidTimecode Genvid_GetCurrentTimecode()
Returns:

the current timecode.

GenvidTimecode Genvid_GetPreviousTimecode()
Returns:

the timecode last returned by Genvid_GetCurrentTimecode().

GenvidStatus Genvid_CreateStream(const char *streamID)

Allocates a stream.

This routine attempts to create a stream. The call is synchronous.

Parameters:

streamID – The unique identifier of the stream.

Return values:

  • GenvidStatus_UninitializedSDK – The Genvid library was not initialized before calling it.

  • GenvidStatus_Success – The operation completed properly.

  • GenvidStatus_AlreadyExists – A stream with the same name has already been created.

GenvidStatus Genvid_DestroyStream(const char *streamID)

Invalidates and deallocates internal data used by the specified stream streamID.

The call is synchronous. This routine attempts to stop then destroy the stream streamID

Parameters:

streamID – The name of the stream.

Return values:

  • GenvidStatus_UninitializedSDK – The Genvid library was not initialized before calling it.

  • GenvidStatus_Success – The operation completed properly.

  • GenvidStatus_UnknownError – The stream could not be unregistered.

GenvidStatus Genvid_SetParameterInt(const char *streamID, const char *paramKey, int paramValue)

Assigns paramValue to paramKey for streamID.

Parameters:

  • streamID – The ID of the stream that will be affected.

  • paramKey – The parameter key to change.

  • paramValue – The value to set.

Returns:

The status of the call.

See also

Common parameters

GenvidStatus Genvid_SetParameterFloat(const char *streamID, const char *paramKey, float paramValue)

Assigns paramValue to paramKey for streamID.

Parameters:

  • streamID – The ID of the stream that will be affected.

  • paramKey – The parameter key to change.

  • paramValue – The value to set.

Returns:

The status of the call.

See also

Common parameters

GenvidStatus Genvid_SetParameterPointer(const char *streamID, const char *paramKey, void *paramValue)

Assigns paramValue to paramKey for streamID.

Parameters:

  • streamID – The ID of the stream that will be affected.

  • paramKey – The parameter key to change.

  • paramValue – The value to set.

Returns:

The status of the call.

See also

Common parameters

GenvidStatus Genvid_GetParameterInt(const char *streamID, const char *paramKey, int *paramValue)

Retrieves the value of the parameter for that stream.

Parameters:

  • streamID – The ID of the stream to query.

  • paramKey – The parameter key to query.

  • paramValue – The pointer where to receive the parameter value.

Return values:

  • GenvidStatus_UninitializedSDK – The Genvid library was not initialized before calling it.

  • GenvidStatus_InvalidState – The stream was not found.

  • GenvidStatus_InvalidParameter – One of the parameters is invalid.

See also

Common parameters

GenvidStatus Genvid_GetParameterFloat(const char *streamID, const char *paramKey, float *paramValue)

Retrieves the value of the parameter for that stream.

Parameters:

  • streamID – The ID of the stream to query.

  • paramKey – The parameter key to query.

  • paramValue – The pointer where to receive the parameter value.

Return values:

  • GenvidStatus_UninitializedSDK – The Genvid library was not initialized before calling it.

  • GenvidStatus_InvalidState – The stream was not found.

  • GenvidStatus_InvalidParameter – One of the parameters is invalid.

  • GenvidStatus_Success – The operation completed properly.

See also

Common parameters

GenvidStatus Genvid_GetParameterPointer(const char *streamID, const char *paramKey, void **paramValue)

Retrieves the value of the parameter for that stream.

Parameters:

  • streamID – The ID of the stream to query.

  • paramKey – The parameter key to query.

  • paramValue – The pointer where to receive the parameter value.

Return values:

  • GenvidStatus_UninitializedSDK – The Genvid library was not initialized before calling it.

  • GenvidStatus_InvalidState – The stream was not found.

  • GenvidStatus_InvalidParameter – One of the parameters is invalid.

  • GenvidStatus_Success – The operation completed properly.

See also

Common parameters

GenvidStatus Genvid_GetParameterUTF8(const char *id, const char *paramKey, char *dstBuffer, size_t dstBufferSize)

Retrieves the value of the parameter for that stream.

Parameters:

  • streamID – The ID of the stream to query.

  • paramKey – The parameter key to query.

  • paramValue – The pointer where to receive the parameter value.

Return values:

  • GenvidStatus_UninitializedSDK – The Genvid library was not initialized before calling it.

  • GenvidStatus_InvalidState – The stream was not found.

  • GenvidStatus_InvalidParameter – One of the parameters is invalid.

  • GenvidStatus_Incomplete – The buffer size is too small. This would result in a non-null terminated string!

  • GenvidStatus_Success – The operation completed properly.

See also

Common parameters

GenvidStatus Genvid_SubmitAudioData(const GenvidTimecode timecode, const char *streamID, const void *audioData, const int audioDataSize)

Sends a buffer of audio samples.

Parameters:

  • timecode – The timecode associated with the start of the buffer. Use -1 to use the current timecode (as retrieve with Genvid_GetCurrentTimecode()).

  • streamID – The ID associated with the stream.

  • audioData – A pointer to an audio data buffer.

  • audioDataSize – The size of the audio data buffer.

The audio-sample format samples must be specified before calling this routine. See Genvid_SetParameterInt() for more information.

Return values:

  • GenvidStatus_UninitializedSDK – The Genvid library was not initialized before calling it.

  • GenvidStatus_InvalidState – The asynchronous handler was not initialized.

  • GenvidStatus_InvalidParameter – The stream was not found.

  • GenvidStatus_Success – The operation completed properly.

GenvidStatus Genvid_SubmitGameData(const GenvidTimecode timecode, const char *streamID, const void *gameData, const int gameDataSize)

Sends an opaque data buffer to the game stream.

A null pointer with a size of zero will send an empty buffer.

Parameters:

  • timecode – The timecode associated with the buffer. Use -1 to use the current timecode (as retrieve with Genvid_GetCurrentTimecode()).

  • streamID – The ID associated with the stream.

  • gameData – A pointer to the data buffer. If the pointer is null, the gameDataSize parameter must be 0.

  • gameDataSize – The size of the data buffer.

Return values:

  • GenvidStatus_UninitializedSDK – The Genvid library was not initialized before calling it.

  • GenvidStatus_InvalidState – The asynchronous handler was not initialized.

  • GenvidStatus_InvalidParameter – The stream was not found.

  • GenvidStatus_Success – The operation completed properly.

GenvidStatus Genvid_SubmitAnnotation(const GenvidTimecode timecode, const char *streamID, const void *annotationData, const int annotationDataSize)

Sends an opaque data buffer as an Annotation to the game stream.

A null pointer with a size of zero will send an empty buffer.

Parameters:

  • timecode – The timecode associated with the buffer. Use -1 to use the current timecode (as retrieve with Genvid_GetCurrentTimecode()).

  • streamID – The ID associated with the stream.

  • annotationData – A pointer to the data buffer. If the pointer is null, the annotationDataSize parameter must be 0.

  • annotationDataSize – The size of the data buffer.

Important

Annotations are dropped if the library isn’t connected.

Return values:

  • GenvidStatus_UninitializedSDK – The Genvid library was not initialized before calling it.

  • GenvidStatus_InvalidState – The asynchronous handler was not initialized.

  • GenvidStatus_InvalidParameter – The stream was not found.

  • GenvidStatus_Success – The operation completed properly.

GenvidStatus Genvid_SubmitNotification(const char *notificationID, const void *notificationData, const int notificationDataSize)

Sends an opaque data buffer as an Notification.

Parameters:

  • notificationID – The ID of the notification.

  • notificationData – A pointer to the data buffer. If the pointer is null, the notificationDataSize parameter must be 0.

  • annotationDataSize – The size of the data buffer.

Return values:

  • GenvidStatus_UninitializedSDK – The Genvid library was not initialized before calling it.

  • GenvidStatus_InvalidState – The asynchronous handler was not initialized.

  • GenvidStatus_Disconnected – The messaging system is currently disconnected.

  • GenvidStatus_UnknownError – The library failed to publish. A log is emitted with the possible cause of the error.

  • GenvidStatus_Success – The operation completed properly.

A null pointer with a size of zero will send an empty buffer with the notification ID.

Important

Notifications are not guaranteed to reach the clients if a disconnection occured.

GenvidStatus Genvid_SubmitVideoData(const GenvidTimecode timecode, const char *streamID, const void *videoData, const int videoDataSize)

Sends a video frame to the stream.

The video-data format must be specified before calling this routine. See Genvid_SetParameterInt() for more information.

When automatic video source capture is used, the video data must be set to NULL. See Genvid_SetParameterPointer() for more information.

Parameters:

  • timecode – The timecode associated with the buffer. Use -1 to use the current timecode (as retrieve with Genvid_GetCurrentTimecode()).

  • streamID – The ID associated with the stream.

  • videoData – A pointer to the data buffer. If the pointer is null, the videoDataSize parameter must be 0.

  • videoDataSize – The size of the data buffer.

Return values:

  • GenvidStatus_UninitializedSDK – The Genvid library was not initialized before calling it.

  • GenvidStatus_InvalidState – The asynchronous handler was not initialized.

  • GenvidStatus_InvalidParameter – The stream was not found.

  • GenvidStatus_InvalidImageFormat – The image format is not supported.

  • GenvidStatus_Success – The operation completed properly.

GenvidStatus Genvid_Subscribe(const char *id, GenvidEventSummaryCallback callback, void *userData)

Subscribes to the specified reduction event.

Parameters:

  • id – The unique identifier of the reduction.

  • callback – A pointer to the function that will be called when the reduction summary will be received.

  • userData – An opaque pointer that will be passed to the callback.

Return values:

  • GenvidStatus_UninitializedSDK – The Genvid library was not initialized before calling it.

  • GenvidStatus_InvalidParameter – id is null.

  • GenvidStatus_InvalidState – The asynchronous handler was not initialized.

  • GenvidStatus_InvalidParameter – One of the parameters is invalid.

  • GenvidStatus_Success – The operation completed properly.

Important

You cannot call this command from a GenvidEventSummaryCallback.

See also

Genvid_Unsubscribe()

GenvidStatus Genvid_Unsubscribe(const char *id, GenvidEventSummaryCallback callback, void *userData)

Unsubscribes from the reduction event specified by id, callback, and userData.

It’s possible to unsubscribe from multiple subscriptions by passing NULL to one or more of the parameters.

Parameters:

  • id – The reduction identifier to unsubscribe. NULL or empty means all identifiers.

  • callback – The callback to unsubscribe. NULL means all callbacks.

  • userData – The userData to unsubscribe. NULL means all userData.

Return values:

  • GenvidStatus_UninitializedSDK – The Genvid library was not initialized before calling it.

  • GenvidStatus_InvalidState – The asynchronous handler was not initialized.

  • GenvidStatus_InvalidParameter – One of the parameters is invalid.

  • GenvidStatus_Success – The operation completed properly.

Important

You cannot call this command from a GenvidEventSummaryCallback.

See also

Genvid_Subscribe()

GenvidStatus Genvid_CheckForEvents()

Synchronously checks for event results.

This routine calls any appropriate callback previously set using Genvid_Subscribe() or Genvid_SubscribeCommand().

Important

Calling this method recursively from one of the callback will return an error.

Return values:

  • GenvidStatus_Success – The operation has completed properly and events are available.

  • GenvidStatus_ConnectionTimeout – No events were available at this time.

  • GenvidStatus_InvalidState – The function was called recursively from the same thread.

GenvidStatus Genvid_SubscribeCommand(const char *id, GenvidCommandCallback callback, void *userData)

Subscribes to a command.

Parameters:

  • id – The unique identifier of the command to subscribe.

  • callback – The function to call when the command is received.

  • userData – An opaque pointer passed to the callback.

Return values:

  • GenvidStatus_UninitializedSDK – The Genvid library was not initialized before calling it.

  • GenvidStatus_InvalidParameter – The command identifier is null or empty.

  • GenvidStatus_InvalidState – The asynchronous handler was not initialized.

  • GenvidStatus_InvalidParameter – One of the parameters is invalid.

  • GenvidStatus_Success – The operation completed properly.

Important

You cannot call this command from a GenvidCommandCallback.

See also

Genvid_UnsubscribeCommand()

GenvidStatus Genvid_UnsubscribeCommand(const char *id, GenvidCommandCallback callback, void *userData)

Unsubscribes from the command specified by id, callback, and userData.

It’s possible to unsubscribe from multiple subscriptions by passing NULL to one or more of the parameters.

Important

You cannot call this command from a GenvidCommandCallback.

Parameters:

  • id – The command identifier to unsubscribe. NULL or empty means all identifiers.

  • callback – The callback to unsubscribe. NULL means all callbacks.

  • userData – The userData to unsubscribe. NULL means all userData.

Return values:

  • GenvidStatus_UninitializedSDK – The Genvid library was not initialized before calling it.

  • GenvidStatus_InvalidState – The asynchronous handler was not initialized, or reentry is detected.

  • GenvidStatus_InvalidParameter – One of the parameters is invalid.

  • GenvidStatus_Success – The operation completed properly.

See also

Genvid_SubscribeCommand()

GenvidStatus Genvid_SubscribeRequest(const char *topic, GenvidRequestCallback callback, void *userData)

Subscribes to a request.

Parameters:

  • topic – The topic of the request to subscribe.

  • callback – The function to call when the request is received.

  • userData – An opaque pointer passed to the callback.

Return values:

  • GenvidStatus_UninitializedSDK – The Genvid library was not initialized before calling it.

  • GenvidStatus_InvalidParameter – The topic identifier is null or empty.

  • GenvidStatus_InvalidState – The asynchronous handler was not initialized.

  • GenvidStatus_InvalidParameter – One of the parameters is invalid.

  • GenvidStatus_Success – The operation completed properly.

See also

Genvid_UnsubscribeRequest()

New in version 1.42.0.

GenvidStatus Genvid_UnsubscribeRequest(const char *topic, GenvidRequestCallback callback, void *userData)

Unsubscribes from the request specified by topic, callback, and userData.

It’s possible to unsubscribe from multiple subscriptions by passing NULL to one or more of the parameters.

Parameters:

  • topic – The topic to unsubscribe. NULL or empty means all identifiers.

  • callback – The callback to unsubscribe. NULL means all callbacks.

  • userData – The userData to unsubscribe. NULL means all userData.

Return values:

  • GenvidStatus_UninitializedSDK – The Genvid library was not initialized before calling it.

  • GenvidStatus_InvalidState – The asynchronous handler was not initialized.

  • GenvidStatus_InvalidParameter – One of the parameters is invalid.

  • GenvidStatus_Success – The operation completed properly.

See also

Genvid_SubscribeRequest()

New in version 1.42.0.

GenvidStatus Genvid_SubmitRequestReply(const char *topic, const char *replyTo, const void *buffer, const uint32_t bufferSize)

Sends an opaque data buffer as a Reply.

Parameters:

  • topic – The topic of the original request.

  • replyTo – The opaque address of the reply, obtained from GenvidRequestResult.

  • buffer – A pointer to the data buffer. If the pointer is null, the bufferSize parameter must be 0.

  • bufferSize – The size of the data buffer.

Return values:

  • GenvidStatus_UninitializedSDK – The Genvid library was not initialized before calling it.

  • GenvidStatus_InvalidState – The call was made outside of a GenvidRequestCallback associated with the topic.

  • GenvidStatus_Disconnected – The messaging system is currently disconnected.

  • GenvidStatus_UnknownError – The library failed to publish. A log is emitted with the possible cause of the error.

  • GenvidStatus_Success – The operation completed properly.

New in version 1.42.0.