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
25using ::android::hardware::camera::common::V1_0::helper::CameraMetadata;
26namespace 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 */
34class HdrPlusClient {
35public:
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
152private:
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