SurfaceTexture.java revision 37cec0fc50760fe89614863eded14011f9412534
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>The texture object uses the GL_TEXTURE_EXTERNAL_OES texture target, which is defined by the 36 * OES_EGL_image_external OpenGL ES extension. This limits how the texture may be used. 37 * 38 * <p>SurfaceTexture objects may be created on any thread. {@link #updateTexImage} may only be 39 * called on the thread with the OpenGL ES context that contains the texture object. The 40 * frame-available callback is called on an arbitrary thread, so unless special care is taken {@link 41 * #updateTexImage} should not be called directly from the callback. 42 */ 43public class SurfaceTexture { 44 45 private EventHandler mEventHandler; 46 private OnFrameAvailableListener mOnFrameAvailableListener; 47 48 @SuppressWarnings("unused") 49 private int mSurfaceTexture; 50 51 /** 52 * Callback interface for being notified that a new stream frame is available. 53 */ 54 public interface OnFrameAvailableListener { 55 void onFrameAvailable(SurfaceTexture surfaceTexture); 56 } 57 58 /** 59 * Exception thrown when a surface couldn't be created or resized 60 */ 61 public static class OutOfResourcesException extends Exception { 62 public OutOfResourcesException() { 63 } 64 public OutOfResourcesException(String name) { 65 super(name); 66 } 67 } 68 69 /** 70 * Construct a new SurfaceTexture to stream images to a given OpenGL texture. 71 * 72 * @param texName the OpenGL texture object name (e.g. generated via glGenTextures) 73 */ 74 public SurfaceTexture(int texName) { 75 Looper looper; 76 if ((looper = Looper.myLooper()) != null) { 77 mEventHandler = new EventHandler(looper); 78 } else if ((looper = Looper.getMainLooper()) != null) { 79 mEventHandler = new EventHandler(looper); 80 } else { 81 mEventHandler = null; 82 } 83 nativeInit(texName, new WeakReference<SurfaceTexture>(this)); 84 } 85 86 /** 87 * Register a callback to be invoked when a new image frame becomes available to the 88 * SurfaceTexture. Note that this callback may be called on an arbitrary thread, so it is not 89 * safe to call {@link #updateTexImage} without first binding the OpenGL ES context to the 90 * thread invoking the callback. 91 */ 92 public void setOnFrameAvailableListener(OnFrameAvailableListener l) { 93 mOnFrameAvailableListener = l; 94 } 95 96 /** 97 * Update the texture image to the most recent frame from the image stream. This may only be 98 * called while the OpenGL ES context that owns the texture is bound to the thread. It will 99 * implicitly bind its texture to the GL_TEXTURE_EXTERNAL_OES texture target. 100 */ 101 public void updateTexImage() { 102 nativeUpdateTexImage(); 103 } 104 105 /** 106 * Retrieve the 4x4 texture coordinate transform matrix associated with the texture image set by 107 * the most recent call to updateTexImage. 108 * 109 * This transform matrix maps 2D homogeneous texture coordinates of the form (s, t, 0, 1) with s 110 * and t in the inclusive range [0, 1] to the texture coordinate that should be used to sample 111 * that location from the texture. Sampling the texture outside of the range of this transform 112 * is undefined. 113 * 114 * The matrix is stored in column-major order so that it may be passed directly to OpenGL ES via 115 * the glLoadMatrixf or glUniformMatrix4fv functions. 116 * 117 * @param mtx the array into which the 4x4 matrix will be stored. The array must have exactly 118 * 16 elements. 119 */ 120 public void getTransformMatrix(float[] mtx) { 121 if (mtx.length != 16) { 122 throw new IllegalArgumentException(); 123 } 124 nativeGetTransformMatrix(mtx); 125 } 126 127 protected void finalize() throws Throwable { 128 try { 129 nativeFinalize(); 130 } finally { 131 super.finalize(); 132 } 133 } 134 135 private class EventHandler extends Handler { 136 public EventHandler(Looper looper) { 137 super(looper); 138 } 139 140 @Override 141 public void handleMessage(Message msg) { 142 if (mOnFrameAvailableListener != null) { 143 mOnFrameAvailableListener.onFrameAvailable(SurfaceTexture.this); 144 } 145 return; 146 } 147 } 148 149 private static void postEventFromNative(Object selfRef) { 150 WeakReference weakSelf = (WeakReference)selfRef; 151 SurfaceTexture st = (SurfaceTexture)weakSelf.get(); 152 if (st == null) { 153 return; 154 } 155 156 if (st.mEventHandler != null) { 157 Message m = st.mEventHandler.obtainMessage(); 158 st.mEventHandler.sendMessage(m); 159 } 160 } 161 162 private native void nativeInit(int texName, Object weakSelf); 163 private native void nativeFinalize(); 164 private native void nativeGetTransformMatrix(float[] mtx); 165 private native void nativeUpdateTexImage(); 166 167 /* 168 * We use a class initializer to allow the native code to cache some 169 * field offsets. 170 */ 171 private static native void nativeClassInit(); 172 static { nativeClassInit(); } 173} 174