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