Changes to Memoryless texture setting

- Added extensive validation: - Load & Store actions are validated - TextureGpu::copyTo validates - AsyncTextureTicket validates - StagingTexture validates - Validation is used on non-tilers too, to ease development and cross-platform compatibility & testing. - Replaced TextureFlags::TilerDepthMemoryless with DepthBuffer::POOL_MEMORYLESS - Eugene's code was more aggressive in deducing if memoryless could be used, but this would break advanced user cases (i.e. where UAV / Compute Shaders are involved). While it might be possible to deduce a that a NotTexture + RenderTexture + not UAV should be memoryless, such specific flag combination implies the user knows what they're doing and can request the memoryless explicitly. Discardable does not mean it's safe for the texture to be memoryless, since Discardable is for content that can be discarded for the next frame, but it may still be accessed during the same frame. Explicit MSAA are almost never intended to be memoryless. - Make implicit MSAA textures always memoryless - "WindowMemoryless" replaced with per-window setting memoryless_depth_buffer
OGRECave · Nov 16, 2024 · bf991d0 · bf991d0
1 parent c41413e
commit bf991d0
Show file tree

Hide file tree

Showing 39 changed files with 234 additions and 148 deletions.
diff --git a/OgreMain/include/OgreDepthBuffer.h b/OgreMain/include/OgreDepthBuffer.h
@@ -89,6 +89,11 @@ namespace Ogre
             POOL_NO_DEPTH = 0,
             POOL_MANUAL_USAGE OGRE_DEPRECATED_ENUM_VER( 3 ) = 0,
             POOL_DEFAULT = 1,
+
+            /// The depth buffer doesn't does not have memory backing it.
+            /// It will be created with TextureFlags::TilerMemoryless.
+            POOL_MEMORYLESS = 65533,
+
             /// Deprecated.
             ///
             /// Do NOT use this flag directly. It made sense in Ogre 2.1

diff --git a/OgreMain/include/OgreRenderPassDescriptor.h b/OgreMain/include/OgreRenderPassDescriptor.h
@@ -204,6 +204,10 @@ namespace Ogre
 
     protected:
         void         checkRequiresTextureFlipping();
+        void         validateMemorylessTexture( const TextureGpu              *texture,
+                                                const LoadAction::LoadAction   loadAction,
+                                                const StoreAction::StoreAction storeAction,
+                                                const bool                     bIsDepthStencil );
         virtual void colourEntriesModified();
 
     public:

diff --git a/OgreMain/include/OgreTextureGpu.h b/OgreMain/include/OgreTextureGpu.h
@@ -169,15 +169,19 @@ namespace Ogre
             /// If this flag is present, either RenderToTexture or Uav must be present
             DiscardableContent  = 1u << 14u,
             /// When this flag is present, we can save VRAM by using memoryless storage mode (Metal on
-            /// iOS and Apple Silicon macOS). Choose the memoryless mode if your texture is a memoryless
-            /// render target that’s temporarily populated and accessed by the GPU. Memoryless render
-            /// targets are render targets that exist only in tile memory and are not backed by system
-            /// memory. An example is a depth or stencil texture thatʼs used only within a render pass
-            /// and isnʼt needed before or after GPU execution. This flag requires RenderToTexture
+            /// iOS and Apple Silicon macOS) aka TRANSIENT memory (Vulkan).
+            ///
+            /// With this flag set, the texture will not be backed by memory, it will only ever live in
+            /// cache. Only TBDR GPUs support this. It will be ignored if unsupported.
+            ///
+            /// Many operations are unsupported with TilerMemoryless textures (e.g. copy operations)
+            /// because there is no memory behind them.
+            ///
+            /// An example is a depth or stencil texture thatʼs used only within a render pass
+            /// and isnʼt needed before or after GPU execution.
+            ///
+            /// This flag requires RenderToTexture.
             TilerMemoryless = 1u << 15u,
-            /// When this flag is present together with RenderToTexture it will use DepthBuffer with
-            /// TilerMemoryless option
-            TilerDepthMemoryless = 1u << 16u
             // clang-format on
         };
     }
@@ -660,10 +664,6 @@ namespace Ogre
         bool isPoolOwner() const;
         bool isDiscardableContent() const;
         bool isTilerMemoryless() const { return ( mTextureFlags & TextureFlags::TilerMemoryless ) != 0; }
-        bool isTilerDepthMemoryless() const
-        {
-            return ( mTextureFlags & TextureFlags::TilerDepthMemoryless ) != 0;
-        }
 
         /// OpenGL RenderWindows are a bit specific:
         ///     * Their origins are upside down. Which means we need to flip Y.

