Image.java revision e3351f1942bfe86682389b278e7ff128a72ea671
1b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala/* 2b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala * Copyright (C) 2013 The Android Open Source Project 3b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala * 4b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala * Licensed under the Apache License, Version 2.0 (the "License"); 5b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala * you may not use this file except in compliance with the License. 6b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala * You may obtain a copy of the License at 7b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala * 8b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala * http://www.apache.org/licenses/LICENSE-2.0 9b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala * 10b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala * Unless required by applicable law or agreed to in writing, software 11b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala * distributed under the License is distributed on an "AS IS" BASIS, 12b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala * See the License for the specific language governing permissions and 14b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala * limitations under the License. 15b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala */ 16b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala 17b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvalapackage android.media; 18b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala 19b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvalaimport java.nio.ByteBuffer; 20b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvalaimport java.lang.AutoCloseable; 21b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala 22b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala/** 23b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala * <p>A single complete image buffer to use with a media source such as a 24b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala * {@link MediaCodec} or a 255e712064dfe48992f8f732208fa4fc13f3455b30Igor Murashkin * {@link android.hardware.camera2.CameraDevice CameraDevice}.</p> 26b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala * 27b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala * <p>This class allows for efficient direct application access to the pixel 28b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala * data of the Image through one or more 29b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala * {@link java.nio.ByteBuffer ByteBuffers}. Each buffer is encapsulated in a 30b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala * {@link Plane} that describes the layout of the pixel data in that plane. Due 315e712064dfe48992f8f732208fa4fc13f3455b30Igor Murashkin * to this direct access, and unlike the {@link android.graphics.Bitmap Bitmap} class, 32b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala * Images are not directly usable as as UI resources.</p> 33b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala * 34b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala * <p>Since Images are often directly produced or consumed by hardware 35b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala * components, they are a limited resource shared across the system, and should 36b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala * be closed as soon as they are no longer needed.</p> 37b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala * 38b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala * <p>For example, when using the {@link ImageReader} class to read out Images 39b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala * from various media sources, not closing old Image objects will prevent the 40b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala * availability of new Images once 41b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala * {@link ImageReader#getMaxImages the maximum outstanding image count} is 425e712064dfe48992f8f732208fa4fc13f3455b30Igor Murashkin * reached. When this happens, the function acquiring new Images will typically 43e3351f1942bfe86682389b278e7ff128a72ea671Igor Murashkin * throw an {@link IllegalStateException}.</p> 44b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala * 45b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala * @see ImageReader 46b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala */ 475e712064dfe48992f8f732208fa4fc13f3455b30Igor Murashkinpublic abstract class Image implements AutoCloseable { 485e712064dfe48992f8f732208fa4fc13f3455b30Igor Murashkin /** 495e712064dfe48992f8f732208fa4fc13f3455b30Igor Murashkin * @hide 505e712064dfe48992f8f732208fa4fc13f3455b30Igor Murashkin */ 515e712064dfe48992f8f732208fa4fc13f3455b30Igor Murashkin protected Image() { 525e712064dfe48992f8f732208fa4fc13f3455b30Igor Murashkin } 535e712064dfe48992f8f732208fa4fc13f3455b30Igor Murashkin 54b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala /** 55b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala * Get the format for this image. This format determines the number of 56b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala * ByteBuffers needed to represent the image, and the general layout of the 57b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala * pixel data in each in ByteBuffer. 58b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala * 595e712064dfe48992f8f732208fa4fc13f3455b30Igor Murashkin * <p> 60b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala * The format is one of the values from 615e712064dfe48992f8f732208fa4fc13f3455b30Igor Murashkin * {@link android.graphics.ImageFormat ImageFormat}. The mapping between the 625e712064dfe48992f8f732208fa4fc13f3455b30Igor Murashkin * formats and the planes is as follows: 635e712064dfe48992f8f732208fa4fc13f3455b30Igor Murashkin * </p> 64b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala * 65b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala * <table> 66af753a2dfc66c92bfcac64b77c7a4d89d9434ad8Zhijun He * <tr> 67af753a2dfc66c92bfcac64b77c7a4d89d9434ad8Zhijun He * <th>Format</th> 68af753a2dfc66c92bfcac64b77c7a4d89d9434ad8Zhijun He * <th>Plane count</th> 69af753a2dfc66c92bfcac64b77c7a4d89d9434ad8Zhijun He * <th>Layout details</th> 70af753a2dfc66c92bfcac64b77c7a4d89d9434ad8Zhijun He * </tr> 71b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala * <tr> 725e712064dfe48992f8f732208fa4fc13f3455b30Igor Murashkin * <td>{@link android.graphics.ImageFormat#JPEG JPEG}</td> 73b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala * <td>1</td> 74b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala * <td>Compressed data, so row and pixel strides are 0. To uncompress, use 755e712064dfe48992f8f732208fa4fc13f3455b30Igor Murashkin * {@link android.graphics.BitmapFactory#decodeByteArray BitmapFactory#decodeByteArray}. 765e712064dfe48992f8f732208fa4fc13f3455b30Igor Murashkin * </td> 77b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala * </tr> 78b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala * <tr> 795e712064dfe48992f8f732208fa4fc13f3455b30Igor Murashkin * <td>{@link android.graphics.ImageFormat#YUV_420_888 YUV_420_888}</td> 80b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala * <td>3</td> 81b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala * <td>A luminance plane followed by the Cb and Cr chroma planes. 82b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala * The chroma planes have half the width and height of the luminance 83b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala * plane (4:2:0 subsampling). Each pixel sample in each plane has 8 bits. 84b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala * Each plane has its own row stride and pixel stride.</td> 85b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala * </tr> 86b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala * <tr> 875e712064dfe48992f8f732208fa4fc13f3455b30Igor Murashkin * <td>{@link android.graphics.ImageFormat#RAW_SENSOR RAW_SENSOR}</td> 88b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala * <td>1</td> 89b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala * <td>A single plane of raw sensor image data, with 16 bits per color 90b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala * sample. The details of the layout need to be queried from the source of 91b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala * the raw sensor data, such as 925e712064dfe48992f8f732208fa4fc13f3455b30Igor Murashkin * {@link android.hardware.camera2.CameraDevice CameraDevice}. 93b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala * </td> 94b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala * </tr> 95b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala * </table> 96b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala * 97b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala * @see android.graphics.ImageFormat 98b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala */ 995e712064dfe48992f8f732208fa4fc13f3455b30Igor Murashkin public abstract int getFormat(); 100b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala 101b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala /** 102b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala * The width of the image in pixels. For formats where some color channels 103b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala * are subsampled, this is the width of the largest-resolution plane. 104b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala */ 1055e712064dfe48992f8f732208fa4fc13f3455b30Igor Murashkin public abstract int getWidth(); 106b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala 107b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala /** 108b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala * The height of the image in pixels. For formats where some color channels 109b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala * are subsampled, this is the height of the largest-resolution plane. 110b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala */ 1115e712064dfe48992f8f732208fa4fc13f3455b30Igor Murashkin public abstract int getHeight(); 112b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala 113b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala /** 1145e712064dfe48992f8f732208fa4fc13f3455b30Igor Murashkin * Get the timestamp associated with this frame. 1155e712064dfe48992f8f732208fa4fc13f3455b30Igor Murashkin * <p> 1165e712064dfe48992f8f732208fa4fc13f3455b30Igor Murashkin * The timestamp is measured in nanoseconds, and is monotonically 1175e712064dfe48992f8f732208fa4fc13f3455b30Igor Murashkin * increasing. However, the zero point and whether the timestamp can be 1185e712064dfe48992f8f732208fa4fc13f3455b30Igor Murashkin * compared against other sources of time or images depend on the source of 1195e712064dfe48992f8f732208fa4fc13f3455b30Igor Murashkin * this image. 1205e712064dfe48992f8f732208fa4fc13f3455b30Igor Murashkin * </p> 121b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala */ 1225e712064dfe48992f8f732208fa4fc13f3455b30Igor Murashkin public abstract long getTimestamp(); 123b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala 124b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala /** 125b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala * Get the array of pixel planes for this Image. The number of planes is 126b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala * determined by the format of the Image. 127b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala */ 1285e712064dfe48992f8f732208fa4fc13f3455b30Igor Murashkin public abstract Plane[] getPlanes(); 129b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala 130b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala /** 1315e712064dfe48992f8f732208fa4fc13f3455b30Igor Murashkin * Free up this frame for reuse. 1325e712064dfe48992f8f732208fa4fc13f3455b30Igor Murashkin * <p> 1335e712064dfe48992f8f732208fa4fc13f3455b30Igor Murashkin * After calling this method, calling any methods on this {@code Image} will 1345e712064dfe48992f8f732208fa4fc13f3455b30Igor Murashkin * result in an {@link IllegalStateException}, and attempting to read from 1355e712064dfe48992f8f732208fa4fc13f3455b30Igor Murashkin * {@link ByteBuffer ByteBuffers} returned by an earlier 1365e712064dfe48992f8f732208fa4fc13f3455b30Igor Murashkin * {@link Plane#getBuffer} call will have undefined behavior. 1375e712064dfe48992f8f732208fa4fc13f3455b30Igor Murashkin * </p> 138b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala */ 1395e712064dfe48992f8f732208fa4fc13f3455b30Igor Murashkin @Override 1405e712064dfe48992f8f732208fa4fc13f3455b30Igor Murashkin public abstract void close(); 141b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala 142b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala /** 143b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala * <p>A single color plane of image data.</p> 144b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala * 145b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala * <p>The number and meaning of the planes in an Image are determined by the 146b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala * format of the Image.</p> 147b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala * 148b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala * <p>Once the Image has been closed, any access to the the plane's 149b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala * ByteBuffer will fail.</p> 150b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala * 151b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala * @see #getFormat 152b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala */ 1535e712064dfe48992f8f732208fa4fc13f3455b30Igor Murashkin public static abstract class Plane { 154b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala /** 1555e712064dfe48992f8f732208fa4fc13f3455b30Igor Murashkin * @hide 1565e712064dfe48992f8f732208fa4fc13f3455b30Igor Murashkin */ 1575e712064dfe48992f8f732208fa4fc13f3455b30Igor Murashkin protected Plane() { 1585e712064dfe48992f8f732208fa4fc13f3455b30Igor Murashkin } 1595e712064dfe48992f8f732208fa4fc13f3455b30Igor Murashkin 1605e712064dfe48992f8f732208fa4fc13f3455b30Igor Murashkin /** 1615e712064dfe48992f8f732208fa4fc13f3455b30Igor Murashkin * <p>The row stride for this color plane, in bytes.</p> 162b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala * 163b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala * <p>This is the distance between the start of two consecutive rows of 1645e712064dfe48992f8f732208fa4fc13f3455b30Igor Murashkin * pixels in the image. The row stride is always greater than 0.</p> 165b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala */ 1665e712064dfe48992f8f732208fa4fc13f3455b30Igor Murashkin public abstract int getRowStride(); 167b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala /** 168b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala * <p>The distance between adjacent pixel samples, in bytes.</p> 169b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala * 170b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala * <p>This is the distance between two consecutive pixel values in a row 171b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala * of pixels. It may be larger than the size of a single pixel to 1725e712064dfe48992f8f732208fa4fc13f3455b30Igor Murashkin * account for interleaved image data or padded formats. 1735e712064dfe48992f8f732208fa4fc13f3455b30Igor Murashkin * The pixel stride is always greater than 0.</p> 174b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala */ 1755e712064dfe48992f8f732208fa4fc13f3455b30Igor Murashkin public abstract int getPixelStride(); 176b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala /** 1775e712064dfe48992f8f732208fa4fc13f3455b30Igor Murashkin * <p>Get a direct {@link java.nio.ByteBuffer ByteBuffer} 178b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala * containing the frame data.</p> 179b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala * 1805e712064dfe48992f8f732208fa4fc13f3455b30Igor Murashkin * <p>In particular, the buffer returned will always have 1815e712064dfe48992f8f732208fa4fc13f3455b30Igor Murashkin * {@link java.nio.ByteBuffer#isDirect isDirect} return {@code true}, so 1825e712064dfe48992f8f732208fa4fc13f3455b30Igor Murashkin * the underlying data could be mapped as a pointer in JNI without doing 1835e712064dfe48992f8f732208fa4fc13f3455b30Igor Murashkin * any copies with {@code GetDirectBufferAddress}.</p> 1845e712064dfe48992f8f732208fa4fc13f3455b30Igor Murashkin * 185b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala * @return the byte buffer containing the image data for this plane. 186b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala */ 1875e712064dfe48992f8f732208fa4fc13f3455b30Igor Murashkin public abstract ByteBuffer getBuffer(); 188b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala } 189b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala 190b2675542c2f414154125b534767ae0903fba581eEino-Ville Talvala} 191