libs/vr/libdvr/include/dvr/dvr_tracking.h

#ifndef ANDROID_DVR_TRACKING_H_
#define ANDROID_DVR_TRACKING_H_

#include <stdint.h>
#include <sys/cdefs.h>

#include <dvr/dvr_tracking_types.h>

__BEGIN_DECLS

typedef struct DvrReadBuffer DvrReadBuffer;
typedef struct DvrTrackingCamera DvrTrackingCamera;
typedef struct DvrTrackingFeatureExtractor DvrTrackingFeatureExtractor;
typedef struct DvrTrackingSensors DvrTrackingSensors;
typedef struct DvrWriteBufferQueue DvrWriteBufferQueue;

// The callback for DvrTrackingFeatureExtractor that will deliver the feature
// events. This callback is passed to dvrTrackingFeatureExtractorStart.
typedef void (*DvrTrackingFeatureCallback)(void* context,
                                           const DvrTrackingFeatures* event);

// The callback for DvrTrackingSensors session that will deliver the events.
// This callback is passed to dvrTrackingSensorsStart.
typedef void (*DvrTrackingSensorEventCallback)(void* context,
                                               DvrTrackingSensorEvent* event);

// Creates a DvrTrackingCamera session.
//
// On creation, the session is not in operating mode. Client code must call
// dvrTrackingCameraStart to bootstrap the underlying camera stack.
//
// There is no plan to expose camera configuration through this API. All camera
// parameters are determined by the system optimized for better tracking
// results. See b/78662281 for detailed deprecation plan of this API and the
// Stage 2 of VR tracking data source refactoring.
//
// @param out_camera The pointer of a DvrTrackingCamera will be filled here if
//     the method call succeeds.
// @return Zero on success, or negative error code.
int dvrTrackingCameraCreate(DvrTrackingCamera** out_camera);

// Destroys a DvrTrackingCamera handle.
//
// @param camera The DvrTrackingCamera of interest.
void dvrTrackingCameraDestroy(DvrTrackingCamera* camera);

// Starts the DvrTrackingCamera.
//
// On successful return, all DvrReadBufferQueue's associated with the given
// write_queue will start to receive buffers from the camera stack. Note that
// clients of this API should not assume the buffer dimension, format, and/or
// usage of the outcoming buffers, as they are governed by the underlying camera
// logic. Also note that it's the client's responsibility to consume buffers
// from DvrReadBufferQueue on time and return them back to the producer;
// otherwise the camera stack might be blocked.
//
// @param camera The DvrTrackingCamera of interest.
// @param write_queue A DvrWriteBufferQueue that the camera stack can use to
//     populate the buffer into. The queue must be empty and the camera stack
//     will request buffer allocation with proper buffer dimension, format, and
//     usage. Note that the write queue must be created with user_metadata_size
//     set to sizeof(DvrTrackingBufferMetadata). On success, the write_queue
//     handle will become invalid and the ownership of the queue handle will be
//     transferred into the camera; otherwise, the write_queue handle will keep
//     untouched and the caller still has the ownership.
// @return Zero on success, or negative error code.
int dvrTrackingCameraStart(DvrTrackingCamera* camera,
                           DvrWriteBufferQueue* write_queue);

// Stops the DvrTrackingCamera.
//
// On successful return, the DvrWriteBufferQueue set during
// dvrTrackingCameraStart will stop getting new buffers from the camera stack.
//
// @param camera The DvrTrackingCamera of interest.
// @return Zero on success, or negative error code.
int dvrTrackingCameraStop(DvrTrackingCamera* camera);

// Creates a DvrTrackingSensors session.
//
// This will initialize but not start device sensors (gyro / accel). Upon
// successfull creation, the clients can call dvrTrackingSensorsStart to start
// receiving sensor events.
//
// @param out_sensors The pointer of a DvrTrackingSensors will be filled here if
//     the method call succeeds.
// @param mode The sensor mode.
//        mode="ndk": Use the Android NDK.
//        mode="direct": Use direct mode sensors (lower latency).
// @return Zero on success, or negative error code.
int dvrTrackingSensorsCreate(DvrTrackingSensors** out_sensors,
                             const char* mode);