diff --git a/OgreMain/include/OgreWindow.h b/OgreMain/include/OgreWindow.h
@@ -81,6 +81,8 @@ namespace Ogre
 
         void setFinalResolution( uint32 widthPx, uint32 heightPx );
 
+        static bool requestedMemoryless( const NameValuePairList *ogre_nullable miscParams );
+
     public:
         Window( const String &title, uint32 widthPt, uint32 heightPt, bool fullscreenMode );
         virtual ~Window();
@@ -288,7 +290,8 @@ namespace Ogre
         void _setPrimary();
         bool isPrimary() const;
 
-        virtual void _initialize( TextureGpuManager *textureGpuManager ) = 0;
+        virtual void _initialize( TextureGpuManager                     *textureGpuManager,
+                                  const NameValuePairList *ogre_nullable miscParams ) = 0;
 
         /// Overloaded version of getMetrics from RenderTarget, including extra details
         /// specific to windowing systems. Result is in pixels.

diff --git a/OgreMain/src/OgreAsyncTextureTicket.cpp b/OgreMain/src/OgreAsyncTextureTicket.cpp
@@ -87,6 +87,8 @@ namespace Ogre
         assert( ( !textureSrc->isMultisample() || !textureSrc->hasMsaaExplicitResolves() ||
                   textureSrc->isOpenGLRenderWindow() ) &&
                 "Cannot download from an explicitly resolved MSAA texture!" );
+        OGRE_ASSERT_LOW( !textureSrc->isTilerMemoryless() &&
+                         "Cannot download from a memoryless texture!" );
     }
     //-----------------------------------------------------------------------------------
     void AsyncTextureTicket::notifyTextureChanged( TextureGpu *texture,

diff --git a/OgreMain/src/OgreRenderPassDescriptor.cpp b/OgreMain/src/OgreRenderPassDescriptor.cpp
@@ -163,6 +163,47 @@ namespace Ogre
             mRequiresTextureFlipping = mColour[0].resolveTexture->requiresTextureFlipping();
     }
     //-----------------------------------------------------------------------------------
+    void RenderPassDescriptor::validateMemorylessTexture( const TextureGpu *texture,
+                                                          const LoadAction::LoadAction loadAction,
+                                                          const StoreAction::StoreAction storeAction,
+                                                          const bool bIsDepthStencil )
+    {
+        if( !texture->isTilerMemoryless() )
+            return;
+
+        if( loadAction != LoadAction::Clear && loadAction != LoadAction::DontCare &&
+            loadAction != LoadAction::ClearOnTilers )
+        {
+            OGRE_EXCEPT( Exception::ERR_INVALIDPARAMS,
+                         "Texture '" + texture->getNameStr() +
+                             "' is TilerMemoryless. For load actions it can only use clear, "
+                             "dont_care or clear_on_tilers.",
+                         "RenderPassDescriptor::validateMemorylessTexture" );
+        }
+
+        if( !texture->isMultisample() || bIsDepthStencil )
+        {
+            if( storeAction != StoreAction::DontCare )
+            {
+                OGRE_EXCEPT( Exception::ERR_INVALIDPARAMS,
+                             "Texture '" + texture->getNameStr() +
+                                 "' is TilerMemoryless. For store actions it can only use dont_care.",
+                             "RenderPassDescriptor::validateMemorylessTexture" );
+            }
+        }
+        else
+        {
+            if( storeAction != StoreAction::DontCare && storeAction != StoreAction::MultisampleResolve )
+            {
+                OGRE_EXCEPT( Exception::ERR_INVALIDPARAMS,
+                             "MSAA Texture '" + texture->getNameStr() +
+                                 "' is TilerMemoryless. For store actions it can only use dont_care "
+                                 "or resolve.",
+                             "RenderPassDescriptor::validateMemorylessTexture" );
+            }
+        }
+    }
+    //-----------------------------------------------------------------------------------
     void RenderPassDescriptor::colourEntriesModified()
     {
         mNumColourEntries = 0;
@@ -176,6 +217,9 @@ namespace Ogre
         {
             const RenderPassColourTarget &colourEntry = mColour[mNumColourEntries];
 
+            validateMemorylessTexture( colourEntry.texture, colourEntry.loadAction,
+                                       colourEntry.storeAction, false );
+
             if( colourEntry.texture->isRenderWindowSpecific() )
             {
                 RenderPassColourTarget &colourEntryRW = mColour[mNumColourEntries];
@@ -208,6 +252,14 @@ namespace Ogre
                                  "RenderPassDescriptor::colourEntriesModified" );
                 }
 
+                if( colourEntry.resolveTexture->isTilerMemoryless() )
+                {
+                    OGRE_EXCEPT( Exception::ERR_INVALIDPARAMS,
+                                 "Resolving to Texture '" + colourEntry.resolveTexture->getNameStr() +
+                                     "' which is memoryless!",
+                                 "RenderPassDescriptor::colourEntriesModified" );
+                }
+
                 if( colourEntry.texture != colourEntry.resolveTexture &&
                     !colourEntry.texture->hasMsaaExplicitResolves() )
                 {
@@ -305,6 +357,8 @@ namespace Ogre
                                  "RenderPassDescriptor::entriesModified" );
                 }
             }
