surface_texture.h revision 3131a024c9f526a2cc468d9cece9e5beac5fdc37 
1/*
2 * Copyright (C) 2018 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
17/**
18 * @addtogroup SurfaceTexture
19 * @{
20 */
21
22/**
23 * @file surface_texture.h
24 */
25
26#ifndef ANDROID_NATIVE_SURFACE_TEXTURE_H
27#define ANDROID_NATIVE_SURFACE_TEXTURE_H
28
29/******************************************************************
30 *
31 * IMPORTANT NOTICE:
32 *
33 *   This file is part of Android's set of stable system headers
34 *   exposed by the Android NDK (Native Development Kit).
35 *
36 *   Third-party source AND binary code relies on the definitions
37 *   here to be FROZEN ON ALL UPCOMING PLATFORM RELEASES.
38 *
39 *   - DO NOT MODIFY ENUMS (EXCEPT IF YOU ADD NEW 32-BIT VALUES)
40 *   - DO NOT MODIFY CONSTANTS OR FUNCTIONAL MACROS
41 *   - DO NOT CHANGE THE SIGNATURE OF FUNCTIONS IN ANY WAY
42 *   - DO NOT CHANGE THE LAYOUT OR SIZE OF STRUCTURES
43 */
44
45#include <stdint.h>
46
47#include <android/native_window.h>
48
49__BEGIN_DECLS
50
51struct ASurfaceTexture;
52
53/**
54 * {@link ASurfaceTexture} is an opaque type to manage SurfaceTexture from native code
55 *
56 * {@link ASurfaceTexture} can be obtained from an android.graphics.SurfaceTexture object using
57 * ASurfaceTexture_fromSurfaceTexture().
58 */
59typedef struct ASurfaceTexture ASurfaceTexture;
60
61/**
62 * Release the reference to the native ASurfaceTexture acquired with
63 * ASurfaceTexture_fromSurfaceTexture().
64 * Failing to do so will result in leaked memory and graphic resources.
65 * \param st A ASurfaceTexture reference acquired with ASurfaceTexture_fromSurfaceTexture()
66 */
67void ASurfaceTexture_release(ASurfaceTexture* st);
68
69/**
70 * Returns a reference to an ANativeWindow (i.e. the Producer) for this SurfaceTexture.
71 * This is equivalent to Java's: Surface sur = new Surface(surfaceTexture);
72 *
73 * \param st A ASurfaceTexture reference acquired with ASurfaceTexture_fromSurfaceTexture()
74 * @return A reference to an ANativeWindow. This reference MUST BE released when no longer needed
75 * using ANativeWindow_release(). Failing to do so will result in leaked resources. nullptr is
76 * returned if \st is null or if it's not an instance of android.graphics.SurfaceTexture
77 */
78ANativeWindow* ASurfaceTexture_acquireANativeWindow(ASurfaceTexture* st);
79
80/**
81 * Attach the SurfaceTexture to the OpenGL ES context that is current on the calling thread.  A
82 * new OpenGL ES texture object is created and populated with the SurfaceTexture image frame
83 * that was current at the time of the last call to {@link #detachFromGLContext}.  This new
84 * texture is bound to the GL_TEXTURE_EXTERNAL_OES texture target.
85 *
86 * This can be used to access the SurfaceTexture image contents from multiple OpenGL ES
87 * contexts.  Note, however, that the image contents are only accessible from one OpenGL ES
88 * context at a time.
89 *
90 * \param st A ASurfaceTexture reference acquired with ASurfaceTexture_fromSurfaceTexture()
91 * \param texName The name of the OpenGL ES texture that will be created.  This texture name
92 * must be unusued in the OpenGL ES context that is current on the calling thread.
93 * \return 0 on success, negative posix error code otherwise (see <errno.h>)
94 */
95int ASurfaceTexture_attachToGLContext(ASurfaceTexture* st, uint32_t texName);
96
97/**
98 * Detach the SurfaceTexture from the OpenGL ES context that owns the OpenGL ES texture object.
99 * This call must be made with the OpenGL ES context current on the calling thread.  The OpenGL
100 * ES texture object will be deleted as a result of this call.  After calling this method all
101 * calls to {@link #updateTexImage} will fail until a successful call to {@link #attachToGLContext}
102 * is made.
103 *
104 * This can be used to access the SurfaceTexture image contents from multiple OpenGL ES
105 * contexts.  Note, however, that the image contents are only accessible from one OpenGL ES
106 * context at a time.
107 *
108 * \param st A ASurfaceTexture reference acquired with ASurfaceTexture_fromSurfaceTexture()
109 * \return 0 on success, negative posix error code otherwise (see <errno.h>)
110 */
111int ASurfaceTexture_detachFromGLContext(ASurfaceTexture* st);
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 current on the calling thread.
116 * It will implicitly bind its texture to the GL_TEXTURE_EXTERNAL_OES texture target.
117 *
118 * \param st A ASurfaceTexture reference acquired with ASurfaceTexture_fromSurfaceTexture()
119 * \return 0 on success, negative posix error code otherwise (see <errno.h>)
120 */
121int ASurfaceTexture_updateTexImage(ASurfaceTexture* st);
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 st A ASurfaceTexture reference acquired with ASurfaceTexture_fromSurfaceTexture()
136 * \param mtx the array into which the 4x4 matrix will be stored.  The array must have exactly
137 *     16 elements.
138 */
139void ASurfaceTexture_getTransformMatrix(ASurfaceTexture* st, float mtx[16]);
140
141/**
142 * Retrieve the timestamp associated with the texture image set by the most recent call to
143 * updateTexImage.
144 *
145 * This timestamp is in nanoseconds, and is normally monotonically increasing. The timestamp
146 * should be unaffected by time-of-day adjustments, and for a camera should be strictly
147 * monotonic but for a MediaPlayer may be reset when the position is set.  The
148 * specific meaning and zero point of the timestamp depends on the source providing images to
149 * the SurfaceTexture. Unless otherwise specified by the image source, timestamps cannot
150 * generally be compared across SurfaceTexture instances, or across multiple program
151 * invocations. It is mostly useful for determining time offsets between subsequent frames.
152 *
153 * For EGL/Vulkan producers, this timestamp is the desired present time set with the
154 * EGL_ANDROID_presentation_time or VK_GOOGLE_display_timing extensions
155 *
156 * \param st A ASurfaceTexture reference acquired with ASurfaceTexture_fromSurfaceTexture()
157 */
158int64_t ASurfaceTexture_getTimestamp(ASurfaceTexture* st);
159
160__END_DECLS
161
162#endif /* ANDROID_NATIVE_SURFACE_TEXTURE_H */
163