Home | History | Annotate | Download | only in include 
      1 /*
      2  * Copyright 2016 The Android Open Source Project
      3  *
      4  * Licensed under the Apache License, Version 2.0 (the "License");
      5  * you may not use this file except in compliance with the License.
      6  * You may obtain a copy of the License at
      7  *
      8  *      http://www.apache.org/licenses/LICENSE-2.0
      9  *
     10  * Unless required by applicable law or agreed to in writing, software
     11  * distributed under the License is distributed on an "AS IS" BASIS,
     12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
     13  * See the License for the specific language governing permissions and
     14  * limitations under the License.
     15  */
     16 
     17 #ifndef HDR_PLUS_CLIENT_H
     18 #define HDR_PLUS_CLIENT_H
     19 
     20 #include "CameraMetadata.h"
     21 #include "hardware/camera3.h"
     22 #include "HdrPlusClientListener.h"
     23 #include "HdrPlusTypes.h"
     24 
     25 using ::android::hardware::camera::common::V1_0::helper::CameraMetadata;
     26 namespace android {
     27 
     28 /**
     29  * HdrPlusClient
     30  *
     31  * HdrPlusClient class can be used to connect to HDR+ service to perform HDR+ processing on
     32  * Easel.
     33  */
     34 class HdrPlusClient {
     35 public:
     36     // HdrPlusClientListener is the listener to receive callbacks from HDR+ client. The listener
     37     // must be valid during the life cycle of HdrPlusClient
     38     HdrPlusClient(HdrPlusClientListener *) {};
     39     /*
     40      * The recommended way to create an HdrPlusClient instance is via
     41      * EaselManagerClient::openHdrPlusClientAsync() or EaselManagerClient::openHdrPlusClientAsync().
     42      * EaselManagerClient will make sure Easel is in a valid state to open an HDR+ client. To close
     43      * an HdrPlusClient, use EaselManagerClient::closeHdrPlusClient.
     44      */
     45     virtual ~HdrPlusClient() {};
     46 
     47     /*
     48      * Connect to HDR+ service.
     49      *
     50      * If EaselManagerClient is used to create the HdrPlusClient, it is already connected.
     51      *
     52      * Returns:
     53      *  0:          on success.
     54      *  -EEXIST:    if it's already connected.
     55      *  -ENODEV:    if connecting failed due to a serious error.
     56      */
     57     virtual status_t connect() = 0;
     58 
     59     /*
     60      * Set the static metadata of current camera device.
     61      *
     62      * Must be called after connect() and before configuring streams.
     63      *
     64      * staticMetadata is the static metadata of current camera device.
     65      *
     66      * Returns:
     67      *  0:         on success.
     68      *  -ENODEV:   if HDR+ service is not connected.
     69      */
     70     virtual status_t setStaticMetadata(const camera_metadata_t &staticMetadata) = 0;
     71 
     72     /*
     73      * Configure streams.
     74      *
     75      * Must be called when configuration changes including input (sensor) resolution and format, and
     76      * output resolutions and formats.
     77      *
     78      * inputConfig contains the information about the input frames or sensor configurations.
     79      * outputConfigs is a vector of output stream configurations.
     80      *
     81      * Returns:
     82      *  0:          on success.
     83      *  -EINVAL:    if outputConfigs is empty or the configurations are not supported.
     84      *  -ENODEV:    if HDR+ service is not connected.
     85      */
     86     virtual status_t configureStreams(const pbcamera::InputConfiguration &inputConfig,
     87             const std::vector<pbcamera::StreamConfiguration> &outputConfigs) = 0;
     88 
     89     /*
     90      * Enable or disable ZSL HDR+ mode.
     91      *
     92      * When ZSL HDR+ mode is enabled, Easel will capture ZSL RAW buffers. ZSL HDR+ mode should be
     93      * disabled to reduce power consumption when HDR+ processing is not necessary, e.g in video
     94      * mode.
     95      *
     96      * enabled is a flag indicating whether to enable ZSL HDR+ mode.
     97      *
     98      * Returns:
     99      *  0:          on success.
    100      *  -ENODEV:    if HDR+ service is not connected, or streams are not configured.
    101      */
    102     virtual status_t setZslHdrPlusMode(bool enabled) = 0;
    103 
    104     /*
    105      * Submit a capture request for HDR+ outputs.
    106      *
    107      * For each output buffer in CaptureRequest, it will be returned in a CaptureResult via
    108      * HdrPlusClientListener::onCaptureResult(). HdrPlusClientListener::onCaptureResult() may be
    109      * invoked multiple times to return all output buffers in one CaptureRequest. Each output
    110      * buffer will be returned in CaptureResult only once.
    111      *
    112      * request is a CaptureRequest containing output buffers to be filled by HDR+ service.
    113      * requestMetadata is the metadata for this request.
    114      *
    115      * Returns:
    116      *  0:              on success.
    117      *  -EINVAL:        if the request is invalid such as containing invalid stream IDs.
    118      */
    119     virtual status_t submitCaptureRequest(pbcamera::CaptureRequest *request,
    120             const CameraMetadata &requestMetadata) = 0;
    121 
    122     /*
    123      * Send an input buffer to HDR+ service. This is used when HDR+ service's input buffers come
    124      * from the client rather than MIPI.
    125      *
    126      * inputBuffer is the input buffer to send to HDR+ service. After this method returns, the
    127      *             buffer has been copied (with DMA) to HDR+ service and the caller has the
    128      *             ownership of the buffer.
    129      */
    130     virtual void notifyInputBuffer(const pbcamera::StreamBuffer &inputBuffer,
    131             int64_t timestampNs) = 0;
    132 
    133     /*
    134      * Notify about result metadata of a frame that AP captured. This may be called multiple times
    135      * for a frame to send multiple partial metadata and lastMetadata must be false except for the
    136      * last partial metadata. When there is only one metadata for a frame, lastMetadata must be
    137      * true.
    138      *
    139      * frameNumber is a unique frame number that the metadata belong to.
    140      * resultMetadata is the result metadata of a frame that AP captured.
    141      * lastMetadata is a flag indicating whether this is the last metadata for the frame number.
    142      */
    143     virtual void notifyFrameMetadata(uint32_t frameNumber, const camera_metadata_t &resultMetadata,
    144             bool lastMetadata=true) = 0;
    145 
    146     /*
    147      * Notify Easel has encountered a fatal error and HDR+ client should stop sending messages
    148      * to Easel.
    149      */
    150     virtual void nofityEaselFatalError() = 0;
    151 
    152 private:
    153     // Disallow copy and assign.
    154     HdrPlusClient(const HdrPlusClient&) = delete;
    155     void operator=(const HdrPlusClient&) = delete;
    156 };
    157 
    158 } // namespace android
    159 
    160 #endif // HDR_PLUS_CLIENT_H
    161