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