SurfaceTexture.h revision b267579ba8dfe3f47d2a481c5a3c2254e3d565a1
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 17#ifndef ANDROID_GUI_SURFACETEXTURE_H 18#define ANDROID_GUI_SURFACETEXTURE_H 19 20#include <EGL/egl.h> 21#include <EGL/eglext.h> 22#include <GLES2/gl2.h> 23#include <GLES2/gl2ext.h> 24 25#include <gui/ISurfaceTexture.h> 26#include <gui/BufferQueue.h> 27 28#include <ui/GraphicBuffer.h> 29 30#include <utils/String8.h> 31#include <utils/Vector.h> 32#include <utils/threads.h> 33 34#define ANDROID_GRAPHICS_SURFACETEXTURE_JNI_ID "mSurfaceTexture" 35 36namespace android { 37// ---------------------------------------------------------------------------- 38 39 40class String8; 41 42class SurfaceTexture : public virtual RefBase { 43public: 44 // This typedef allows external code to continue referencing 45 // SurfaceTexture::FrameAvailableListener during refactoring 46 typedef BufferQueue::FrameAvailableListener FrameAvailableListener; 47 48 49 // SurfaceTexture constructs a new SurfaceTexture object. tex indicates the 50 // name of the OpenGL ES texture to which images are to be streamed. This 51 // texture name cannot be changed once the SurfaceTexture is created. 52 // allowSynchronousMode specifies whether or not synchronous mode can be 53 // enabled. texTarget specifies the OpenGL ES texture target to which the 54 // texture will be bound in updateTexImage. useFenceSync specifies whether 55 // fences should be used to synchronize access to buffers if that behavior 56 // is enabled at compile-time. A custom bufferQueue can be specified 57 // if behavior for queue/dequeue/connect etc needs to be customized. 58 // Otherwise a default BufferQueue will be created and used. 59 SurfaceTexture(GLuint tex, bool allowSynchronousMode = true, 60 GLenum texTarget = GL_TEXTURE_EXTERNAL_OES, bool useFenceSync = true, 61 const sp<BufferQueue> &bufferQueue = 0); 62 63 virtual ~SurfaceTexture(); 64 65 // updateTexImage sets the image contents of the target texture to that of 66 // the most recently queued buffer. 67 // 68 // This call may only be made while the OpenGL ES context to which the 69 // target texture belongs is bound to the calling thread. 70 status_t updateTexImage(); 71 72 // setBufferCountServer set the buffer count. If the client has requested 73 // a buffer count using setBufferCount, the server-buffer count will 74 // take effect once the client sets the count back to zero. 75 status_t setBufferCountServer(int bufferCount); 76 77 // getTransformMatrix retrieves the 4x4 texture coordinate transform matrix 78 // associated with the texture image set by the most recent call to 79 // updateTexImage. 80 // 81 // This transform matrix maps 2D homogeneous texture coordinates of the form 82 // (s, t, 0, 1) with s and t in the inclusive range [0, 1] to the texture 83 // coordinate that should be used to sample that location from the texture. 84 // Sampling the texture outside of the range of this transform is undefined. 85 // 86 // This transform is necessary to compensate for transforms that the stream 87 // content producer may implicitly apply to the content. By forcing users of 88 // a SurfaceTexture to apply this transform we avoid performing an extra 89 // copy of the data that would be needed to hide the transform from the 90 // user. 91 // 92 // The matrix is stored in column-major order so that it may be passed 93 // directly to OpenGL ES via the glLoadMatrixf or glUniformMatrix4fv 94 // functions. 95 void getTransformMatrix(float mtx[16]); 96 97 // getTimestamp retrieves the timestamp associated with the texture image 98 // set by the most recent call to updateTexImage. 99 // 100 // The timestamp is in nanoseconds, and is monotonically increasing. Its 101 // other semantics (zero point, etc) are source-dependent and should be 102 // documented by the source. 103 int64_t getTimestamp(); 104 105 // setFrameAvailableListener sets the listener object that will be notified 106 // when a new frame becomes available. 107 void setFrameAvailableListener(const sp<FrameAvailableListener>& listener); 108 109 // getAllocator retrieves the binder object that must be referenced as long 110 // as the GraphicBuffers dequeued from this SurfaceTexture are referenced. 111 // Holding this binder reference prevents SurfaceFlinger from freeing the 112 // buffers before the client is done with them. 113 sp<IBinder> getAllocator(); 114 115 // setDefaultBufferSize is used to set the size of buffers returned by 116 // requestBuffers when a with and height of zero is requested. 117 // A call to setDefaultBufferSize() may trigger requestBuffers() to 118 // be called from the client. 119 // The width and height parameters must be no greater than the minimum of 120 // GL_MAX_VIEWPORT_DIMS and GL_MAX_TEXTURE_SIZE (see: glGetIntegerv). 121 // An error due to invalid dimensions might not be reported until 122 // updateTexImage() is called. 123 status_t setDefaultBufferSize(uint32_t width, uint32_t height); 124 125 // getCurrentBuffer returns the buffer associated with the current image. 126 sp<GraphicBuffer> getCurrentBuffer() const; 127 128 // getCurrentTextureTarget returns the texture target of the current 129 // texture as returned by updateTexImage(). 130 GLenum getCurrentTextureTarget() const; 131 132 // getCurrentCrop returns the cropping rectangle of the current buffer 133 Rect getCurrentCrop() const; 134 135 // getCurrentTransform returns the transform of the current buffer 136 uint32_t getCurrentTransform() const; 137 138 // getCurrentScalingMode returns the scaling mode of the current buffer 139 uint32_t getCurrentScalingMode() const; 140 141 // isSynchronousMode returns whether the SurfaceTexture is currently in 142 // synchronous mode. 143 bool isSynchronousMode() const; 144 145 // abandon frees all the buffers and puts the SurfaceTexture into the 146 // 'abandoned' state. Once put in this state the SurfaceTexture can never 147 // leave it. When in the 'abandoned' state, all methods of the 148 // ISurfaceTexture interface will fail with the NO_INIT error. 149 // 150 // Note that while calling this method causes all the buffers to be freed 151 // from the perspective of the the SurfaceTexture, if there are additional 152 // references on the buffers (e.g. if a buffer is referenced by a client or 153 // by OpenGL ES as a texture) then those buffer will remain allocated. 154 void abandon(); 155 156 // set the name of the SurfaceTexture that will be used to identify it in 157 // log messages. 158 void setName(const String8& name); 159 160 // These functions call the corresponding BufferQueue implementation 161 // so the refactoring can proceed smoothly 162 status_t setDefaultBufferFormat(uint32_t defaultFormat); 163 status_t setConsumerUsageBits(uint32_t usage); 164 status_t setTransformHint(uint32_t hint); 165 virtual status_t setSynchronousMode(bool enabled); 166 virtual status_t setBufferCount(int bufferCount); 167 virtual status_t connect(int api, 168 uint32_t* outWidth, uint32_t* outHeight, uint32_t* outTransform); 169 170 sp<BufferQueue> getBufferQueue() const; 171 172 // dump our state in a String 173 virtual void dump(String8& result) const; 174 virtual void dump(String8& result, const char* prefix, char* buffer, size_t SIZE) const; 175 176protected: 177 178 static bool isExternalFormat(uint32_t format); 179 180private: 181 182 // createImage creates a new EGLImage from a GraphicBuffer. 183 EGLImageKHR createImage(EGLDisplay dpy, 184 const sp<GraphicBuffer>& graphicBuffer); 185 186 // computeCurrentTransformMatrix computes the transform matrix for the 187 // current texture. It uses mCurrentTransform and the current GraphicBuffer 188 // to compute this matrix and stores it in mCurrentTransformMatrix. 189 void computeCurrentTransformMatrix(); 190 191 // mCurrentTextureBuf is the graphic buffer of the current texture. It's 192 // possible that this buffer is not associated with any buffer slot, so we 193 // must track it separately in order to support the getCurrentBuffer method. 194 sp<GraphicBuffer> mCurrentTextureBuf; 195 196 // mCurrentCrop is the crop rectangle that applies to the current texture. 197 // It gets set each time updateTexImage is called. 198 Rect mCurrentCrop; 199 200 // mCurrentTransform is the transform identifier for the current texture. It 201 // gets set each time updateTexImage is called. 202 uint32_t mCurrentTransform; 203 204 // mCurrentScalingMode is the scaling mode for the current texture. It gets 205 // set to each time updateTexImage is called. 206 uint32_t mCurrentScalingMode; 207 208 // mCurrentTransformMatrix is the transform matrix for the current texture. 209 // It gets computed by computeTransformMatrix each time updateTexImage is 210 // called. 211 float mCurrentTransformMatrix[16]; 212 213 // mCurrentTimestamp is the timestamp for the current texture. It 214 // gets set each time updateTexImage is called. 215 int64_t mCurrentTimestamp; 216 217 // mTexName is the name of the OpenGL texture to which streamed images will 218 // be bound when updateTexImage is called. It is set at construction time 219 // changed with a call to setTexName. 220 const GLuint mTexName; 221 222 // mUseFenceSync indicates whether creation of the EGL_KHR_fence_sync 223 // extension should be used to prevent buffers from being dequeued before 224 // it's safe for them to be written. It gets set at construction time and 225 // never changes. 226 const bool mUseFenceSync; 227 228 // mTexTarget is the GL texture target with which the GL texture object is 229 // associated. It is set in the constructor and never changed. It is 230 // almost always GL_TEXTURE_EXTERNAL_OES except for one use case in Android 231 // Browser. In that case it is set to GL_TEXTURE_2D to allow 232 // glCopyTexSubImage to read from the texture. This is a hack to work 233 // around a GL driver limitation on the number of FBO attachments, which the 234 // browser's tile cache exceeds. 235 const GLenum mTexTarget; 236 237 // SurfaceTexture maintains EGL information about GraphicBuffers that corresponds 238 // directly with BufferQueue's buffers 239 struct EGLSlot { 240 EGLSlot() 241 : mEglImage(EGL_NO_IMAGE_KHR), 242 mEglDisplay(EGL_NO_DISPLAY), 243 mFence(EGL_NO_SYNC_KHR) { 244 } 245 246 sp<GraphicBuffer> mGraphicBuffer; 247 248 // mEglImage is the EGLImage created from mGraphicBuffer. 249 EGLImageKHR mEglImage; 250 251 // mEglDisplay is the EGLDisplay used to create mEglImage. 252 EGLDisplay mEglDisplay; 253 254 // mFence is the EGL sync object that must signal before the buffer 255 // associated with this buffer slot may be dequeued. It is initialized 256 // to EGL_NO_SYNC_KHR when the buffer is created and (optionally, based 257 // on a compile-time option) set to a new sync object in updateTexImage. 258 EGLSyncKHR mFence; 259 }; 260 261 EGLSlot mEGLSlots[BufferQueue::NUM_BUFFER_SLOTS]; 262 263 // mAbandoned indicates that the BufferQueue will no longer be used to 264 // consume images buffers pushed to it using the ISurfaceTexture interface. 265 // It is initialized to false, and set to true in the abandon method. A 266 // BufferQueue that has been abandoned will return the NO_INIT error from 267 // all ISurfaceTexture methods capable of returning an error. 268 bool mAbandoned; 269 270 // mName is a string used to identify the SurfaceTexture in log messages. 271 // It can be set by the setName method. 272 String8 mName; 273 274 // mMutex is the mutex used to prevent concurrent access to the member 275 // variables of SurfaceTexture objects. It must be locked whenever the 276 // member variables are accessed. 277 mutable Mutex mMutex; 278 279 // mCurrentTexture is the buffer slot index of the buffer that is currently 280 // bound to the OpenGL texture. It is initialized to INVALID_BUFFER_SLOT, 281 // indicating that no buffer slot is currently bound to the texture. Note, 282 // however, that a value of INVALID_BUFFER_SLOT does not necessarily mean 283 // that no buffer is bound to the texture. A call to setBufferCount will 284 // reset mCurrentTexture to INVALID_BUFFER_SLOT. 285 int mCurrentTexture; 286 287 // The SurfaceTexture has-a BufferQueue and is responsible for creating this object 288 // if none is supplied 289 sp<BufferQueue> mBufferQueue; 290 291}; 292 293// ---------------------------------------------------------------------------- 294}; // namespace android 295 296#endif // ANDROID_GUI_SURFACETEXTURE_H 297