Serialization Interface

Detailed Description

Defines the serialization API of the global egomotion module.

The typical use case of the serialization API is transmission of the state history across process and/or machine boundaries. The state is transmitted as a variable-size array of state elements and combined into a full state on deserialization.

Example:

// PRODUCER
{
    // buffer that will be transmitted
    dwGlobalEgomotionStateElement buffer[CAPACITY];
    size_t bufferSize = 0;
 
    // serialize and transmit state
    if(dwGlobalEgomotion_serialize(buffer, &bufferSize, CAPACITY, handle) == DW_SUCCESS)
    {
        // `buffer` now contains `bufferSize` (latest) estimates
        // transmit to consumer
        ...
    }
}
 
// CONSUMER
{
    // initialize deserializer module
    dwGlobalEgomotionHandle_t deserializer;
    dwGlobalEgomotion_initializeDeserializer(*deserializer, ...);
 
    // dwGlobalEgomotionStateElement buffer[CAPACITY];
    size_t bufferSize = 0;
 
    // receive `buffer` and `bufferSize` from producer
    ...
 
    // deserialize state
    dwGlobalEgomotion_deserialize(buffer, bufferSize, deserializer);
 
    // The `deserializer` handle can now be used with all getter APIs of
    // dwGlobalEgomotion (identifiable by the const handle input):
 
    dwGlobalEgomotion_getTimestamp(...);
    dwGlobalEgomotion_computeEstimate(...);
    dwGlobalEgomotion_getEstimate(...);
    ...
}

Typedefs
typedef struct dwGlobalEgomotionSerializer *	dwGlobalEgomotionSerializerHandle_t
typedef struct dwGlobalEgomotionSerializer const *	dwGlobalEgomotionSerializerConstHandle_t
typedef struct dwGlobalEgomotionDeserializer *	dwGlobalEgomotionDeserializerHandle_t
typedef struct dwGlobalEgomotionDeserializer const *	dwGlobalEgomotionDeserializerConstHandle_t

Functions
DW_API_PUBLIC dwStatus	dwGlobalEgomotion_initializeDeserializer (dwGlobalEgomotionHandle_t *handle, size_t historySize, dwContextHandle_t ctx)
	Initializes a global egomotion deserializer object. More...
DW_API_PUBLIC dwStatus	dwGlobalEgomotion_serialize (dwGlobalEgomotionStateElement *buffer, size_t *bufferSize, size_t const bufferCapacity, dwGlobalEgomotionHandle_t handle)
	Serialize the global egomotion state history out into the provided buffer. More...
DW_API_PUBLIC dwStatus	dwGlobalEgomotion_deserialize (dwGlobalEgomotionStateElement *buffer, size_t bufferSize, dwGlobalEgomotionHandle_t globalEgomotion)
	Deserialize the global egomotion state history from the provided buffer. More...

Typedef Documentation

dwGlobalEgomotionDeserializerConstHandle_t

typedef struct dwGlobalEgomotionDeserializer const* dwGlobalEgomotionDeserializerConstHandle_t

Definition at line 89 of file GlobalEgomotionSerialization.h.

dwGlobalEgomotionDeserializerHandle_t

typedef struct dwGlobalEgomotionDeserializer* dwGlobalEgomotionDeserializerHandle_t

Definition at line 88 of file GlobalEgomotionSerialization.h.

dwGlobalEgomotionSerializerConstHandle_t

typedef struct dwGlobalEgomotionSerializer const* dwGlobalEgomotionSerializerConstHandle_t

Definition at line 86 of file GlobalEgomotionSerialization.h.

dwGlobalEgomotionSerializerHandle_t

typedef struct dwGlobalEgomotionSerializer* dwGlobalEgomotionSerializerHandle_t

Definition at line 85 of file GlobalEgomotionSerialization.h.

Function Documentation

dwGlobalEgomotion_deserialize()

DW_API_PUBLIC dwStatus dwGlobalEgomotion_deserialize	(	dwGlobalEgomotionStateElement *	buffer,
		size_t	bufferSize,
		dwGlobalEgomotionHandle_t	globalEgomotion
	)

Deserialize the global egomotion state history from the provided buffer.

This call replaces any existing state history.

Parameters

[in]	buffer	Buffer containing serialized state history.
[in]	bufferSize	Number of elements in buffer.
[in]	globalEgomotion	Handle of a global egomotion object storing the deserialized history.

Returns

DW_INVALID_ARGUMENT - if the provided buffer is nullptr or the data is invalid.
DW_INVALID_HANDLE - if provided deserializer handle is invalid
DW_SUCCESS - buffer has been deserialized into corresponding global egomotion object.

API Group

• Init: Yes
• Runtime: Yes
• De-Init: Yes

dwGlobalEgomotion_initializeDeserializer()

DW_API_PUBLIC dwStatus dwGlobalEgomotion_initializeDeserializer	(	dwGlobalEgomotionHandle_t *	handle,
		size_t	historySize,
		dwContextHandle_t	ctx
	)

Initializes a global egomotion deserializer object.

This object does not support the dwGlobalEgomotion_addRelativeMotion and dwGlobalEgomotion_addGPSMeasurement APIs.

The deserializer is released with dwGlobalEgomotion_release.

Parameters

[out]	handle	A pointer to the handle for the created deserializer object.
[in]	historySize	Size of the internal history,

See also

dwGlobalEgomotionParameters.historySize. The size does not have to match that of the serialized module.

Parameters

[in]

ctx

Handle of the context under which the objects are created.

Returns

DW_INVALID_HANDLE - if the provided context handle is invalid
DW_SUCCESS - if initialization succeeded

API Group

• Init: Yes
• Runtime: No
• De-Init: No

dwGlobalEgomotion_serialize()

DW_API_PUBLIC dwStatus dwGlobalEgomotion_serialize	(	dwGlobalEgomotionStateElement *	buffer,
		size_t *	bufferSize,
		size_t const	bufferCapacity,
		dwGlobalEgomotionHandle_t	handle
	)

Serialize the global egomotion state history out into the provided buffer.

Fills out the provided buffer with the current global egomotion state history. The most recent state history is serialized, up to the buffer capacity. Filling order is oldest to most recent state history element.

Provide a buffer with capacity larger or equal to the historySize parameter of the global egomotion module to be serialized in order to ensure the full state history can be stored. If the buffer capacity is too low to fit the state history, the buffer is filled with the latest history elements that fit.

Parameters

[out]	buffer	Buffer containing serialized state history.
[out]	bufferSize	Number of elements written to buffer.
[in]	bufferCapacity	Capacity of buffer in number of elements.
[in]	handle	Handle of a global egomotion object from which to serialize data.

Returns

DW_INVALID_ARGUMENT - buffer or bufferSize is nullptr.
DW_INVALID_HANDLE - global egomotion handle is invalid.
DW_NOT_AVAILABLE - no state history to be serialized.
DW_SUCCESS - buffer has been filled with state history.

API Group

• Init: Yes
• Runtime: Yes
• De-Init: Yes