1/*
2 * Copyright (C) 2013 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.media;
18
19import java.nio.ByteBuffer;
20import java.lang.AutoCloseable;
21
22import android.graphics.Rect;
23
24/**
25 * <p>A single complete image buffer to use with a media source such as a
26 * {@link MediaCodec} or a
27 * {@link android.hardware.camera2.CameraDevice CameraDevice}.</p>
28 *
29 * <p>This class allows for efficient direct application access to the pixel
30 * data of the Image through one or more
31 * {@link java.nio.ByteBuffer ByteBuffers}. Each buffer is encapsulated in a
32 * {@link Plane} that describes the layout of the pixel data in that plane. Due
33 * to this direct access, and unlike the {@link android.graphics.Bitmap Bitmap} class,
34 * Images are not directly usable as as UI resources.</p>
35 *
36 * <p>Since Images are often directly produced or consumed by hardware
37 * components, they are a limited resource shared across the system, and should
38 * be closed as soon as they are no longer needed.</p>
39 *
40 * <p>For example, when using the {@link ImageReader} class to read out Images
41 * from various media sources, not closing old Image objects will prevent the
42 * availability of new Images once
43 * {@link ImageReader#getMaxImages the maximum outstanding image count} is
44 * reached. When this happens, the function acquiring new Images will typically
45 * throw an {@link IllegalStateException}.</p>
46 *
47 * @see ImageReader
48 */
49public abstract class Image implements AutoCloseable {
50    /**
51     * @hide
52     */
53    protected Image() {
54    }
55
56    /**
57     * Get the format for this image. This format determines the number of
58     * ByteBuffers needed to represent the image, and the general layout of the
59     * pixel data in each in ByteBuffer.
60     *
61     * <p>
62     * The format is one of the values from
63     * {@link android.graphics.ImageFormat ImageFormat}. The mapping between the
64     * formats and the planes is as follows:
65     * </p>
66     *
67     * <table>
68     * <tr>
69     *   <th>Format</th>
70     *   <th>Plane count</th>
71     *   <th>Layout details</th>
72     * </tr>
73     * <tr>
74     *   <td>{@link android.graphics.ImageFormat#JPEG JPEG}</td>
75     *   <td>1</td>
76     *   <td>Compressed data, so row and pixel strides are 0. To uncompress, use
77     *      {@link android.graphics.BitmapFactory#decodeByteArray BitmapFactory#decodeByteArray}.
78     *   </td>
79     * </tr>
80     * <tr>
81     *   <td>{@link android.graphics.ImageFormat#YUV_420_888 YUV_420_888}</td>
82     *   <td>3</td>
83     *   <td>A luminance plane followed by the Cb and Cr chroma planes.
84     *     The chroma planes have half the width and height of the luminance
85     *     plane (4:2:0 subsampling). Each pixel sample in each plane has 8 bits.
86     *     Each plane has its own row stride and pixel stride.</td>
87     * </tr>
88     * <tr>
89     *   <td>{@link android.graphics.ImageFormat#RAW_SENSOR RAW_SENSOR}</td>
90     *   <td>1</td>
91     *   <td>A single plane of raw sensor image data, with 16 bits per color
92     *     sample. The details of the layout need to be queried from the source of
93     *     the raw sensor data, such as
94     *     {@link android.hardware.camera2.CameraDevice CameraDevice}.
95     *   </td>
96     * </tr>
97     * </table>
98     *
99     * @see android.graphics.ImageFormat
100     */
101    public abstract int getFormat();
102
103    /**
104     * The width of the image in pixels. For formats where some color channels
105     * are subsampled, this is the width of the largest-resolution plane.
106     */
107    public abstract int getWidth();
108
109    /**
110     * The height of the image in pixels. For formats where some color channels
111     * are subsampled, this is the height of the largest-resolution plane.
112     */
113    public abstract int getHeight();
114
115    /**
116     * Get the timestamp associated with this frame.
117     * <p>
118     * The timestamp is measured in nanoseconds, and is monotonically
119     * increasing. However, the zero point and whether the timestamp can be
120     * compared against other sources of time or images depend on the source of
121     * this image.
122     * </p>
123     */
124    public abstract long getTimestamp();
125
126    private Rect mCropRect;
127
128    /**
129     * Get the crop rectangle associated with this frame.
130     * <p>
131     * The crop rectangle specifies the region of valid pixels in the image,
132     * using coordinates in the largest-resolution plane.
133     */
134    public Rect getCropRect() {
135        if (mCropRect == null) {
136            return new Rect(0, 0, getWidth(), getHeight());
137        } else {
138            return new Rect(mCropRect); // return a copy
139        }
140    }
141
142    /**
143     * Set the crop rectangle associated with this frame.
144     * <p>
145     * The crop rectangle specifies the region of valid pixels in the image,
146     * using coordinates in the largest-resolution plane.
147     */
148    public void setCropRect(Rect cropRect) {
149        if (cropRect != null) {
150            cropRect = new Rect(cropRect);  // make a copy
151            cropRect.intersect(0, 0, getWidth(), getHeight());
152        }
153        mCropRect = cropRect;
154    }
155
156    /**
157     * Get the array of pixel planes for this Image. The number of planes is
158     * determined by the format of the Image.
159     */
160    public abstract Plane[] getPlanes();
161
162    /**
163     * Free up this frame for reuse.
164     * <p>
165     * After calling this method, calling any methods on this {@code Image} will
166     * result in an {@link IllegalStateException}, and attempting to read from
167     * {@link ByteBuffer ByteBuffers} returned by an earlier
168     * {@link Plane#getBuffer} call will have undefined behavior.
169     * </p>
170     */
171    @Override
172    public abstract void close();
173
174    /**
175     * <p>A single color plane of image data.</p>
176     *
177     * <p>The number and meaning of the planes in an Image are determined by the
178     * format of the Image.</p>
179     *
180     * <p>Once the Image has been closed, any access to the the plane's
181     * ByteBuffer will fail.</p>
182     *
183     * @see #getFormat
184     */
185    public static abstract class Plane {
186        /**
187         * @hide
188         */
189        protected Plane() {
190        }
191
192        /**
193         * <p>The row stride for this color plane, in bytes.</p>
194         *
195         * <p>This is the distance between the start of two consecutive rows of
196         * pixels in the image. The row stride is always greater than 0.</p>
197         */
198        public abstract int getRowStride();
199        /**
200         * <p>The distance between adjacent pixel samples, in bytes.</p>
201         *
202         * <p>This is the distance between two consecutive pixel values in a row
203         * of pixels. It may be larger than the size of a single pixel to
204         * account for interleaved image data or padded formats.
205         * The pixel stride is always greater than 0.</p>
206         */
207        public abstract int getPixelStride();
208        /**
209         * <p>Get a direct {@link java.nio.ByteBuffer ByteBuffer}
210         * containing the frame data.</p>
211         *
212         * <p>In particular, the buffer returned will always have
213         * {@link java.nio.ByteBuffer#isDirect isDirect} return {@code true}, so
214         * the underlying data could be mapped as a pointer in JNI without doing
215         * any copies with {@code GetDirectBufferAddress}.</p>
216         *
217         * <p>For raw formats, each plane is only guaranteed to contain data
218         * up to the last pixel in the last row. In other words, the stride
219         * after the last row may not be mapped into the buffer. This is a
220         * necessary requirement for any interleaved format.</p>
221         *
222         * @return the byte buffer containing the image data for this plane.
223         */
224        public abstract ByteBuffer getBuffer();
225    }
226
227}
228