SurfaceTexture.java revision 376590d668e22a918439877b55faf075427b13f3
16714efc5e0c52953b65e774de0003e22377e7d39Jamie Gennis/* 26714efc5e0c52953b65e774de0003e22377e7d39Jamie Gennis * Copyright (C) 2010 The Android Open Source Project 36714efc5e0c52953b65e774de0003e22377e7d39Jamie Gennis * 46714efc5e0c52953b65e774de0003e22377e7d39Jamie Gennis * Licensed under the Apache License, Version 2.0 (the "License"); 56714efc5e0c52953b65e774de0003e22377e7d39Jamie Gennis * you may not use this file except in compliance with the License. 66714efc5e0c52953b65e774de0003e22377e7d39Jamie Gennis * You may obtain a copy of the License at 76714efc5e0c52953b65e774de0003e22377e7d39Jamie Gennis * 86714efc5e0c52953b65e774de0003e22377e7d39Jamie Gennis * http://www.apache.org/licenses/LICENSE-2.0 96714efc5e0c52953b65e774de0003e22377e7d39Jamie Gennis * 106714efc5e0c52953b65e774de0003e22377e7d39Jamie Gennis * Unless required by applicable law or agreed to in writing, software 116714efc5e0c52953b65e774de0003e22377e7d39Jamie Gennis * distributed under the License is distributed on an "AS IS" BASIS, 126714efc5e0c52953b65e774de0003e22377e7d39Jamie Gennis * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 136714efc5e0c52953b65e774de0003e22377e7d39Jamie Gennis * See the License for the specific language governing permissions and 146714efc5e0c52953b65e774de0003e22377e7d39Jamie Gennis * limitations under the License. 156714efc5e0c52953b65e774de0003e22377e7d39Jamie Gennis */ 166714efc5e0c52953b65e774de0003e22377e7d39Jamie Gennis 176714efc5e0c52953b65e774de0003e22377e7d39Jamie Gennispackage android.graphics; 186714efc5e0c52953b65e774de0003e22377e7d39Jamie Gennis 19376590d668e22a918439877b55faf075427b13f3Jamie Gennisimport java.lang.ref.WeakReference; 20376590d668e22a918439877b55faf075427b13f3Jamie Gennisimport android.os.Handler; 21376590d668e22a918439877b55faf075427b13f3Jamie Gennisimport android.os.Looper; 22376590d668e22a918439877b55faf075427b13f3Jamie Gennisimport android.os.Message; 23376590d668e22a918439877b55faf075427b13f3Jamie Gennis 246714efc5e0c52953b65e774de0003e22377e7d39Jamie Gennis/** 256714efc5e0c52953b65e774de0003e22377e7d39Jamie Gennis * Captures frames from an image stream as an OpenGL ES texture. 266714efc5e0c52953b65e774de0003e22377e7d39Jamie Gennis * 276714efc5e0c52953b65e774de0003e22377e7d39Jamie Gennis * <p>The image stream may come from either video playback or camera preview. A SurfaceTexture may 286714efc5e0c52953b65e774de0003e22377e7d39Jamie Gennis * be used in place of a SurfaceHolder when specifying the output destination of a MediaPlayer or 296714efc5e0c52953b65e774de0003e22377e7d39Jamie Gennis * Camera object. This will cause all the frames from that image stream to be sent to the 306714efc5e0c52953b65e774de0003e22377e7d39Jamie Gennis * SurfaceTexture object rather than to the device's display. When {@link #updateTexImage} is 316714efc5e0c52953b65e774de0003e22377e7d39Jamie Gennis * called, the contents of the texture object specified when the SurfaceTexture was created is 326714efc5e0c52953b65e774de0003e22377e7d39Jamie Gennis * updated to contain the most recent image from the image stream. This may cause some frames of 336714efc5e0c52953b65e774de0003e22377e7d39Jamie Gennis * the stream to be skipped. 346714efc5e0c52953b65e774de0003e22377e7d39Jamie Gennis * 356714efc5e0c52953b65e774de0003e22377e7d39Jamie Gennis * <p>The texture object uses the GL_TEXTURE_EXTERNAL_OES texture target, which is defined by the 366714efc5e0c52953b65e774de0003e22377e7d39Jamie Gennis * OES_EGL_image_external OpenGL ES extension. This limits how the texture may be used. 376714efc5e0c52953b65e774de0003e22377e7d39Jamie Gennis */ 386714efc5e0c52953b65e774de0003e22377e7d39Jamie Gennispublic class SurfaceTexture { 396714efc5e0c52953b65e774de0003e22377e7d39Jamie Gennis 40376590d668e22a918439877b55faf075427b13f3Jamie Gennis private EventHandler mEventHandler; 41376590d668e22a918439877b55faf075427b13f3Jamie Gennis private OnFrameAvailableListener mOnFrameAvailableListener; 42376590d668e22a918439877b55faf075427b13f3Jamie Gennis 436714efc5e0c52953b65e774de0003e22377e7d39Jamie Gennis @SuppressWarnings("unused") 446714efc5e0c52953b65e774de0003e22377e7d39Jamie Gennis private int mSurfaceTexture; 456714efc5e0c52953b65e774de0003e22377e7d39Jamie Gennis 466714efc5e0c52953b65e774de0003e22377e7d39Jamie Gennis /** 476714efc5e0c52953b65e774de0003e22377e7d39Jamie Gennis * Callback interface for being notified that a new stream frame is available. 486714efc5e0c52953b65e774de0003e22377e7d39Jamie Gennis */ 496714efc5e0c52953b65e774de0003e22377e7d39Jamie Gennis public interface OnFrameAvailableListener { 506714efc5e0c52953b65e774de0003e22377e7d39Jamie Gennis void onFrameAvailable(SurfaceTexture surfaceTexture); 516714efc5e0c52953b65e774de0003e22377e7d39Jamie Gennis } 526714efc5e0c52953b65e774de0003e22377e7d39Jamie Gennis 536714efc5e0c52953b65e774de0003e22377e7d39Jamie Gennis /** 546714efc5e0c52953b65e774de0003e22377e7d39Jamie Gennis * Exception thrown when a surface couldn't be created or resized 556714efc5e0c52953b65e774de0003e22377e7d39Jamie Gennis */ 566714efc5e0c52953b65e774de0003e22377e7d39Jamie Gennis public static class OutOfResourcesException extends Exception { 576714efc5e0c52953b65e774de0003e22377e7d39Jamie Gennis public OutOfResourcesException() { 586714efc5e0c52953b65e774de0003e22377e7d39Jamie Gennis } 596714efc5e0c52953b65e774de0003e22377e7d39Jamie Gennis public OutOfResourcesException(String name) { 606714efc5e0c52953b65e774de0003e22377e7d39Jamie Gennis super(name); 616714efc5e0c52953b65e774de0003e22377e7d39Jamie Gennis } 626714efc5e0c52953b65e774de0003e22377e7d39Jamie Gennis } 636714efc5e0c52953b65e774de0003e22377e7d39Jamie Gennis 646714efc5e0c52953b65e774de0003e22377e7d39Jamie Gennis /** 656714efc5e0c52953b65e774de0003e22377e7d39Jamie Gennis * Construct a new SurfaceTexture to stream images to a given OpenGL texture. 666714efc5e0c52953b65e774de0003e22377e7d39Jamie Gennis * 676714efc5e0c52953b65e774de0003e22377e7d39Jamie Gennis * @param texName the OpenGL texture object name (e.g. generated via glGenTextures) 686714efc5e0c52953b65e774de0003e22377e7d39Jamie Gennis */ 696714efc5e0c52953b65e774de0003e22377e7d39Jamie Gennis public SurfaceTexture(int texName) { 70376590d668e22a918439877b55faf075427b13f3Jamie Gennis Looper looper; 71376590d668e22a918439877b55faf075427b13f3Jamie Gennis if ((looper = Looper.myLooper()) != null) { 72376590d668e22a918439877b55faf075427b13f3Jamie Gennis mEventHandler = new EventHandler(looper); 73376590d668e22a918439877b55faf075427b13f3Jamie Gennis } else if ((looper = Looper.getMainLooper()) != null) { 74376590d668e22a918439877b55faf075427b13f3Jamie Gennis mEventHandler = new EventHandler(looper); 75376590d668e22a918439877b55faf075427b13f3Jamie Gennis } else { 76376590d668e22a918439877b55faf075427b13f3Jamie Gennis mEventHandler = null; 77376590d668e22a918439877b55faf075427b13f3Jamie Gennis } 78376590d668e22a918439877b55faf075427b13f3Jamie Gennis nativeInit(texName, new WeakReference<SurfaceTexture>(this)); 796714efc5e0c52953b65e774de0003e22377e7d39Jamie Gennis } 806714efc5e0c52953b65e774de0003e22377e7d39Jamie Gennis 816714efc5e0c52953b65e774de0003e22377e7d39Jamie Gennis /** 826714efc5e0c52953b65e774de0003e22377e7d39Jamie Gennis * Register a callback to be invoked when a new image frame becomes available to the 836714efc5e0c52953b65e774de0003e22377e7d39Jamie Gennis * SurfaceTexture. Note that this callback may be called on an arbitrary thread, so it is not 846714efc5e0c52953b65e774de0003e22377e7d39Jamie Gennis * safe to call {@link #updateTexImage} without first binding the OpenGL ES context to the 856714efc5e0c52953b65e774de0003e22377e7d39Jamie Gennis * thread invoking the callback. 866714efc5e0c52953b65e774de0003e22377e7d39Jamie Gennis */ 876714efc5e0c52953b65e774de0003e22377e7d39Jamie Gennis public void setOnFrameAvailableListener(OnFrameAvailableListener l) { 88376590d668e22a918439877b55faf075427b13f3Jamie Gennis mOnFrameAvailableListener = l; 896714efc5e0c52953b65e774de0003e22377e7d39Jamie Gennis } 906714efc5e0c52953b65e774de0003e22377e7d39Jamie Gennis 916714efc5e0c52953b65e774de0003e22377e7d39Jamie Gennis /** 926714efc5e0c52953b65e774de0003e22377e7d39Jamie Gennis * Update the texture image to the most recent frame from the image stream. This may only be 936714efc5e0c52953b65e774de0003e22377e7d39Jamie Gennis * called while the OpenGL ES context that owns the texture is bound to the thread. It will 946714efc5e0c52953b65e774de0003e22377e7d39Jamie Gennis * implicitly bind its texture to the GL_TEXTURE_EXTERNAL_OES texture target. 956714efc5e0c52953b65e774de0003e22377e7d39Jamie Gennis */ 96376590d668e22a918439877b55faf075427b13f3Jamie Gennis public void updateTexImage() { 97376590d668e22a918439877b55faf075427b13f3Jamie Gennis nativeUpdateTexImage(); 98376590d668e22a918439877b55faf075427b13f3Jamie Gennis } 99b0ba48c95ea8768a051100c5adb4c906caa1e080Jamie Gennis 100b0ba48c95ea8768a051100c5adb4c906caa1e080Jamie Gennis /** 101b0ba48c95ea8768a051100c5adb4c906caa1e080Jamie Gennis * Retrieve the 4x4 texture coordinate transform matrix associated with the texture image set by 102b0ba48c95ea8768a051100c5adb4c906caa1e080Jamie Gennis * the most recent call to updateTexImage. 103b0ba48c95ea8768a051100c5adb4c906caa1e080Jamie Gennis * 104b0ba48c95ea8768a051100c5adb4c906caa1e080Jamie Gennis * This transform matrix maps 2D homogeneous texture coordinates of the form (s, t, 0, 1) with s 105b0ba48c95ea8768a051100c5adb4c906caa1e080Jamie Gennis * and t in the inclusive range [0, 1] to the texture coordinate that should be used to sample 106b0ba48c95ea8768a051100c5adb4c906caa1e080Jamie Gennis * that location from the texture. Sampling the texture outside of the range of this transform 107b0ba48c95ea8768a051100c5adb4c906caa1e080Jamie Gennis * is undefined. 108b0ba48c95ea8768a051100c5adb4c906caa1e080Jamie Gennis * 109b0ba48c95ea8768a051100c5adb4c906caa1e080Jamie Gennis * The matrix is stored in column-major order so that it may be passed directly to OpenGL ES via 110b0ba48c95ea8768a051100c5adb4c906caa1e080Jamie Gennis * the glLoadMatrixf or glUniformMatrix4fv functions. 111b0ba48c95ea8768a051100c5adb4c906caa1e080Jamie Gennis * 112b0ba48c95ea8768a051100c5adb4c906caa1e080Jamie Gennis * @param mtx the array into which the 4x4 matrix will be stored. The array must have exactly 113b0ba48c95ea8768a051100c5adb4c906caa1e080Jamie Gennis * 16 elements. 114b0ba48c95ea8768a051100c5adb4c906caa1e080Jamie Gennis */ 115b0ba48c95ea8768a051100c5adb4c906caa1e080Jamie Gennis public void getTransformMatrix(float[] mtx) { 116b0ba48c95ea8768a051100c5adb4c906caa1e080Jamie Gennis if (mtx.length != 16) { 117b0ba48c95ea8768a051100c5adb4c906caa1e080Jamie Gennis throw new IllegalArgumentException(); 118b0ba48c95ea8768a051100c5adb4c906caa1e080Jamie Gennis } 119376590d668e22a918439877b55faf075427b13f3Jamie Gennis nativeGetTransformMatrix(mtx); 120b0ba48c95ea8768a051100c5adb4c906caa1e080Jamie Gennis } 121b0ba48c95ea8768a051100c5adb4c906caa1e080Jamie Gennis 122376590d668e22a918439877b55faf075427b13f3Jamie Gennis protected void finalize() throws Throwable { 123376590d668e22a918439877b55faf075427b13f3Jamie Gennis try { 124376590d668e22a918439877b55faf075427b13f3Jamie Gennis nativeFinalize(); 125376590d668e22a918439877b55faf075427b13f3Jamie Gennis } finally { 126376590d668e22a918439877b55faf075427b13f3Jamie Gennis super.finalize(); 127376590d668e22a918439877b55faf075427b13f3Jamie Gennis } 128376590d668e22a918439877b55faf075427b13f3Jamie Gennis } 129376590d668e22a918439877b55faf075427b13f3Jamie Gennis 130376590d668e22a918439877b55faf075427b13f3Jamie Gennis private class EventHandler extends Handler { 131376590d668e22a918439877b55faf075427b13f3Jamie Gennis public EventHandler(Looper looper) { 132376590d668e22a918439877b55faf075427b13f3Jamie Gennis super(looper); 133376590d668e22a918439877b55faf075427b13f3Jamie Gennis } 134376590d668e22a918439877b55faf075427b13f3Jamie Gennis 135376590d668e22a918439877b55faf075427b13f3Jamie Gennis @Override 136376590d668e22a918439877b55faf075427b13f3Jamie Gennis public void handleMessage(Message msg) { 137376590d668e22a918439877b55faf075427b13f3Jamie Gennis if (mOnFrameAvailableListener != null) { 138376590d668e22a918439877b55faf075427b13f3Jamie Gennis mOnFrameAvailableListener.onFrameAvailable(SurfaceTexture.this); 139376590d668e22a918439877b55faf075427b13f3Jamie Gennis } 140376590d668e22a918439877b55faf075427b13f3Jamie Gennis return; 141376590d668e22a918439877b55faf075427b13f3Jamie Gennis } 142376590d668e22a918439877b55faf075427b13f3Jamie Gennis } 143376590d668e22a918439877b55faf075427b13f3Jamie Gennis 144376590d668e22a918439877b55faf075427b13f3Jamie Gennis private static void postEventFromNative(Object selfRef) { 145376590d668e22a918439877b55faf075427b13f3Jamie Gennis WeakReference weakSelf = (WeakReference)selfRef; 146376590d668e22a918439877b55faf075427b13f3Jamie Gennis SurfaceTexture st = (SurfaceTexture)weakSelf.get(); 147376590d668e22a918439877b55faf075427b13f3Jamie Gennis if (st == null) { 148376590d668e22a918439877b55faf075427b13f3Jamie Gennis return; 149376590d668e22a918439877b55faf075427b13f3Jamie Gennis } 150376590d668e22a918439877b55faf075427b13f3Jamie Gennis 151376590d668e22a918439877b55faf075427b13f3Jamie Gennis if (st.mEventHandler != null) { 152376590d668e22a918439877b55faf075427b13f3Jamie Gennis Message m = st.mEventHandler.obtainMessage(); 153376590d668e22a918439877b55faf075427b13f3Jamie Gennis st.mEventHandler.sendMessage(m); 154376590d668e22a918439877b55faf075427b13f3Jamie Gennis } 155376590d668e22a918439877b55faf075427b13f3Jamie Gennis } 156b0ba48c95ea8768a051100c5adb4c906caa1e080Jamie Gennis 157376590d668e22a918439877b55faf075427b13f3Jamie Gennis private native void nativeInit(int texName, Object weakSelf); 158376590d668e22a918439877b55faf075427b13f3Jamie Gennis private native void nativeFinalize(); 159376590d668e22a918439877b55faf075427b13f3Jamie Gennis private native void nativeGetTransformMatrix(float[] mtx); 160376590d668e22a918439877b55faf075427b13f3Jamie Gennis private native void nativeUpdateTexImage(); 1616714efc5e0c52953b65e774de0003e22377e7d39Jamie Gennis 1626714efc5e0c52953b65e774de0003e22377e7d39Jamie Gennis /* 1636714efc5e0c52953b65e774de0003e22377e7d39Jamie Gennis * We use a class initializer to allow the native code to cache some 1646714efc5e0c52953b65e774de0003e22377e7d39Jamie Gennis * field offsets. 1656714efc5e0c52953b65e774de0003e22377e7d39Jamie Gennis */ 1666714efc5e0c52953b65e774de0003e22377e7d39Jamie Gennis private static native void nativeClassInit(); 1676714efc5e0c52953b65e774de0003e22377e7d39Jamie Gennis static { nativeClassInit(); } 1686714efc5e0c52953b65e774de0003e22377e7d39Jamie Gennis} 169