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