libs/nativedisplay/include/surfacetexture/EGLConsumer.h - third_party/android/platform/frameworks/native - Git at Google

 /*
  * Copyright (C) 2018 The Android Open Source Project
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
  * You may obtain a copy of the License at
  *
  *      http://www.apache.org/licenses/LICENSE-2.0
  *
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */

 #pragma once

 #include <EGL/egl.h>
 #include <EGL/eglext.h>
 #include <gui/BufferQueueDefs.h>
 #include <ui/FenceTime.h>
 #include <ui/GraphicBuffer.h>
 #include <utils/Mutex.h>

 namespace android {

 class SurfaceTexture;

 /*
  * EGLConsumer implements the parts of SurfaceTexture that deal with
  * textures attached to an GL context.
  */
 class EGLConsumer {
 public:
     EGLConsumer();

     /**
      * updateTexImage acquires the most recently queued buffer, and sets the
      * image contents of the target texture to it.
      *
      * This call may only be made while the OpenGL ES context to which the
      * target texture belongs is bound to the calling thread.
      *
      * This calls doGLFenceWait to ensure proper synchronization.
      */
     status_t updateTexImage(SurfaceTexture& st);

     /*
      * releaseTexImage releases the texture acquired in updateTexImage().
      * This is intended to be used in single buffer mode.
      *
      * This call may only be made while the OpenGL ES context to which the
      * target texture belongs is bound to the calling thread.
      */
     status_t releaseTexImage(SurfaceTexture& st);

     /**
      * detachFromContext detaches the EGLConsumer from the calling thread's
      * current OpenGL ES context.  This context must be the same as the context
      * that was current for previous calls to updateTexImage.
      *
      * Detaching a EGLConsumer from an OpenGL ES context will result in the
      * deletion of the OpenGL ES texture object into which the images were being
      * streamed.  After a EGLConsumer has been detached from the OpenGL ES
      * context calls to updateTexImage will fail returning INVALID_OPERATION
      * until the EGLConsumer is attached to a new OpenGL ES context using the
      * attachToContext method.
      */
     status_t detachFromContext(SurfaceTexture& st);

     /**
      * attachToContext attaches a EGLConsumer that is currently in the
      * 'detached' state to the current OpenGL ES context.  A EGLConsumer is
      * in the 'detached' state iff detachFromContext has successfully been
      * called and no calls to attachToContext have succeeded since the last
      * detachFromContext call.  Calls to attachToContext made on a
      * EGLConsumer that is not in the 'detached' state will result in an
      * INVALID_OPERATION error.
      *
      * The tex argument specifies the OpenGL ES texture object name in the
      * new context into which the image contents will be streamed.  A successful
      * call to attachToContext will result in this texture object being bound to
      * the texture target and populated with the image contents that were
      * current at the time of the last call to detachFromContext.
      */
     status_t attachToContext(uint32_t tex, SurfaceTexture& st);

     /**
      * onAcquireBufferLocked amends the ConsumerBase method to update the
      * mEglSlots array in addition to the ConsumerBase behavior.
      */
     void onAcquireBufferLocked(BufferItem* item, SurfaceTexture& st);

     /**
      * onReleaseBufferLocked amends the ConsumerBase method to update the
      * mEglSlots array in addition to the ConsumerBase.
      */
     void onReleaseBufferLocked(int slot);

     /**
      * onFreeBufferLocked frees up the given buffer slot. If the slot has been
      * initialized this will release the reference to the GraphicBuffer in that
      * slot and destroy the EGLImage in that slot.  Otherwise it has no effect.
      */
     void onFreeBufferLocked(int slotIndex);

     /**
      * onAbandonLocked amends the ConsumerBase method to clear
      * mCurrentTextureImage in addition to the ConsumerBase behavior.
      */
     void onAbandonLocked();

 protected:
     struct PendingRelease {
         PendingRelease()
               : isPending(false),
                 currentTexture(-1),
                 graphicBuffer(),
                 display(nullptr),
                 fence(nullptr) {}

         bool isPending;
         int currentTexture;
         sp<GraphicBuffer> graphicBuffer;
         EGLDisplay display;
         EGLSyncKHR fence;
     };

     /**
      * This releases the buffer in the slot referenced by mCurrentTexture,
      * then updates state to refer to the BufferItem, which must be a
      * newly-acquired buffer. If pendingRelease is not null, the parameters
      * which would have been passed to releaseBufferLocked upon the successful
      * completion of the method will instead be returned to the caller, so that
      * it may call releaseBufferLocked itself later.
      */
     status_t updateAndReleaseLocked(const BufferItem& item, PendingRelease* pendingRelease,
                                     SurfaceTexture& st);

     /**
      * Binds mTexName and the current buffer to mTexTarget.  Uses
      * mCurrentTexture if it's set, mCurrentTextureImage if not.  If the
      * bind succeeds, this calls doGLFenceWait.
      */
     status_t bindTextureImageLocked(SurfaceTexture& st);

     /**
      * Gets the current EGLDisplay and EGLContext values, and compares them
      * to mEglDisplay and mEglContext.  If the fields have been previously
      * set, the values must match; if not, the fields are set to the current
      * values.
      * The contextCheck argument is used to ensure that a GL context is
      * properly set; when set to false, the check is not performed.
      */
     status_t checkAndUpdateEglStateLocked(SurfaceTexture& st, bool contextCheck = false);

     /**
      * EglImage is a utility class for tracking and creating EGLImageKHRs. There
      * is primarily just one image per slot, but there is also special cases:
      *  - For releaseTexImage, we use a debug image (mReleasedTexImage)
      *  - After freeBuffer, we must still keep the current image/buffer
      * Reference counting EGLImages lets us handle all these cases easily while
      * also only creating new EGLImages from buffers when required.
      */
     class EglImage : public LightRefBase<EglImage> {
     public:
         EglImage(sp<GraphicBuffer> graphicBuffer);

         /**
          * createIfNeeded creates an EGLImage if required (we haven't created
          * one yet, or the EGLDisplay or crop-rect has changed).
          */
         status_t createIfNeeded(EGLDisplay display, bool forceCreate = false);

         /**
          * This calls glEGLImageTargetTexture2DOES to bind the image to the
          * texture in the specified texture target.
          */
         void bindToTextureTarget(uint32_t texTarget);

         const sp<GraphicBuffer>& graphicBuffer() { return mGraphicBuffer; }
         const native_handle* graphicBufferHandle() {
             return mGraphicBuffer == nullptr ? nullptr : mGraphicBuffer->handle;
         }

     private:
         // Only allow instantiation using ref counting.
         friend class LightRefBase<EglImage>;
         virtual ~EglImage();

         // createImage creates a new EGLImage from a GraphicBuffer.
         EGLImageKHR createImage(EGLDisplay dpy, const sp<GraphicBuffer>& graphicBuffer);

         // Disallow copying
         EglImage(const EglImage& rhs);
         void operator=(const EglImage& rhs);

         // mGraphicBuffer is the buffer that was used to create this image.
         sp<GraphicBuffer> mGraphicBuffer;

         // mEglImage is the EGLImage created from mGraphicBuffer.
         EGLImageKHR mEglImage;

         // mEGLDisplay is the EGLDisplay that was used to create mEglImage.
         EGLDisplay mEglDisplay;

         // mCropRect is the crop rectangle passed to EGL when mEglImage
         // was created.
         Rect mCropRect;
     };

     /**
      * doGLFenceWaitLocked inserts a wait command into the OpenGL ES command
      * stream to ensure that it is safe for future OpenGL ES commands to
      * access the current texture buffer.
      */
     status_t doGLFenceWaitLocked(SurfaceTexture& st) const;

     /**
      * syncForReleaseLocked performs the synchronization needed to release the
      * current slot from an OpenGL ES context.  If needed it will set the
      * current slot's fence to guard against a producer accessing the buffer
      * before the outstanding accesses have completed.
      */
     status_t syncForReleaseLocked(EGLDisplay dpy, SurfaceTexture& st);

     /**
      * returns a graphic buffer used when the texture image has been released
      */
     static sp<GraphicBuffer> getDebugTexImageBuffer();

     /**
      * The default consumer usage flags that EGLConsumer always sets on its
      * BufferQueue instance; these will be OR:d with any additional flags passed
      * from the EGLConsumer user. In particular, EGLConsumer will always
      * consume buffers as hardware textures.
      */
     static const uint64_t DEFAULT_USAGE_FLAGS = GraphicBuffer::USAGE_HW_TEXTURE;

     /**
      * mCurrentTextureImage is the EglImage/buffer of the current texture. It's
      * possible that this buffer is not associated with any buffer slot, so we
      * must track it separately in order to support the getCurrentBuffer method.
      */
     sp<EglImage> mCurrentTextureImage;

     /**
      * EGLSlot contains the information and object references that
      * EGLConsumer maintains about a BufferQueue buffer slot.
      */
     struct EglSlot {
         EglSlot() : mEglFence(EGL_NO_SYNC_KHR) {}

         /**
          * mEglImage is the EGLImage created from mGraphicBuffer.
          */
         sp<EglImage> mEglImage;

         /**
          * mFence is the EGL sync object that must signal before the buffer
          * associated with this buffer slot may be dequeued. It is initialized
          * to EGL_NO_SYNC_KHR when the buffer is created and (optionally, based
          * on a compile-time option) set to a new sync object in updateTexImage.
          */
         EGLSyncKHR mEglFence;
     };

     /**
      * mEglDisplay is the EGLDisplay with which this EGLConsumer is currently
      * associated.  It is intialized to EGL_NO_DISPLAY and gets set to the
      * current display when updateTexImage is called for the first time and when
      * attachToContext is called.
      */
     EGLDisplay mEglDisplay;

     /**
      * mEglContext is the OpenGL ES context with which this EGLConsumer is
      * currently associated.  It is initialized to EGL_NO_CONTEXT and gets set
      * to the current GL context when updateTexImage is called for the first
      * time and when attachToContext is called.
      */
     EGLContext mEglContext;

     /**
      * mEGLSlots stores the buffers that have been allocated by the BufferQueue
      * for each buffer slot.  It is initialized to null pointers, and gets
      * filled in with the result of BufferQueue::acquire when the
      * client dequeues a buffer from a
      * slot that has not yet been used. The buffer allocated to a slot will also
      * be replaced if the requested buffer usage or geometry differs from that
      * of the buffer allocated to a slot.
      */
     EglSlot mEglSlots[BufferQueueDefs::NUM_BUFFER_SLOTS];

     /**
      * protects static initialization
      */
     static Mutex sStaticInitLock;

     /**
      * mReleasedTexImageBuffer is a dummy buffer used when in single buffer
      * mode and releaseTexImage() has been called
      */
     static sp<GraphicBuffer> sReleasedTexImageBuffer;
     sp<EglImage> mReleasedTexImage;
 };

 } // namespace android
	/*
	* Copyright (C) 2018 The Android Open Source Project
	*
	* Licensed under the Apache License, Version 2.0 (the "License");
	* you may not use this file except in compliance with the License.
	* You may obtain a copy of the License at
	*
	* http://www.apache.org/licenses/LICENSE-2.0
	*
	* Unless required by applicable law or agreed to in writing, software
	* distributed under the License is distributed on an "AS IS" BASIS,
	* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	* See the License for the specific language governing permissions and
	* limitations under the License.
	*/

	#pragma once

	#include <EGL/egl.h>
	#include <EGL/eglext.h>
	#include <gui/BufferQueueDefs.h>
	#include <ui/FenceTime.h>
	#include <ui/GraphicBuffer.h>
	#include <utils/Mutex.h>

	namespace android {

	class SurfaceTexture;

	/*
	* EGLConsumer implements the parts of SurfaceTexture that deal with
	* textures attached to an GL context.
	*/
	class EGLConsumer {
	public:
	EGLConsumer();

	/**
	* updateTexImage acquires the most recently queued buffer, and sets the
	* image contents of the target texture to it.
	*
	* This call may only be made while the OpenGL ES context to which the
	* target texture belongs is bound to the calling thread.
	*
	* This calls doGLFenceWait to ensure proper synchronization.
	*/
	status_t updateTexImage(SurfaceTexture& st);

	/*
	* releaseTexImage releases the texture acquired in updateTexImage().
	* This is intended to be used in single buffer mode.
	*
	* This call may only be made while the OpenGL ES context to which the
	* target texture belongs is bound to the calling thread.
	*/
	status_t releaseTexImage(SurfaceTexture& st);

	/**
	* detachFromContext detaches the EGLConsumer from the calling thread's
	* current OpenGL ES context. This context must be the same as the context
	* that was current for previous calls to updateTexImage.
	*
	* Detaching a EGLConsumer from an OpenGL ES context will result in the
	* deletion of the OpenGL ES texture object into which the images were being
	* streamed. After a EGLConsumer has been detached from the OpenGL ES
	* context calls to updateTexImage will fail returning INVALID_OPERATION
	* until the EGLConsumer is attached to a new OpenGL ES context using the
	* attachToContext method.
	*/
	status_t detachFromContext(SurfaceTexture& st);

	/**
	* attachToContext attaches a EGLConsumer that is currently in the
	* 'detached' state to the current OpenGL ES context. A EGLConsumer is
	* in the 'detached' state iff detachFromContext has successfully been
	* called and no calls to attachToContext have succeeded since the last
	* detachFromContext call. Calls to attachToContext made on a
	* EGLConsumer that is not in the 'detached' state will result in an
	* INVALID_OPERATION error.
	*
	* The tex argument specifies the OpenGL ES texture object name in the
	* new context into which the image contents will be streamed. A successful
	* call to attachToContext will result in this texture object being bound to
	* the texture target and populated with the image contents that were
	* current at the time of the last call to detachFromContext.
	*/
	status_t attachToContext(uint32_t tex, SurfaceTexture& st);

	/**
	* onAcquireBufferLocked amends the ConsumerBase method to update the
	* mEglSlots array in addition to the ConsumerBase behavior.
	*/
	void onAcquireBufferLocked(BufferItem* item, SurfaceTexture& st);

	/**
	* onReleaseBufferLocked amends the ConsumerBase method to update the
	* mEglSlots array in addition to the ConsumerBase.
	*/
	void onReleaseBufferLocked(int slot);

	/**
	* onFreeBufferLocked frees up the given buffer slot. If the slot has been
	* initialized this will release the reference to the GraphicBuffer in that
	* slot and destroy the EGLImage in that slot. Otherwise it has no effect.
	*/
	void onFreeBufferLocked(int slotIndex);

	/**
	* onAbandonLocked amends the ConsumerBase method to clear
	* mCurrentTextureImage in addition to the ConsumerBase behavior.
	*/
	void onAbandonLocked();

	protected:
	struct PendingRelease {
	PendingRelease()
	: isPending(false),
	currentTexture(-1),
	graphicBuffer(),
	display(nullptr),
	fence(nullptr) {}

	bool isPending;
	int currentTexture;
	sp<GraphicBuffer> graphicBuffer;
	EGLDisplay display;
	EGLSyncKHR fence;
	};

	/**
	* This releases the buffer in the slot referenced by mCurrentTexture,
	* then updates state to refer to the BufferItem, which must be a
	* newly-acquired buffer. If pendingRelease is not null, the parameters
	* which would have been passed to releaseBufferLocked upon the successful
	* completion of the method will instead be returned to the caller, so that
	* it may call releaseBufferLocked itself later.
	*/
	status_t updateAndReleaseLocked(const BufferItem& item, PendingRelease* pendingRelease,
	SurfaceTexture& st);

	/**
	* Binds mTexName and the current buffer to mTexTarget. Uses
	* mCurrentTexture if it's set, mCurrentTextureImage if not. If the
	* bind succeeds, this calls doGLFenceWait.
	*/
	status_t bindTextureImageLocked(SurfaceTexture& st);

	/**
	* Gets the current EGLDisplay and EGLContext values, and compares them
	* to mEglDisplay and mEglContext. If the fields have been previously
	* set, the values must match; if not, the fields are set to the current
	* values.
	* The contextCheck argument is used to ensure that a GL context is
	* properly set; when set to false, the check is not performed.
	*/
	status_t checkAndUpdateEglStateLocked(SurfaceTexture& st, bool contextCheck = false);

	/**
	* EglImage is a utility class for tracking and creating EGLImageKHRs. There
	* is primarily just one image per slot, but there is also special cases:
	* - For releaseTexImage, we use a debug image (mReleasedTexImage)
	* - After freeBuffer, we must still keep the current image/buffer
	* Reference counting EGLImages lets us handle all these cases easily while
	* also only creating new EGLImages from buffers when required.
	*/
	class EglImage : public LightRefBase<EglImage> {
	public:
	EglImage(sp<GraphicBuffer> graphicBuffer);

	/**
	* createIfNeeded creates an EGLImage if required (we haven't created
	* one yet, or the EGLDisplay or crop-rect has changed).
	*/
	status_t createIfNeeded(EGLDisplay display, bool forceCreate = false);

	/**
	* This calls glEGLImageTargetTexture2DOES to bind the image to the
	* texture in the specified texture target.
	*/
	void bindToTextureTarget(uint32_t texTarget);

	const sp<GraphicBuffer>& graphicBuffer() { return mGraphicBuffer; }
	const native_handle* graphicBufferHandle() {
	return mGraphicBuffer == nullptr ? nullptr : mGraphicBuffer->handle;
	}

	private:
	// Only allow instantiation using ref counting.
	friend class LightRefBase<EglImage>;
	virtual ~EglImage();

	// createImage creates a new EGLImage from a GraphicBuffer.
	EGLImageKHR createImage(EGLDisplay dpy, const sp<GraphicBuffer>& graphicBuffer);

	// Disallow copying
	EglImage(const EglImage& rhs);
	void operator=(const EglImage& rhs);

	// mGraphicBuffer is the buffer that was used to create this image.
	sp<GraphicBuffer> mGraphicBuffer;

	// mEglImage is the EGLImage created from mGraphicBuffer.
	EGLImageKHR mEglImage;

	// mEGLDisplay is the EGLDisplay that was used to create mEglImage.
	EGLDisplay mEglDisplay;

	// mCropRect is the crop rectangle passed to EGL when mEglImage
	// was created.
	Rect mCropRect;
	};

	/**
	* doGLFenceWaitLocked inserts a wait command into the OpenGL ES command
	* stream to ensure that it is safe for future OpenGL ES commands to
	* access the current texture buffer.
	*/
	status_t doGLFenceWaitLocked(SurfaceTexture& st) const;

	/**
	* syncForReleaseLocked performs the synchronization needed to release the
	* current slot from an OpenGL ES context. If needed it will set the
	* current slot's fence to guard against a producer accessing the buffer
	* before the outstanding accesses have completed.
	*/
	status_t syncForReleaseLocked(EGLDisplay dpy, SurfaceTexture& st);

	/**
	* returns a graphic buffer used when the texture image has been released
	*/
	static sp<GraphicBuffer> getDebugTexImageBuffer();

	/**
	* The default consumer usage flags that EGLConsumer always sets on its
	* BufferQueue instance; these will be OR:d with any additional flags passed
	* from the EGLConsumer user. In particular, EGLConsumer will always
	* consume buffers as hardware textures.
	*/
	static const uint64_t DEFAULT_USAGE_FLAGS = GraphicBuffer::USAGE_HW_TEXTURE;

	/**
	* mCurrentTextureImage is the EglImage/buffer of the current texture. It's
	* possible that this buffer is not associated with any buffer slot, so we
	* must track it separately in order to support the getCurrentBuffer method.
	*/
	sp<EglImage> mCurrentTextureImage;

	/**
	* EGLSlot contains the information and object references that
	* EGLConsumer maintains about a BufferQueue buffer slot.
	*/
	struct EglSlot {
	EglSlot() : mEglFence(EGL_NO_SYNC_KHR) {}

	/**
	* mEglImage is the EGLImage created from mGraphicBuffer.
	*/
	sp<EglImage> mEglImage;

	/**
	* mFence is the EGL sync object that must signal before the buffer
	* associated with this buffer slot may be dequeued. It is initialized
	* to EGL_NO_SYNC_KHR when the buffer is created and (optionally, based
	* on a compile-time option) set to a new sync object in updateTexImage.
	*/
	EGLSyncKHR mEglFence;
	};

	/**
	* mEglDisplay is the EGLDisplay with which this EGLConsumer is currently
	* associated. It is intialized to EGL_NO_DISPLAY and gets set to the
	* current display when updateTexImage is called for the first time and when
	* attachToContext is called.
	*/
	EGLDisplay mEglDisplay;

	/**
	* mEglContext is the OpenGL ES context with which this EGLConsumer is
	* currently associated. It is initialized to EGL_NO_CONTEXT and gets set
	* to the current GL context when updateTexImage is called for the first
	* time and when attachToContext is called.
	*/
	EGLContext mEglContext;

	/**
	* mEGLSlots stores the buffers that have been allocated by the BufferQueue
	* for each buffer slot. It is initialized to null pointers, and gets
	* filled in with the result of BufferQueue::acquire when the
	* client dequeues a buffer from a
	* slot that has not yet been used. The buffer allocated to a slot will also
	* be replaced if the requested buffer usage or geometry differs from that
	* of the buffer allocated to a slot.
	*/
	EglSlot mEglSlots[BufferQueueDefs::NUM_BUFFER_SLOTS];

	/**
	* protects static initialization
	*/
	static Mutex sStaticInitLock;

	/**
	* mReleasedTexImageBuffer is a dummy buffer used when in single buffer
	* mode and releaseTexImage() has been called
	*/
	static sp<GraphicBuffer> sReleasedTexImageBuffer;
	sp<EglImage> mReleasedTexImage;
	};

	} // namespace android