1 #ifndef ANDROID_DVR_TRACKING_H_ 2 #define ANDROID_DVR_TRACKING_H_ 3 4 #include <stdint.h> 5 #include <sys/cdefs.h> 6 7 #include <dvr/dvr_tracking_types.h> 8 9 __BEGIN_DECLS 10 11 typedef struct DvrReadBuffer DvrReadBuffer; 12 typedef struct DvrTrackingCamera DvrTrackingCamera; 13 typedef struct DvrTrackingFeatureExtractor DvrTrackingFeatureExtractor; 14 typedef struct DvrTrackingSensors DvrTrackingSensors; 15 typedef struct DvrWriteBufferQueue DvrWriteBufferQueue; 16 17 // The callback for DvrTrackingFeatureExtractor that will deliver the feature 18 // events. This callback is passed to dvrTrackingFeatureExtractorStart. 19 typedef void (*DvrTrackingFeatureCallback)(void* context, 20 const DvrTrackingFeatures* event); 21 22 // The callback for DvrTrackingSensors session that will deliver the events. 23 // This callback is passed to dvrTrackingSensorsStart. 24 typedef void (*DvrTrackingSensorEventCallback)(void* context, 25 DvrTrackingSensorEvent* event); 26 27 // Creates a DvrTrackingCamera session. 28 // 29 // On creation, the session is not in operating mode. Client code must call 30 // dvrTrackingCameraStart to bootstrap the underlying camera stack. 31 // 32 // There is no plan to expose camera configuration through this API. All camera 33 // parameters are determined by the system optimized for better tracking 34 // results. See b/78662281 for detailed deprecation plan of this API and the 35 // Stage 2 of VR tracking data source refactoring. 36 // 37 // @param out_camera The pointer of a DvrTrackingCamera will be filled here if 38 // the method call succeeds. 39 // @return Zero on success, or negative error code. 40 int dvrTrackingCameraCreate(DvrTrackingCamera** out_camera); 41 42 // Destroys a DvrTrackingCamera handle. 43 // 44 // @param camera The DvrTrackingCamera of interest. 45 void dvrTrackingCameraDestroy(DvrTrackingCamera* camera); 46 47 // Starts the DvrTrackingCamera. 48 // 49 // On successful return, all DvrReadBufferQueue's associated with the given 50 // write_queue will start to receive buffers from the camera stack. Note that 51 // clients of this API should not assume the buffer dimension, format, and/or 52 // usage of the outcoming buffers, as they are governed by the underlying camera 53 // logic. Also note that it's the client's responsibility to consume buffers 54 // from DvrReadBufferQueue on time and return them back to the producer; 55 // otherwise the camera stack might be blocked. 56 // 57 // @param camera The DvrTrackingCamera of interest. 58 // @param write_queue A DvrWriteBufferQueue that the camera stack can use to 59 // populate the buffer into. The queue must be empty and the camera stack 60 // will request buffer allocation with proper buffer dimension, format, and 61 // usage. Note that the write queue must be created with user_metadata_size 62 // set to sizeof(DvrTrackingBufferMetadata). On success, the write_queue 63 // handle will become invalid and the ownership of the queue handle will be 64 // transferred into the camera; otherwise, the write_queue handle will keep 65 // untouched and the caller still has the ownership. 66 // @return Zero on success, or negative error code. 67 int dvrTrackingCameraStart(DvrTrackingCamera* camera, 68 DvrWriteBufferQueue* write_queue); 69 70 // Stops the DvrTrackingCamera. 71 // 72 // On successful return, the DvrWriteBufferQueue set during 73 // dvrTrackingCameraStart will stop getting new buffers from the camera stack. 74 // 75 // @param camera The DvrTrackingCamera of interest. 76 // @return Zero on success, or negative error code. 77 int dvrTrackingCameraStop(DvrTrackingCamera* camera); 78 79 // Creates a DvrTrackingSensors session. 80 // 81 // This will initialize but not start device sensors (gyro / accel). Upon 82 // successfull creation, the clients can call dvrTrackingSensorsStart to start 83 // receiving sensor events. 84 // 85 // @param out_sensors The pointer of a DvrTrackingSensors will be filled here if 86 // the method call succeeds. 87 // @param mode The sensor mode. 88 // mode="ndk": Use the Android NDK. 89 // mode="direct": Use direct mode sensors (lower latency). 90 // @return Zero on success, or negative error code. 91 int dvrTrackingSensorsCreate(DvrTrackingSensors** out_sensors, 92 const char* mode); 93 94 // Destroys a DvrTrackingSensors session. 95 // 96 // @param sensors The DvrTrackingSensors struct to destroy. 97 void dvrTrackingSensorsDestroy(DvrTrackingSensors* sensors); 98 99 // Starts the tracking sensor session. 100 // 101 // This will start the device sensors and start pumping the feature and sensor 102 // events as they arrive. 103 // 104 // @param client A tracking client created by dvrTrackingSensorsCreate. 105 // @param context A client supplied pointer that will be passed to the callback. 106 // @param callback A callback that will receive the sensor events on an 107 // arbitrary thread. 108 // @return Zero on success, or negative error code. 109 int dvrTrackingSensorsStart(DvrTrackingSensors* sensors, 110 DvrTrackingSensorEventCallback callback, 111 void* context); 112 113 // Stops a DvrTrackingSensors session. 114 // 115 // This will stop the device sensors. dvrTrackingSensorsStart can be called to 116 // restart them again. 117 // 118 // @param client A tracking client created by dvrTrackingClientCreate. 119 // @return Zero on success, or negative error code. 120 int dvrTrackingSensorsStop(DvrTrackingSensors* sensors); 121 122 // Creates a tracking feature extractor. 123 // 124 // This will initialize but not start the feature extraction session. Upon 125 // successful creation, the client can call dvrTrackingFeatureExtractorStart to 126 // start receiving features. 127 // 128 // @param out_extractor The pointer of a DvrTrackingFeatureExtractor will be 129 // filled here if the method call succeeds. 130 int dvrTrackingFeatureExtractorCreate( 131 DvrTrackingFeatureExtractor** out_extractor); 132 133 // Destroys a tracking feature extractor. 134 // 135 // @param extractor The DvrTrackingFeatureExtractor to destroy. 136 void dvrTrackingFeatureExtractorDestroy(DvrTrackingFeatureExtractor* extractor); 137 138 // Starts the tracking feature extractor. 139 // 140 // This will start the extractor and start pumping the output feature events to 141 // the registered callback. Note that this method will create one or more 142 // threads to handle feature processing. 143 // 144 // @param extractor The DvrTrackingFeatureExtractor to destroy. 145 int dvrTrackingFeatureExtractorStart(DvrTrackingFeatureExtractor* extractor, 146 DvrTrackingFeatureCallback callback, 147 void* context); 148 149 // Stops the tracking feature extractor. 150 // 151 // This will stop the extractor session and clean up all internal resourcse 152 // related to this extractor. On succssful return, all internal therad started 153 // by dvrTrackingFeatureExtractorStart should be stopped. 154 // 155 // @param extractor The DvrTrackingFeatureExtractor to destroy. 156 int dvrTrackingFeatureExtractorStop(DvrTrackingFeatureExtractor* extractor); 157 158 // Processes one buffer to extract features from. 159 // 160 // The buffer will be sent over to DSP for feature extraction. Once the process 161 // is done, the processing thread will invoke DvrTrackingFeatureCallback with 162 // newly extracted features. Note that not all buffers will be processed, as the 163 // underlying DSP can only process buffers at a certain framerate. If a buffer 164 // needs to be skipped, out_skipped filed will be set to true. Also note that 165 // for successfully processed stereo buffer, two callbacks (one for each eye) 166 // will be fired. 167 // 168 // @param extractor The DvrTrackingFeatureExtractor to destroy. 169 // @param buffer The buffer to extract features from. Note that the buffer must 170 // be in acquired state for the buffer to be processed. Also note that the 171 // buffer will be released back to its producer on successful return of the 172 // method. 173 // @param metadata The metadata associated with the buffer. Should be populated 174 // by DvrTrackingCamera session as user defined metadata. 175 // @param out_skipped On successful return, the field will be set to true iff 176 // the buffer was skipped; and false iff the buffer was processed. This 177 // field is optional and nullptr can be passed here to ignore the field. 178 // @return Zero on success, or negative error code. 179 int dvrTrackingFeatureExtractorProcessBuffer( 180 DvrTrackingFeatureExtractor* extractor, DvrReadBuffer* buffer, 181 const DvrTrackingBufferMetadata* metadata, bool* out_skipped); 182 183 __END_DECLS 184 185 #endif // ANDROID_DVR_TRACKING_H_ 186