13131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian/* 23131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian * Copyright (C) 2018 The Android Open Source Project 33131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian * 43131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian * Licensed under the Apache License, Version 2.0 (the "License"); 53131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian * you may not use this file except in compliance with the License. 63131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian * You may obtain a copy of the License at 73131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian * 83131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian * http://www.apache.org/licenses/LICENSE-2.0 93131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian * 103131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian * Unless required by applicable law or agreed to in writing, software 113131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian * distributed under the License is distributed on an "AS IS" BASIS, 123131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 133131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian * See the License for the specific language governing permissions and 143131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian * limitations under the License. 153131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian */ 163131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian 173131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian/** 183131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian * @addtogroup SurfaceTexture 193131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian * @{ 203131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian */ 213131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian 223131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian/** 233131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian * @file surface_texture.h 243131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian */ 253131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian 263131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian#ifndef ANDROID_NATIVE_SURFACE_TEXTURE_H 273131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian#define ANDROID_NATIVE_SURFACE_TEXTURE_H 283131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian 293131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian/****************************************************************** 303131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian * 313131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian * IMPORTANT NOTICE: 323131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian * 333131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian * This file is part of Android's set of stable system headers 343131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian * exposed by the Android NDK (Native Development Kit). 353131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian * 363131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian * Third-party source AND binary code relies on the definitions 373131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian * here to be FROZEN ON ALL UPCOMING PLATFORM RELEASES. 383131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian * 393131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian * - DO NOT MODIFY ENUMS (EXCEPT IF YOU ADD NEW 32-BIT VALUES) 403131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian * - DO NOT MODIFY CONSTANTS OR FUNCTIONAL MACROS 413131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian * - DO NOT CHANGE THE SIGNATURE OF FUNCTIONS IN ANY WAY 423131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian * - DO NOT CHANGE THE LAYOUT OR SIZE OF STRUCTURES 433131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian */ 443131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian 453131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian#include <stdint.h> 463131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian 473131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian#include <android/native_window.h> 483131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian 493131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian__BEGIN_DECLS 503131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian 513131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopianstruct ASurfaceTexture; 523131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian 533131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian/** 543131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian * {@link ASurfaceTexture} is an opaque type to manage SurfaceTexture from native code 553131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian * 563131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian * {@link ASurfaceTexture} can be obtained from an android.graphics.SurfaceTexture object using 573131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian * ASurfaceTexture_fromSurfaceTexture(). 583131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian */ 593131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopiantypedef struct ASurfaceTexture ASurfaceTexture; 603131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian 613131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian/** 623131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian * Release the reference to the native ASurfaceTexture acquired with 633131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian * ASurfaceTexture_fromSurfaceTexture(). 643131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian * Failing to do so will result in leaked memory and graphic resources. 653131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian * \param st A ASurfaceTexture reference acquired with ASurfaceTexture_fromSurfaceTexture() 663131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian */ 673131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopianvoid ASurfaceTexture_release(ASurfaceTexture* st); 683131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian 693131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian/** 703131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian * Returns a reference to an ANativeWindow (i.e. the Producer) for this SurfaceTexture. 713131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian * This is equivalent to Java's: Surface sur = new Surface(surfaceTexture); 723131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian * 733131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian * \param st A ASurfaceTexture reference acquired with ASurfaceTexture_fromSurfaceTexture() 743131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian * @return A reference to an ANativeWindow. This reference MUST BE released when no longer needed 753131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian * using ANativeWindow_release(). Failing to do so will result in leaked resources. nullptr is 763131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian * returned if \st is null or if it's not an instance of android.graphics.SurfaceTexture 773131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian */ 783131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias AgopianANativeWindow* ASurfaceTexture_acquireANativeWindow(ASurfaceTexture* st); 793131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian 803131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian/** 813131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian * Attach the SurfaceTexture to the OpenGL ES context that is current on the calling thread. A 823131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian * new OpenGL ES texture object is created and populated with the SurfaceTexture image frame 833131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian * that was current at the time of the last call to {@link #detachFromGLContext}. This new 843131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian * texture is bound to the GL_TEXTURE_EXTERNAL_OES texture target. 853131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian * 863131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian * This can be used to access the SurfaceTexture image contents from multiple OpenGL ES 873131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian * contexts. Note, however, that the image contents are only accessible from one OpenGL ES 883131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian * context at a time. 893131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian * 903131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian * \param st A ASurfaceTexture reference acquired with ASurfaceTexture_fromSurfaceTexture() 913131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian * \param texName The name of the OpenGL ES texture that will be created. This texture name 923131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian * must be unusued in the OpenGL ES context that is current on the calling thread. 933131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian * \return 0 on success, negative posix error code otherwise (see <errno.h>) 943131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian */ 953131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopianint ASurfaceTexture_attachToGLContext(ASurfaceTexture* st, uint32_t texName); 963131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian 973131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian/** 983131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian * Detach the SurfaceTexture from the OpenGL ES context that owns the OpenGL ES texture object. 993131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian * This call must be made with the OpenGL ES context current on the calling thread. The OpenGL 1003131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian * ES texture object will be deleted as a result of this call. After calling this method all 1013131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian * calls to {@link #updateTexImage} will fail until a successful call to {@link #attachToGLContext} 1023131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian * is made. 1033131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian * 1043131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian * This can be used to access the SurfaceTexture image contents from multiple OpenGL ES 1053131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian * contexts. Note, however, that the image contents are only accessible from one OpenGL ES 1063131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian * context at a time. 1073131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian * 1083131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian * \param st A ASurfaceTexture reference acquired with ASurfaceTexture_fromSurfaceTexture() 1093131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian * \return 0 on success, negative posix error code otherwise (see <errno.h>) 1103131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian */ 1113131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopianint ASurfaceTexture_detachFromGLContext(ASurfaceTexture* st); 1123131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian 1133131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian/** 1143131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian * Update the texture image to the most recent frame from the image stream. This may only be 1153131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian * called while the OpenGL ES context that owns the texture is current on the calling thread. 1163131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian * It will implicitly bind its texture to the GL_TEXTURE_EXTERNAL_OES texture target. 1173131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian * 1183131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian * \param st A ASurfaceTexture reference acquired with ASurfaceTexture_fromSurfaceTexture() 1193131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian * \return 0 on success, negative posix error code otherwise (see <errno.h>) 1203131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian */ 1213131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopianint ASurfaceTexture_updateTexImage(ASurfaceTexture* st); 1223131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian 1233131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian/** 1243131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian * Retrieve the 4x4 texture coordinate transform matrix associated with the texture image set by 1253131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian * the most recent call to updateTexImage. 1263131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian * 1273131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian * This transform matrix maps 2D homogeneous texture coordinates of the form (s, t, 0, 1) with s 1283131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian * and t in the inclusive range [0, 1] to the texture coordinate that should be used to sample 1293131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian * that location from the texture. Sampling the texture outside of the range of this transform 1303131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian * is undefined. 1313131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian * 1323131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian * The matrix is stored in column-major order so that it may be passed directly to OpenGL ES via 1333131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian * the glLoadMatrixf or glUniformMatrix4fv functions. 1343131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian * 1353131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian * \param st A ASurfaceTexture reference acquired with ASurfaceTexture_fromSurfaceTexture() 1363131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian * \param mtx the array into which the 4x4 matrix will be stored. The array must have exactly 1373131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian * 16 elements. 1383131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian */ 1393131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopianvoid ASurfaceTexture_getTransformMatrix(ASurfaceTexture* st, float mtx[16]); 1403131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian 1413131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian/** 1423131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian * Retrieve the timestamp associated with the texture image set by the most recent call to 1433131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian * updateTexImage. 1443131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian * 1453131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian * This timestamp is in nanoseconds, and is normally monotonically increasing. The timestamp 1463131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian * should be unaffected by time-of-day adjustments, and for a camera should be strictly 1473131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian * monotonic but for a MediaPlayer may be reset when the position is set. The 1483131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian * specific meaning and zero point of the timestamp depends on the source providing images to 1493131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian * the SurfaceTexture. Unless otherwise specified by the image source, timestamps cannot 1503131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian * generally be compared across SurfaceTexture instances, or across multiple program 1513131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian * invocations. It is mostly useful for determining time offsets between subsequent frames. 1523131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian * 1533131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian * For EGL/Vulkan producers, this timestamp is the desired present time set with the 1543131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian * EGL_ANDROID_presentation_time or VK_GOOGLE_display_timing extensions 1553131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian * 1563131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian * \param st A ASurfaceTexture reference acquired with ASurfaceTexture_fromSurfaceTexture() 1573131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian */ 1583131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopianint64_t ASurfaceTexture_getTimestamp(ASurfaceTexture* st); 1593131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian 1603131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian__END_DECLS 1613131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian 1623131a024c9f526a2cc468d9cece9e5beac5fdc37Mathias Agopian#endif /* ANDROID_NATIVE_SURFACE_TEXTURE_H */ 163