All Downloads are FREE. Search and download functionalities are using the official Maven repository.

android.media.Image Maven / Gradle / Ivy

Go to download

A library jar that provides APIs for Applications written for the Google Android Platform.

There is a newer version: 14-robolectric-10818077
Show newest version
/*
 * Copyright (C) 2013 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package android.media;

import java.nio.ByteBuffer;
import java.lang.AutoCloseable;

import android.graphics.Rect;

/**
 * 

A single complete image buffer to use with a media source such as a * {@link MediaCodec} or a * {@link android.hardware.camera2.CameraDevice CameraDevice}.

* *

This class allows for efficient direct application access to the pixel * data of the Image through one or more * {@link java.nio.ByteBuffer ByteBuffers}. Each buffer is encapsulated in a * {@link Plane} that describes the layout of the pixel data in that plane. Due * to this direct access, and unlike the {@link android.graphics.Bitmap Bitmap} class, * Images are not directly usable as as UI resources.

* *

Since Images are often directly produced or consumed by hardware * components, they are a limited resource shared across the system, and should * be closed as soon as they are no longer needed.

* *

For example, when using the {@link ImageReader} class to read out Images * from various media sources, not closing old Image objects will prevent the * availability of new Images once * {@link ImageReader#getMaxImages the maximum outstanding image count} is * reached. When this happens, the function acquiring new Images will typically * throw an {@link IllegalStateException}.

* * @see ImageReader */ public abstract class Image implements AutoCloseable { /** * @hide */ protected Image() { } /** * Get the format for this image. This format determines the number of * ByteBuffers needed to represent the image, and the general layout of the * pixel data in each in ByteBuffer. * *

* The format is one of the values from * {@link android.graphics.ImageFormat ImageFormat}. The mapping between the * formats and the planes is as follows: *

* * * * * * * * * * * * * * * * * * * * * * *
FormatPlane countLayout details
{@link android.graphics.ImageFormat#JPEG JPEG}1Compressed data, so row and pixel strides are 0. To uncompress, use * {@link android.graphics.BitmapFactory#decodeByteArray BitmapFactory#decodeByteArray}. *
{@link android.graphics.ImageFormat#YUV_420_888 YUV_420_888}3A luminance plane followed by the Cb and Cr chroma planes. * The chroma planes have half the width and height of the luminance * plane (4:2:0 subsampling). Each pixel sample in each plane has 8 bits. * Each plane has its own row stride and pixel stride.
{@link android.graphics.ImageFormat#RAW_SENSOR RAW_SENSOR}1A single plane of raw sensor image data, with 16 bits per color * sample. The details of the layout need to be queried from the source of * the raw sensor data, such as * {@link android.hardware.camera2.CameraDevice CameraDevice}. *
* * @see android.graphics.ImageFormat */ public abstract int getFormat(); /** * The width of the image in pixels. For formats where some color channels * are subsampled, this is the width of the largest-resolution plane. */ public abstract int getWidth(); /** * The height of the image in pixels. For formats where some color channels * are subsampled, this is the height of the largest-resolution plane. */ public abstract int getHeight(); /** * Get the timestamp associated with this frame. *

* The timestamp is measured in nanoseconds, and is monotonically * increasing. However, the zero point and whether the timestamp can be * compared against other sources of time or images depend on the source of * this image. *

*/ public abstract long getTimestamp(); private Rect mCropRect; /** * Get the crop rectangle associated with this frame. *

* The crop rectangle specifies the region of valid pixels in the image, * using coordinates in the largest-resolution plane. */ public Rect getCropRect() { if (mCropRect == null) { return new Rect(0, 0, getWidth(), getHeight()); } else { return new Rect(mCropRect); // return a copy } } /** * Set the crop rectangle associated with this frame. *

* The crop rectangle specifies the region of valid pixels in the image, * using coordinates in the largest-resolution plane. */ public void setCropRect(Rect cropRect) { cropRect = new Rect(cropRect); // make a copy cropRect.intersect(0, 0, getWidth(), getHeight()); mCropRect = cropRect; } /** * Get the array of pixel planes for this Image. The number of planes is * determined by the format of the Image. */ public abstract Plane[] getPlanes(); /** * Free up this frame for reuse. *

* After calling this method, calling any methods on this {@code Image} will * result in an {@link IllegalStateException}, and attempting to read from * {@link ByteBuffer ByteBuffers} returned by an earlier * {@link Plane#getBuffer} call will have undefined behavior. *

*/ @Override public abstract void close(); /** *

A single color plane of image data.

* *

The number and meaning of the planes in an Image are determined by the * format of the Image.

* *

Once the Image has been closed, any access to the the plane's * ByteBuffer will fail.

* * @see #getFormat */ public static abstract class Plane { /** * @hide */ protected Plane() { } /** *

The row stride for this color plane, in bytes.

* *

This is the distance between the start of two consecutive rows of * pixels in the image. The row stride is always greater than 0.

*/ public abstract int getRowStride(); /** *

The distance between adjacent pixel samples, in bytes.

* *

This is the distance between two consecutive pixel values in a row * of pixels. It may be larger than the size of a single pixel to * account for interleaved image data or padded formats. * The pixel stride is always greater than 0.

*/ public abstract int getPixelStride(); /** *

Get a direct {@link java.nio.ByteBuffer ByteBuffer} * containing the frame data.

* *

In particular, the buffer returned will always have * {@link java.nio.ByteBuffer#isDirect isDirect} return {@code true}, so * the underlying data could be mapped as a pointer in JNI without doing * any copies with {@code GetDirectBufferAddress}.

* * @return the byte buffer containing the image data for this plane. */ public abstract ByteBuffer getBuffer(); } }




© 2015 - 2024 Weber Informatics LLC | Privacy Policy