SurfaceTexture.java revision b0ba48c95ea8768a051100c5adb4c906caa1e080 
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
19/**
20 * Captures frames from an image stream as an OpenGL ES texture.
21 *
22 * <p>The image stream may come from either video playback or camera preview.  A SurfaceTexture may
23 * be used in place of a SurfaceHolder when specifying the output destination of a MediaPlayer or
24 * Camera object.  This will cause all the frames from that image stream to be sent to the
25 * SurfaceTexture object rather than to the device's display.  When {@link #updateTexImage} is
26 * called, the contents of the texture object specified when the SurfaceTexture was created is
27 * updated to contain the most recent image from the image stream.  This may cause some frames of
28 * the stream to be skipped.
29 *
30 * <p>The texture object uses the GL_TEXTURE_EXTERNAL_OES texture target, which is defined by the
31 * OES_EGL_image_external OpenGL ES extension.  This limits how the texture may be used.
32 */
33public class SurfaceTexture {
34
35    @SuppressWarnings("unused")
36    private int mSurfaceTexture;
37
38    /**
39     * Callback interface for being notified that a new stream frame is available.
40     */
41    public interface OnFrameAvailableListener {
42        void onFrameAvailable(SurfaceTexture surfaceTexture);
43    }
44
45    /**
46     * Exception thrown when a surface couldn't be created or resized
47     */
48    public static class OutOfResourcesException extends Exception {
49        public OutOfResourcesException() {
50        }
51        public OutOfResourcesException(String name) {
52            super(name);
53        }
54    }
55
56    /**
57     * Construct a new SurfaceTexture to stream images to a given OpenGL texture.
58     *
59     * @param texName the OpenGL texture object name (e.g. generated via glGenTextures)
60     */
61    public SurfaceTexture(int texName) {
62        init(texName);
63    }
64
65    /**
66     * Register a callback to be invoked when a new image frame becomes available to the
67     * SurfaceTexture.  Note that this callback may be called on an arbitrary thread, so it is not
68     * safe to call {@link #updateTexImage} without first binding the OpenGL ES context to the
69     * thread invoking the callback.
70     */
71    public void setOnFrameAvailableListener(OnFrameAvailableListener l) {
72        // TODO: Implement this!
73    }
74
75    /**
76     * Update the texture image to the most recent frame from the image stream.  This may only be
77     * called while the OpenGL ES context that owns the texture is bound to the thread.  It will
78     * implicitly bind its texture to the GL_TEXTURE_EXTERNAL_OES texture target.
79     */
80    public native void updateTexImage();
81
82
83    /**
84     * Retrieve the 4x4 texture coordinate transform matrix associated with the texture image set by
85     * the most recent call to updateTexImage.
86     *
87     * This transform matrix maps 2D homogeneous texture coordinates of the form (s, t, 0, 1) with s
88     * and t in the inclusive range [0, 1] to the texture coordinate that should be used to sample
89     * that location from the texture.  Sampling the texture outside of the range of this transform
90     * is undefined.
91     *
92     * The matrix is stored in column-major order so that it may be passed directly to OpenGL ES via
93     * the glLoadMatrixf or glUniformMatrix4fv functions.
94     *
95     * @param mtx the array into which the 4x4 matrix will be stored.  The array must have exactly
96     *     16 elements.
97     */
98    public void getTransformMatrix(float[] mtx) {
99        if (mtx.length != 16) {
100            throw new IllegalArgumentException();
101        }
102        getTransformMatrixImpl(mtx);
103    }
104
105    private native void getTransformMatrixImpl(float[] mtx);
106
107    private native void init(int texName);
108
109    /*
110     * We use a class initializer to allow the native code to cache some
111     * field offsets.
112     */
113    private static native void nativeClassInit();
114    static { nativeClassInit(); }
115}
116