// Destroys a DvrTrackingSensors session.
//
// @param sensors The DvrTrackingSensors struct to destroy.
void dvrTrackingSensorsDestroy(DvrTrackingSensors* sensors);

// Starts the tracking sensor session.
//
// This will start the device sensors and start pumping the feature and sensor
// events as they arrive.
//
// @param client A tracking client created by dvrTrackingSensorsCreate.
// @param context A client supplied pointer that will be passed to the callback.
// @param callback A callback that will receive the sensor events on an
// arbitrary thread.
// @return Zero on success, or negative error code.
int dvrTrackingSensorsStart(DvrTrackingSensors* sensors,
                            DvrTrackingSensorEventCallback callback,
                            void* context);

// Stops a DvrTrackingSensors session.
//
// This will stop the device sensors. dvrTrackingSensorsStart can be called to
// restart them again.
//
// @param client A tracking client created by dvrTrackingClientCreate.
// @return Zero on success, or negative error code.
int dvrTrackingSensorsStop(DvrTrackingSensors* sensors);

// Creates a tracking feature extractor.
//
// This will initialize but not start the feature extraction session. Upon
// successful creation, the client can call dvrTrackingFeatureExtractorStart to
// start receiving features.
//
// @param out_extractor The pointer of a DvrTrackingFeatureExtractor will be
//     filled here if the method call succeeds.
int dvrTrackingFeatureExtractorCreate(
    DvrTrackingFeatureExtractor** out_extractor);

// Destroys a tracking feature extractor.
//
// @param extractor The DvrTrackingFeatureExtractor to destroy.
void dvrTrackingFeatureExtractorDestroy(DvrTrackingFeatureExtractor* extractor);

// Starts the tracking feature extractor.
//
// This will start the extractor and start pumping the output feature events to
// the registered callback. Note that this method will create one or more
// threads to handle feature processing.
//
// @param extractor The DvrTrackingFeatureExtractor to destroy.
int dvrTrackingFeatureExtractorStart(DvrTrackingFeatureExtractor* extractor,
                                     DvrTrackingFeatureCallback callback,
                                     void* context);

// Stops the tracking feature extractor.
//
// This will stop the extractor session and clean up all internal resourcse
// related to this extractor. On succssful return, all internal therad started
// by dvrTrackingFeatureExtractorStart should be stopped.
//
// @param extractor The DvrTrackingFeatureExtractor to destroy.
int dvrTrackingFeatureExtractorStop(DvrTrackingFeatureExtractor* extractor);

// Processes one buffer to extract features from.
//
// The buffer will be sent over to DSP for feature extraction. Once the process
// is done, the processing thread will invoke DvrTrackingFeatureCallback with
// newly extracted features. Note that not all buffers will be processed, as the
// underlying DSP can only process buffers at a certain framerate. If a buffer
// needs to be skipped, out_skipped filed will be set to true. Also note that
// for successfully processed stereo buffer, two callbacks (one for each eye)
// will be fired.
//
// @param extractor The DvrTrackingFeatureExtractor to destroy.
// @param buffer The buffer to extract features from. Note that the buffer must
//     be in acquired state for the buffer to be processed. Also note that the
//     buffer will be released back to its producer on successful return of the
//     method.
// @param metadata The metadata associated with the buffer. Should be populated
//     by DvrTrackingCamera session as user defined metadata.
// @param out_skipped On successful return, the field will be set to true iff
//     the buffer was skipped; and false iff the buffer was processed. This
//     field is optional and nullptr can be passed here to ignore the field.
// @return Zero on success, or negative error code.
int dvrTrackingFeatureExtractorProcessBuffer(
    DvrTrackingFeatureExtractor* extractor, DvrReadBuffer* buffer,
    const DvrTrackingBufferMetadata* metadata, bool* out_skipped);

__END_DECLS

#endif  // ANDROID_DVR_TRACKING_H_