+
+            validateMemorylessTexture( mDepth.texture, mDepth.loadAction, mDepth.storeAction, true );
         }
 
         if( mStencil.texture && mStencil.texture != mDepth.texture )
@@ -323,6 +377,9 @@ namespace Ogre
                                  "RenderPassDescriptor::entriesModified" );
                 }
             }
+
+            validateMemorylessTexture( mStencil.texture, mStencil.loadAction, mStencil.storeAction,
+                                       true );
         }
 
         checkRequiresTextureFlipping();

diff --git a/OgreMain/src/OgreRenderSystem.cpp b/OgreMain/src/OgreRenderSystem.cpp
@@ -675,7 +675,7 @@ namespace Ogre
         if( !preferDepthTexture )
             textureFlags |= TextureFlags::NotTexture | TextureFlags::DiscardableContent;
 
-        if( colourTexture->isTilerMemoryless() || colourTexture->isTilerDepthMemoryless() )
+        if( colourTexture->getDepthBufferPoolId() == DepthBuffer::POOL_MEMORYLESS )
             textureFlags |= TextureFlags::TilerMemoryless;
 
         char tmpBuffer[64];

diff --git a/OgreMain/src/OgreStagingTexture.cpp b/OgreMain/src/OgreStagingTexture.cpp
@@ -135,6 +135,14 @@ namespace Ogre
                 "Did you modify it? Did it get corrupted?" );
         assert( ( !cpuSrcBox || srcBox.equalSize( *cpuSrcBox ) ) && "Src & cpuSrcBox must be equal" );
 
+        if( dstTexture->isTilerMemoryless() )
+        {
+            OGRE_EXCEPT(
+                Exception::ERR_INVALIDPARAMS,
+                "Cannot upload to texture '" + dstTexture->getNameStr() + "' because it's memoryless.",
+                "StagingTexture::upload" );
+        }
+
         if( dstTexture->isMultisample() )
         {
             OGRE_EXCEPT(

diff --git a/OgreMain/src/OgreTextureGpu.cpp b/OgreMain/src/OgreTextureGpu.cpp
@@ -30,6 +30,7 @@ THE SOFTWARE.
 
 #include "OgreTextureGpu.h"
 
+#include "OgreDepthBuffer.h"
 #include "OgreException.h"
 #include "OgreLogManager.h"
 #include "OgreLwString.h"
@@ -668,6 +669,8 @@ namespace Ogre
         assert( this != dst || !srcBox.overlaps( dstBox ) );
         assert( srcMipLevel < this->getNumMipmaps() && dstMipLevel < dst->getNumMipmaps() );
         OGRE_ASSERT_LOW( ( this->getOrientationMode() & 0x01 ) == ( dst->getOrientationMode() & 0x01 ) );
+        OGRE_ASSERT_LOW( !this->isTilerMemoryless() );
+        OGRE_ASSERT_LOW( !dst->isTilerMemoryless() );
     }
     //-----------------------------------------------------------------------------------
     void TextureGpu::_setDepthBufferDefaults( uint16 depthBufferPoolId, bool preferDepthTexture,
@@ -913,7 +916,7 @@ namespace Ogre
             this->getInternalHeight() == colourTarget->getInternalHeight() &&
             this->getSampleDescription() == colourTarget->getSampleDescription() &&
             this->isTilerMemoryless() ==
-                ( colourTarget->isTilerMemoryless() || colourTarget->isTilerDepthMemoryless() ) &&
+                ( colourTarget->getDepthBufferPoolId() == DepthBuffer::POOL_MEMORYLESS ) &&
             this->isRenderWindowSpecific() == colourTarget->isRenderWindowSpecific() )
         {
             return true;

diff --git a/OgreMain/src/OgreWindow.cpp b/OgreMain/src/OgreWindow.cpp
@@ -31,6 +31,7 @@ THE SOFTWARE.
 #include "OgreWindow.h"
 
 #include "OgreException.h"
+#include "OgreStringConverter.h"
 
 namespace Ogre
 {
@@ -71,6 +72,20 @@ namespace Ogre
         if( mStencilBuffer )
             mStencilBuffer->setResolution( widthPx, heightPx, 1u );
     }
+    //-------------------------------------------------------------------------
+    bool Window::requestedMemoryless( const NameValuePairList *ogre_nullable miscParams )
+    {
+        if( !miscParams )
+            return false;
+
+        NameValuePairList::const_iterator opt;
+        NameValuePairList::const_iterator end = miscParams->end();
+
+        opt = miscParams->find( "memoryless_depth_buffer" );
+        if( opt != end )
+            return StringConverter::parseBool( opt->second );
+        return false;
+    }
     //-----------------------------------------------------------------------------------
     void Window::setTitle( const String &title ) { mTitle = title; }
     //-----------------------------------------------------------------------------------

diff --git a/RenderSystems/Direct3D11/include/OgreD3D11Window.h b/RenderSystems/Direct3D11/include/OgreD3D11Window.h
@@ -123,7 +123,8 @@ namespace Ogre
                                    D3D11RenderSystem *renderSystem );
         ~D3D11WindowSwapChainBased() override;
 
-        void _initialize( TextureGpuManager *textureGpuManager ) override;
+        void _initialize( TextureGpuManager                     *textureGpuManager,
+                          const NameValuePairList *ogre_nullable miscParams ) override;
         void destroy() override;
 
         /// @copydoc Window::setFsaa

diff --git a/RenderSystems/Direct3D11/include/Windowing/WIN32/OgreD3D11WindowHwnd.h b/RenderSystems/Direct3D11/include/Windowing/WIN32/OgreD3D11WindowHwnd.h
@@ -73,7 +73,8 @@ namespace Ogre
                          D3D11Device &device, D3D11RenderSystem *renderSystem );
         ~D3D11WindowHwnd() override;
 
