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 17 package android.media; 18 19 import java.nio.ByteBuffer; 20 import 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 */ 46 public abstract class Image implements AutoCloseable { 47 /** 48 * @hide 49 */ Image()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 */ getFormat()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 */ getWidth()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 */ getHeight()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 */ getTimestamp()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 */ getPlanes()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 close()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 */ Plane()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 */ getRowStride()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 */ getPixelStride()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 */ getBuffer()177 public abstract ByteBuffer getBuffer(); 178 } 179 180 } 181