SurfaceTexture.java revision e309a0fd2e528039b3c1f1372a9a7095bcd852cc
1/* 2 * Copyright (C) 2010 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.graphics; 18 19import java.lang.ref.WeakReference; 20import android.os.Handler; 21import android.os.Looper; 22import android.os.Message; 23 24/** 25 * Captures frames from an image stream as an OpenGL ES texture. 26 * 27 * <p>The image stream may come from either camera preview or video decode. A SurfaceTexture 28 * may be used in place of a SurfaceHolder when specifying the output destination of a 29 * {@link android.hardware.Camera} or {@link android.media.MediaPlayer} 30 * object. Doing so will cause all the frames from the image stream to be sent to the 31 * SurfaceTexture object rather than to the device's display. When {@link #updateTexImage} is 32 * called, the contents of the texture object specified when the SurfaceTexture was created are 33 * updated to contain the most recent image from the image stream. This may cause some frames of 34 * the stream to be skipped. 35 * 36 * <p>When sampling from the texture one should first transform the texture coordinates using the 37 * matrix queried via {@link #getTransformMatrix}. The transform matrix may change each time {@link 38 * #updateTexImage} is called, so it should be re-queried each time the texture image is updated. 39 * This matrix transforms traditional 2D OpenGL ES texture coordinate column vectors of the form (s, 40 * t, 0, 1) where s and t are on the inclusive interval [0, 1] to the proper sampling location in 41 * the streamed texture. This transform compensates for any properties of the image stream source 42 * that cause it to appear different from a traditional OpenGL ES texture. For example, sampling 43 * from the bottom left corner of the image can be accomplished by transforming the column vector 44 * (0, 0, 0, 1) using the queried matrix, while sampling from the top right corner of the image can 45 * be done by transforming (1, 1, 0, 1). 46 * 47 * <p>The texture object uses the GL_TEXTURE_EXTERNAL_OES texture target, which is defined by the 48 * <a href="http://www.khronos.org/registry/gles/extensions/OES/OES_EGL_image_external.txt"> 49 * GL_OES_EGL_image_external</a> OpenGL ES extension. This limits how the texture may be used. 50 * Each time the texture is bound it must be bound to the GL_TEXTURE_EXTERNAL_OES target rather than 51 * the GL_TEXTURE_2D target. Additionally, any OpenGL ES 2.0 shader that samples from the texture 52 * must declare its use of this extension using, for example, an "#extension 53 * GL_OES_EGL_image_external : require" directive. Such shaders must also access the texture using 54 * the samplerExternalOES GLSL sampler type. 55 * 56 * <p>SurfaceTexture objects may be created on any thread. {@link #updateTexImage} may only be 57 * called on the thread with the OpenGL ES context that contains the texture object. The 58 * frame-available callback is called on an arbitrary thread, so unless special care is taken {@link 59 * #updateTexImage} should not be called directly from the callback. 60 */ 61public class SurfaceTexture { 62 63 private EventHandler mEventHandler; 64 private OnFrameAvailableListener mOnFrameAvailableListener; 65 66 @SuppressWarnings("unused") 67 private int mSurfaceTexture; 68 69 /** 70 * Callback interface for being notified that a new stream frame is available. 71 */ 72 public interface OnFrameAvailableListener { 73 void onFrameAvailable(SurfaceTexture surfaceTexture); 74 } 75 76 /** 77 * Exception thrown when a surface couldn't be created or resized 78 */ 79 public static class OutOfResourcesException extends Exception { 80 public OutOfResourcesException() { 81 } 82 public OutOfResourcesException(String name) { 83 super(name); 84 } 85 } 86 87 /** 88 * Construct a new SurfaceTexture to stream images to a given OpenGL texture. 89 * 90 * @param texName the OpenGL texture object name (e.g. generated via glGenTextures) 91 */ 92 public SurfaceTexture(int texName) { 93 Looper looper; 94 if ((looper = Looper.myLooper()) != null) { 95 mEventHandler = new EventHandler(looper); 96 } else if ((looper = Looper.getMainLooper()) != null) { 97 mEventHandler = new EventHandler(looper); 98 } else { 99 mEventHandler = null; 100 } 101 nativeInit(texName, new WeakReference<SurfaceTexture>(this)); 102 } 103 104 /** 105 * Register a callback to be invoked when a new image frame becomes available to the 106 * SurfaceTexture. Note that this callback may be called on an arbitrary thread, so it is not 107 * safe to call {@link #updateTexImage} without first binding the OpenGL ES context to the 108 * thread invoking the callback. 109 */ 110 public void setOnFrameAvailableListener(OnFrameAvailableListener l) { 111 mOnFrameAvailableListener = l; 112 } 113 114 /** 115 * Update the texture image to the most recent frame from the image stream. This may only be 116 * called while the OpenGL ES context that owns the texture is bound to the thread. It will 117 * implicitly bind its texture to the GL_TEXTURE_EXTERNAL_OES texture target. 118 */ 119 public void updateTexImage() { 120 nativeUpdateTexImage(); 121 } 122 123 /** 124 * Retrieve the 4x4 texture coordinate transform matrix associated with the texture image set by 125 * the most recent call to updateTexImage. 126 * 127 * This transform matrix maps 2D homogeneous texture coordinates of the form (s, t, 0, 1) with s 128 * and t in the inclusive range [0, 1] to the texture coordinate that should be used to sample 129 * that location from the texture. Sampling the texture outside of the range of this transform 130 * is undefined. 131 * 132 * The matrix is stored in column-major order so that it may be passed directly to OpenGL ES via 133 * the glLoadMatrixf or glUniformMatrix4fv functions. 134 * 135 * @param mtx the array into which the 4x4 matrix will be stored. The array must have exactly 136 * 16 elements. 137 */ 138 public void getTransformMatrix(float[] mtx) { 139 // Note we intentionally don't check mtx for null, so this will result in a 140 // NullPointerException. But it's safe because it happens before the call to native. 141 if (mtx.length != 16) { 142 throw new IllegalArgumentException(); 143 } 144 nativeGetTransformMatrix(mtx); 145 } 146 147 /** 148 * Retrieve the timestamp associated with the texture image set by the most recent call to 149 * updateTexImage. 150 * 151 * This timestamp is in nanoseconds, and is guaranteed to be monotonically increasing. The 152 * specific meaning and zero point of the timestamp depends on the source providing images to 153 * the SurfaceTexture. Unless otherwise specified by the image source, timestamps cannot 154 * generally be compared across SurfaceTexture instances, or across multiple program 155 * invocations. It is mostly useful for determining time offsets between subsequent frames. 156 */ 157 public long getTimestamp() { 158 return nativeGetTimestamp(); 159 } 160 161 protected void finalize() throws Throwable { 162 try { 163 nativeFinalize(); 164 } finally { 165 super.finalize(); 166 } 167 } 168 169 private class EventHandler extends Handler { 170 public EventHandler(Looper looper) { 171 super(looper); 172 } 173 174 @Override 175 public void handleMessage(Message msg) { 176 if (mOnFrameAvailableListener != null) { 177 mOnFrameAvailableListener.onFrameAvailable(SurfaceTexture.this); 178 } 179 return; 180 } 181 } 182 183 private static void postEventFromNative(Object selfRef) { 184 WeakReference weakSelf = (WeakReference)selfRef; 185 SurfaceTexture st = (SurfaceTexture)weakSelf.get(); 186 if (st == null) { 187 return; 188 } 189 190 if (st.mEventHandler != null) { 191 Message m = st.mEventHandler.obtainMessage(); 192 st.mEventHandler.sendMessage(m); 193 } 194 } 195 196 private native void nativeInit(int texName, Object weakSelf); 197 private native void nativeFinalize(); 198 private native void nativeGetTransformMatrix(float[] mtx); 199 private native long nativeGetTimestamp(); 200 private native void nativeUpdateTexImage(); 201 202 /* 203 * We use a class initializer to allow the native code to cache some 204 * field offsets. 205 */ 206 private static native void nativeClassInit(); 207 static { nativeClassInit(); } 208} 209