-        void _initialize( TextureGpuManager *textureGpuManager ) override;
+        void _initialize( TextureGpuManager                     *textureGpuManager,
+                          const NameValuePairList *ogre_nullable miscParams ) override;
         void destroy() override;
 
         void reposition( int32 left, int32 top ) override;

diff --git a/RenderSystems/Direct3D11/src/OgreD3D11RenderSystem.cpp b/RenderSystems/Direct3D11/src/OgreD3D11RenderSystem.cpp
@@ -1029,7 +1029,7 @@ namespace Ogre
             mSecondaryWindows.push_back( win );
         }
 
-        win->_initialize( mTextureGpuManager );
+        win->_initialize( mTextureGpuManager, miscParams );
 
         return win;
     }

diff --git a/RenderSystems/Direct3D11/src/OgreD3D11Window.cpp b/RenderSystems/Direct3D11/src/OgreD3D11Window.cpp
@@ -171,7 +171,8 @@ namespace Ogre
         return mUseFlipMode ? 2 : mRenderSystem->getVaoManager()->getDynamicBufferMultiplier() - 1u;
     }
     //-----------------------------------------------------------------------------------
-    void D3D11WindowSwapChainBased::_initialize( TextureGpuManager *textureGpuManager )
+    void D3D11WindowSwapChainBased::_initialize( TextureGpuManager *textureGpuManager,
+                                                 const NameValuePairList * )
     {
         _createSwapChain();
 

diff --git a/RenderSystems/Direct3D11/src/Windowing/WIN32/OgreD3D11WindowHwnd.cpp b/RenderSystems/Direct3D11/src/Windowing/WIN32/OgreD3D11WindowHwnd.cpp
@@ -470,9 +470,10 @@ namespace Ogre
         setHidden( mHidden );
     }
     //-----------------------------------------------------------------------------------
