186 lines
8.2 KiB
C
186 lines
8.2 KiB
C
#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_
|