texture_gles.h

Go to the documentation of this file.

// Copyright 2013 The Flutter Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
 
#ifndef FLUTTER_IMPELLER_RENDERER_BACKEND_GLES_TEXTURE_GLES_H_
#define FLUTTER_IMPELLER_RENDERER_BACKEND_GLES_TEXTURE_GLES_H_
 
#include <array>
#include <bitset>
 
#include "fml/logging.h"
#include "impeller/base/backend_cast.h"
#include "impeller/core/texture.h"
#include "impeller/renderer/backend/gles/handle_gles.h"
#include "impeller/renderer/backend/gles/reactor_gles.h"
#include "impeller/renderer/backend/gles/unique_handle_gles.h"
 
namespace impeller {
 
class TextureGLES final : public Texture,
                          public BackendCast<TextureGLES, Texture> {
 public:
  enum class Type {
    kTexture,
    kTextureMultisampled,
    kRenderBuffer,
    kRenderBufferMultisampled,
  };
 
  //----------------------------------------------------------------------------
  /// @brief      Create a texture by wrapping an external framebuffer object
  ///             whose lifecycle is owned by the caller.
  ///
  ///             This is useful for creating a render target for the default
  ///             window managed framebuffer.
  ///
  /// @param[in]  reactor  The reactor
  /// @param[in]  desc     The description
  /// @param[in]  fbo      The fbo
  ///
  /// @return     If a texture representation of the framebuffer could be
  ///             created.
  ///
  static std::shared_ptr<TextureGLES> WrapFBO(
      std::shared_ptr<ReactorGLES> reactor,
      TextureDescriptor desc,
      GLuint fbo);
 
  //----------------------------------------------------------------------------
  /// @brief      Create a texture by wrapping an external OpenGL texture
  ///             handle. Ownership of the texture handle is assumed by the
  ///             reactor.
  ///
  /// @param[in]  reactor          The reactor
  /// @param[in]  desc             The description
  /// @param[in]  external_handle  The external handle
  ///
  /// @return     If a texture representation of the framebuffer could be
  ///             created.
  ///
  static std::shared_ptr<TextureGLES> WrapTexture(
      std::shared_ptr<ReactorGLES> reactor,
      TextureDescriptor desc,
      HandleGLES external_handle);
 
  //----------------------------------------------------------------------------
  /// @brief      Create a "texture" that is never expected to be bound/unbound
  ///             explicitly or initialized in any way. It only exists to setup
  ///             a render pass description.
  ///
  /// @param[in]  reactor  The reactor
  /// @param[in]  desc     The description
  ///
  /// @return     If a texture placeholder could be created.
  ///
  static std::shared_ptr<TextureGLES> CreatePlaceholder(
      std::shared_ptr<ReactorGLES> reactor,
      TextureDescriptor desc);
 
  TextureGLES(std::shared_ptr<ReactorGLES> reactor,
              TextureDescriptor desc,
              bool threadsafe = false);
 
  // |Texture|
  bool IsValid() const override;
 
  std::optional<GLuint> GetGLHandle() const;
 
  [[nodiscard]] bool Bind();
 
  [[nodiscard]] bool GenerateMipmap();
 
  enum class AttachmentType {
    kColor0,
    kDepth,
    kStencil,
  };
  [[nodiscard]] bool SetAsFramebufferAttachment(GLenum target,
                                                AttachmentType attachment_type,
                                                uint32_t mip_level = 0,
                                                uint32_t slice = 0);
 
  Type GetType() const;
 
  bool IsWrapped() const;
 
  /// @brief Reset the internal texture state so that the reactor will not free
  ///        the associated handle.
  void Leak();
 
  std::optional<GLuint> GetFBO() const;
 
  //----------------------------------------------------------------------------
  /// @brief      Indicates that all texture storage has already been allocated
  ///             and contents initialized.
  ///
  ///             This is similar to calling `MarkSliceInitialized` with all
  ///             slices.
  ///
  /// @see        MarkSliceInitialized.
  ///
  void MarkContentsInitialized();
 
  //----------------------------------------------------------------------------
  /// @brief      Indicates that a specific texture slice has been initialized.
  ///
  /// @param[in]  slice  The slice to mark as being initialized.
  ///
  void MarkSliceInitialized(size_t slice);
 
  bool IsSliceInitialized(size_t slice) const;
 
  //----------------------------------------------------------------------------
  /// @brief      Indicates that storage for `mip_level` of `slice` has been
  ///             allocated by a `glTexImage2D` call (or equivalent).
  ///
  ///             GLES raises `GL_INVALID_OPERATION` when `glTexSubImage2D`
  ///             targets a level that has not been previously defined, so
  ///             every per-level upload must check this first and allocate
  ///             on demand.
  ///
  /// @param[in]  slice      The slice (cubemap face for cubemaps, otherwise
  ///                        always 0).
  /// @param[in]  mip_level  The mip level whose storage was allocated.
  ///
  void MarkSliceMipLevelInitialized(size_t slice, size_t mip_level);
 
  bool IsSliceMipLevelInitialized(size_t slice, size_t mip_level) const;
 
  //----------------------------------------------------------------------------
  /// @brief      Attach a sync fence to this texture that will be waited on
  ///             before encoding a rendering operation that references it.
  ///
  /// @param[in]  fence  A handle to a sync fence.
  ///
  void SetFence(HandleGLES fence);
 
  /// Store the FBO object for recycling in the 2D renderer.
  ///
  /// The color0 texture used by the 2D renderer will use this texture
  /// object to store the associated FBO the first time it is used.
  void SetCachedFBO(HandleGLES fbo);
 
  /// Retrieve the cached FBO object, or a dead handle if there is no object.
  const HandleGLES& GetCachedFBO() const;
 
  /// Records the subresource the cached FBO is currently bound to.
  void SetCachedFBOSubresource(uint32_t mip_level, uint32_t slice);
 
  /// Whether the cached FBO is currently bound to `(mip_level, slice)`. When
  /// false, the FBO must be re-attached before use.
  bool CachedFBOMatchesSubresource(uint32_t mip_level, uint32_t slice) const;
 
  // Visible for testing.
  std::optional<HandleGLES> GetSyncFence() const;
 
  // visible for testing
  Type ComputeTypeForBinding(GLenum target) const;
 
 private:
  std::shared_ptr<ReactorGLES> reactor_;
  const Type type_;
  UniqueHandleGLES handle_;
  UniqueHandleGLES fence_;
  // Tracks which `(slice, mip_level)` pairs have had their storage allocated
  // by a `glTexImage2D` call. Allocation is performed lazily on first write
  // to a level so the only-renders-then-mipmaps path (Impeller's snapshot
  // pipeline) keeps its single base-level allocation, and per-level uploads
  // only pay for the levels they actually touch.
  //
  // Sized for up to 6 cubemap faces × 16 mip levels (covers a 32k base
  // dimension); requested levels above this are simply not tracked.
  static constexpr size_t kMaxTrackedMipLevels = 16;
  std::array<std::bitset<kMaxTrackedMipLevels>, 6> slice_mip_initialized_ = {};
  const bool is_wrapped_;
  const std::optional<GLuint> wrapped_fbo_;
  UniqueHandleGLES cached_fbo_;
  uint32_t cached_fbo_mip_level_ = 0;
  uint32_t cached_fbo_slice_ = 0;
  bool is_valid_ = false;
 
  TextureGLES(std::shared_ptr<ReactorGLES> reactor,
              TextureDescriptor desc,
              bool threadsafe,
              std::optional<GLuint> fbo,
              std::optional<HandleGLES> external_handle);
 
  // |Texture|
  void SetLabel(std::string_view label) override;
 
  // |Texture|
  void SetLabel(std::string_view label, std::string_view trailing) override;
 
  // |Texture|
  bool OnSetContents(const uint8_t* contents,
                     size_t length,
                     size_t slice) override;
 
  // |Texture|
  bool OnSetContents(std::shared_ptr<const fml::Mapping> mapping,
                     size_t slice) override;
 
  // |Texture|
  ISize GetSize() const override;
 
  void InitializeContentsIfNecessary();
 
  // Allocates storage for `(slice, mip_level)` if it has not been allocated
  // yet, so the subresource can be attached to a framebuffer. Returns false on
  // failure.
  bool EnsureSliceMipLevelStorage(size_t slice, size_t mip_level);
 
  TextureGLES(const TextureGLES&) = delete;
 
  TextureGLES& operator=(const TextureGLES&) = delete;
};
 
}  // namespace impeller
 
#endif  // FLUTTER_IMPELLER_RENDERER_BACKEND_GLES_TEXTURE_GLES_H_