-    void D3D11WindowHwnd::_initialize( TextureGpuManager *textureGpuManager )
+    void D3D11WindowHwnd::_initialize( TextureGpuManager *textureGpuManager,
+                                       const NameValuePairList *miscParams )
     {
-        D3D11WindowSwapChainBased::_initialize( textureGpuManager );
+        D3D11WindowSwapChainBased::_initialize( textureGpuManager, miscParams );
 
         IDXGIFactory1 *dxgiFactory1 = mDevice.GetDXGIFactory();
         dxgiFactory1->MakeWindowAssociation( mHwnd,

diff --git a/RenderSystems/GL3Plus/include/windowing/GLX/OgreGLXWindow.h b/RenderSystems/GL3Plus/include/windowing/GLX/OgreGLXWindow.h
@@ -36,6 +36,8 @@ THE SOFTWARE.
 
 namespace Ogre
 {
+    OGRE_ASSUME_NONNULL_BEGIN
+
     class _OgrePrivate GLXWindow final : public Window
     {
     protected:
@@ -60,7 +62,8 @@ namespace Ogre
                    GLXGLSupport *glsupport );
         ~GLXWindow() override;
 
-        void _initialize( TextureGpuManager *textureManager ) override;
+        void _initialize( TextureGpuManager                     *textureManager,
+                          const NameValuePairList *ogre_nullable miscParams ) override;
 
         void setVSync( bool vSync, uint32 vSyncInterval ) override;
         void reposition( int32 left, int32 top ) override;
@@ -108,6 +111,8 @@ namespace Ogre
 
         bool requiresTextureFlipping() const { return false; }
     };
+
+    OGRE_ASSUME_NONNULL_END
 }  // namespace Ogre
 
 #endif
diff --git a/RenderSystems/GL3Plus/include/windowing/win32/OgreWin32Window.h b/RenderSystems/GL3Plus/include/windowing/win32/OgreWin32Window.h
@@ -73,7 +73,8 @@ namespace Ogre
                      Win32GLSupport &glsupport );
         virtual ~Win32Window();
 
-        virtual void _initialize( TextureGpuManager *textureGpuManager );
+        virtual void _initialize( TextureGpuManager                     *textureGpuManager,
+                                  const NameValuePairList *ogre_nullable miscParams );
         virtual void destroy();
 
         virtual void reposition( int32 left, int32 top );

diff --git a/RenderSystems/GL3Plus/src/OgreGL3PlusRenderSystem.cpp b/RenderSystems/GL3Plus/src/OgreGL3PlusRenderSystem.cpp
@@ -889,7 +889,7 @@ namespace Ogre
             mTextureGpuManager->_update( true );
         }
 
-        win->_initialize( mTextureGpuManager );
+        win->_initialize( mTextureGpuManager, miscParams );
 
         return win;
     }

diff --git a/RenderSystems/GL3Plus/src/windowing/GLX/OgreGLXWindow.cpp b/RenderSystems/GL3Plus/src/windowing/GLX/OgreGLXWindow.cpp
@@ -541,7 +541,7 @@ namespace Ogre
         mClosed = false;
     }
     //-----------------------------------------------------------------------------------
-    void GLXWindow::_initialize( TextureGpuManager *_textureManager )
+    void GLXWindow::_initialize( TextureGpuManager *_textureManager, const NameValuePairList * )
     {
         GL3PlusTextureGpuManager *textureManager =
             static_cast<GL3PlusTextureGpuManager *>( _textureManager );

diff --git a/RenderSystems/GL3Plus/src/windowing/win32/OgreWin32Window.cpp b/RenderSystems/GL3Plus/src/windowing/win32/OgreWin32Window.cpp
@@ -642,7 +642,7 @@ namespace Ogre
         mFullscreenMode = mRequestedFullscreenMode;
     }
     //-----------------------------------------------------------------------------------
-    void Win32Window::_initialize( TextureGpuManager *textureGpuManager )
+    void Win32Window::_initialize( TextureGpuManager *textureGpuManager, const NameValuePairList * )
     {
         GL3PlusTextureGpuManager *textureManager =
             static_cast<GL3PlusTextureGpuManager *>( textureGpuManager );

diff --git a/RenderSystems/Metal/include/OgreMetalTextureGpuManager.h b/RenderSystems/Metal/include/OgreMetalTextureGpuManager.h
@@ -75,7 +75,7 @@ namespace Ogre
             If caller doesn't delete it, it will leak.
         */
         TextureGpu *createTextureGpuWindow( MetalWindow *window );
-        TextureGpu *createWindowDepthBuffer();
+        TextureGpu *createWindowDepthBuffer( const bool bMemoryLess );
 
         id<MTLTexture> getBlankTextureMetalName( TextureTypes::TextureTypes textureType ) const;
 

diff --git a/RenderSystems/Metal/include/OgreMetalWindow.h b/RenderSystems/Metal/include/OgreMetalWindow.h
@@ -78,7 +78,8 @@ namespace Ogre
         virtual void create( bool fullScreen, const NameValuePairList *miscParams );
         void         destroy() override;
 
-        void _initialize( TextureGpuManager *textureGpuManager ) override;
+        void _initialize( TextureGpuManager       *textureGpuManager,
+                          const NameValuePairList *miscParams ) override;
 
         void reposition( int32 left, int32 top ) override;
         void requestResolution( uint32 width, uint32 height ) override;