1/*
2 * Copyright (C) 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
17package android.hardware.camera.device@1.0;
18
19import android.hardware.camera.common@1.0::types;
20import android.hardware.graphics.common@1.0::types;
21
22/**
23 * Camera device HAL@1.0 preview stream operation interface.
24 */
25interface ICameraDevicePreviewCallback {
26
27    /**
28     * Acquire a buffer to write a preview buffer into.
29     *
30     * @return status The status code for this operation. If not OK, then
31     *     buffer and stride must not be used.
32     * @return bufferId A unique ID for the returned buffer.
33     * @return buffer A handle to the buffer to write into. Must be non-null if the bufferId has not
34     *     been seen by HAL before. Must be null if the bufferId is seen before. HAL must keep track
35     *     of the bufferId to actual buffer handle mapping.
36     * @return stride The stride between two rows of pixels in this buffer.
37     */
38    dequeueBuffer() generates (Status status, uint64_t bufferId, handle buffer, uint32_t stride);
39
40    /**
41     * Send a filled preview buffer to its consumer.
42     *
43     * @param bufferId The bufferId of the preview buffer
44     * @return status The status code for this operation.
45     */
46    enqueueBuffer(uint64_t bufferId) generates (Status status);
47
48    /**
49     * Return a preview buffer unfilled. This buffer must not be sent on to the
50     * preview consumer as a valid buffer, but may be reused as if it were
51     * empty.
52     *
53     * @param bufferId The bufferId of the preview buffer
54     * @return status The status code for this operation.
55     */
56    cancelBuffer(uint64_t bufferId) generates (Status status);
57
58    /**
59     * Set the number of preview buffers needed by the HAL.
60     *
61     * @param count The maximum number of preview buffers to allocate.
62     * @return status The status code for this operation.
63     */
64    setBufferCount(uint32_t count) generates (Status status);
65
66    /**
67     * Set the dimensions and format of future preview buffers.
68     *
69     * The next buffer that is dequeued must match the requested size and
70     * format.
71     *
72     * @return Status The status code for this operation.
73     */
74    setBuffersGeometry(uint32_t w, uint32_t h,
75            android.hardware.graphics.common@1.0::PixelFormat format)
76            generates (Status status);
77
78    /**
79     * Set the valid region of image data for the next buffer(s) to be enqueued.
80     *
81     * @return Status The status code for this operation.
82     */
83    setCrop(int32_t left, int32_t top, int32_t right, int32_t bottom)
84            generates (Status status);
85
86    /**
87     * Set the producer usage flags for the next buffer(s) to be enqueued.
88     *
89     * @return Status The status code for this operation.
90     */
91    setUsage(BufferUsage usage) generates (Status status);
92
93    /**
94     * Set the expected buffering mode for the preview output.
95     */
96    setSwapInterval(int32_t interval) generates (Status status);
97
98    /**
99     * Get the minimum number of buffers the preview consumer endpoint needs
100     * to hold for correct operation.
101     *
102     * @return Status The status code for this operation.
103     * @return count The number of buffers the consumer has requested.
104     */
105    getMinUndequeuedBufferCount() generates (Status status, uint32_t count);
106
107    /**
108     * Set the timestamp for the next buffer to enqueue
109     *
110     * Timestamps are measured in nanoseconds, and must be comparable
111     * and monotonically increasing between two frames in the same
112     * preview stream. They do not need to be comparable between
113     * consecutive or parallel preview streams, cameras, or app runs.
114     *
115     * @param timestamp The timestamp to set for future buffers.
116     * @return Status The status code for this operation.
117     */
118    setTimestamp(int64_t timestamp) generates (Status status);
119
120};
121