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 #include <sys/cdefs.h> 47 48 #include <android/native_window.h> 49 50 __BEGIN_DECLS 51 52 struct ASurfaceTexture; 53 54 /** 55 * {@link ASurfaceTexture} is an opaque type to manage SurfaceTexture from native code 56 * 57 * {@link ASurfaceTexture} can be obtained from an android.graphics.SurfaceTexture object using 58 * ASurfaceTexture_fromSurfaceTexture(). 59 */ 60 typedef struct ASurfaceTexture ASurfaceTexture; 61 62 #if __ANDROID_API__ >= 28 63 64 /** 65 * Release the reference to the native ASurfaceTexture acquired with 66 * ASurfaceTexture_fromSurfaceTexture(). 67 * Failing to do so will result in leaked memory and graphic resources. 68 * 69 * Available since API level 28. 70 * 71 * \param st A ASurfaceTexture reference acquired with ASurfaceTexture_fromSurfaceTexture() 72 */ 73 void ASurfaceTexture_release(ASurfaceTexture* st) __INTRODUCED_IN(28); 74 75 /** 76 * Returns a reference to an ANativeWindow (i.e. the Producer) for this SurfaceTexture. 77 * This is equivalent to Java's: Surface sur = new Surface(surfaceTexture); 78 * 79 * Available since API level 28. 80 * 81 * \param st A ASurfaceTexture reference acquired with ASurfaceTexture_fromSurfaceTexture() 82 * @return A reference to an ANativeWindow. This reference MUST BE released when no longer needed 83 * using ANativeWindow_release(). Failing to do so will result in leaked resources. nullptr is 84 * returned if \p st is null or if it's not an instance of android.graphics.SurfaceTexture 85 */ 86 ANativeWindow* ASurfaceTexture_acquireANativeWindow(ASurfaceTexture* st) __INTRODUCED_IN(28); 87 88 /** 89 * Attach the SurfaceTexture to the OpenGL ES context that is current on the calling thread. A 90 * new OpenGL ES texture object is created and populated with the SurfaceTexture image frame 91 * that was current at the time of the last call to {@link #detachFromGLContext}. This new 92 * texture is bound to the GL_TEXTURE_EXTERNAL_OES texture target. 93 * 94 * This can be used to access the SurfaceTexture image contents from multiple OpenGL ES 95 * contexts. Note, however, that the image contents are only accessible from one OpenGL ES 96 * context at a time. 97 * 98 * Available since API level 28. 99 * 100 * \param st A ASurfaceTexture reference acquired with ASurfaceTexture_fromSurfaceTexture() 101 * \param texName The name of the OpenGL ES texture that will be created. This texture name 102 * must be unusued in the OpenGL ES context that is current on the calling thread. 103 * \return 0 on success, negative posix error code otherwise (see <errno.h>) 104 */ 105 int ASurfaceTexture_attachToGLContext(ASurfaceTexture* st, uint32_t texName) __INTRODUCED_IN(28); 106 107 /** 108 * Detach the SurfaceTexture from the OpenGL ES context that owns the OpenGL ES texture object. 109 * This call must be made with the OpenGL ES context current on the calling thread. The OpenGL 110 * ES texture object will be deleted as a result of this call. After calling this method all 111 * calls to {@link #updateTexImage} will fail until a successful call to {@link #attachToGLContext} 112 * is made. 113 * 114 * This can be used to access the SurfaceTexture image contents from multiple OpenGL ES 115 * contexts. Note, however, that the image contents are only accessible from one OpenGL ES 116 * context at a time. 117 * 118 * Available since API level 28. 119 * 120 * \param st A ASurfaceTexture reference acquired with ASurfaceTexture_fromSurfaceTexture() 121 * \return 0 on success, negative posix error code otherwise (see <errno.h>) 122 */ 123 int ASurfaceTexture_detachFromGLContext(ASurfaceTexture* st) __INTRODUCED_IN(28); 124 125 /** 126 * Update the texture image to the most recent frame from the image stream. This may only be 127 * called while the OpenGL ES context that owns the texture is current on the calling thread. 128 * It will implicitly bind its texture to the GL_TEXTURE_EXTERNAL_OES texture target. 129 * 130 * Available since API level 28. 131 * 132 * \param st A ASurfaceTexture reference acquired with ASurfaceTexture_fromSurfaceTexture() 133 * \return 0 on success, negative posix error code otherwise (see <errno.h>) 134 */ 135 int ASurfaceTexture_updateTexImage(ASurfaceTexture* st) __INTRODUCED_IN(28); 136 137 /** 138 * Retrieve the 4x4 texture coordinate transform matrix associated with the texture image set by 139 * the most recent call to updateTexImage. 140 * 141 * This transform matrix maps 2D homogeneous texture coordinates of the form (s, t, 0, 1) with s 142 * and t in the inclusive range [0, 1] to the texture coordinate that should be used to sample 143 * that location from the texture. Sampling the texture outside of the range of this transform 144 * is undefined. 145 * 146 * The matrix is stored in column-major order so that it may be passed directly to OpenGL ES via 147 * the glLoadMatrixf or glUniformMatrix4fv functions. 148 * 149 * Available since API level 28. 150 * 151 * \param st A ASurfaceTexture reference acquired with ASurfaceTexture_fromSurfaceTexture() 152 * \param mtx the array into which the 4x4 matrix will be stored. The array must have exactly 153 * 16 elements. 154 */ 155 void ASurfaceTexture_getTransformMatrix(ASurfaceTexture* st, float mtx[16]) __INTRODUCED_IN(28); 156 157 /** 158 * Retrieve the timestamp associated with the texture image set by the most recent call to 159 * updateTexImage. 160 * 161 * This timestamp is in nanoseconds, and is normally monotonically increasing. The timestamp 162 * should be unaffected by time-of-day adjustments, and for a camera should be strictly 163 * monotonic but for a MediaPlayer may be reset when the position is set. The 164 * specific meaning and zero point of the timestamp depends on the source providing images to 165 * the SurfaceTexture. Unless otherwise specified by the image source, timestamps cannot 166 * generally be compared across SurfaceTexture instances, or across multiple program 167 * invocations. It is mostly useful for determining time offsets between subsequent frames. 168 * 169 * For EGL/Vulkan producers, this timestamp is the desired present time set with the 170 * EGL_ANDROID_presentation_time or VK_GOOGLE_display_timing extensions 171 * 172 * Available since API level 28. 173 * 174 * \param st A ASurfaceTexture reference acquired with ASurfaceTexture_fromSurfaceTexture() 175 */ 176 int64_t ASurfaceTexture_getTimestamp(ASurfaceTexture* st) __INTRODUCED_IN(28); 177 178 #endif /* __ANDROID_API__ >= 28 */ 179 180 __END_DECLS 181 182 #endif /* ANDROID_NATIVE_SURFACE_TEXTURE_H */ 183