camera2 vndk: Clarify documentation around ACameraDevice::allocateCaptureRequest.

Test: builds; not a functional change.

Change-Id: Id3cc9013802eca044c24d910e4fce4fc7a640f2d
Signed-off-by: Jayant Chowdhary <jchowdhary@google.com>

camera/ndk/ndk_vendor/impl/ACameraDevice.cpp

@@ -289,7 +289,7 @@ camera_status_t CameraDevice::updateOutputConfigurationLocked(ACaptureSessionOut
 }
 
 camera_status_t
-CameraDevice::allocateCaptureRequest(
+CameraDevice::allocateCaptureRequestLocked(
         const ACaptureRequest* request, /*out*/sp<CaptureRequest> &outReq) {
     sp<CaptureRequest> req(new CaptureRequest());
     req->mCaptureRequest.physicalCameraSettings.resize(1);

camera/ndk/ndk_vendor/impl/ACameraDevice.h

@@ -169,7 +169,12 @@ class CameraDevice final : public RefBase {
 
     camera_status_t updateOutputConfigurationLocked(ACaptureSessionOutput *output);
 
-    camera_status_t allocateCaptureRequest(
+    // Since this writes to ICameraDeviceUser's fmq, clients must take care that:
+    //   a) This function is called serially.
+    //   b) This function is called in accordance with ICameraDeviceUser.submitRequestList,
+    //      otherwise, the wrong capture request might have the wrong settings
+    //      metadata associated with it.
+    camera_status_t allocateCaptureRequestLocked(
             const ACaptureRequest* request, sp<CaptureRequest>& outReq);
 
     static ACaptureRequest* allocateACaptureRequest(sp<CaptureRequest>& req);

camera/ndk/ndk_vendor/impl/ACameraDeviceVendor.inc

@@ -73,7 +73,7 @@ camera_status_t CameraDevice::submitRequestsLocked(
     requestsV.setCapacity(numRequests);
     for (int i = 0; i < numRequests; i++) {
         sp<CaptureRequest> req;
-        ret = allocateCaptureRequest(requests[i], req);
+        ret = allocateCaptureRequestLocked(requests[i], req);
         // We need to call this method since after submitRequestList is called,
         // the request metadata queue might have removed the capture request
         // metadata. Therefore we simply add the metadata to its wrapper class,