Radient: use data blobs for texture loading

Replace raw encoded and decoded texture data pointers and release
callbacks with IRadientDataBlob.

Author: TheMostDiligent

Radient/docs/DataBlobs.md

@@ -129,9 +129,9 @@ trigger it.
 The callback receives an `IRadientDataBlob` and the shared `pUserData` context.
 For a mutable blob, it can query `IID_RadientMutableDataBlob` to attempt recycling.
 
-The callback runs synchronously on the thread performing the final `EndRead`,
-outside the internal access lock. The blob stays alive throughout the callback,
-even if the callback releases the caller's reference. Retaining it afterward
+The callback runs synchronously on the thread performing the final `EndRead`
+and may call blob methods. The blob stays alive throughout the callback, even
+if the callback releases the caller's reference. Retaining it afterward
 requires acquiring a separate strong reference. A notification does not reserve
 access: another reader or writer may already be active. A mutable blob can be
 resized from the callback when no access scope is active. Recycling its contents
@@ -151,9 +151,8 @@ not receive a blob pointer because the blob is being destroyed and cannot be
 accessed or retained. It runs synchronously on the destroying thread and must not
 throw; C++ exceptions are caught and logged.
 
-A reference blob can keep external storage alive by storing an owner reference
-in the callback context. The same pattern works for a parsed document that owns
-encoded images, avoiding a copy of those image bytes:
+A reference blob can keep external storage alive without copying its bytes by
+storing an owner reference in the callback context:
 
 ```cpp
 auto Bytes = std::make_shared<const std::vector<Uint8>>(std::initializer_list<Uint8>{1, 2, 3});
@@ -188,3 +187,67 @@ factory also takes the storage mode. A null descriptor returns
 `IRadientDataBlob_GetSize`, `IRadientDataBlob_BeginRead`, and
 `IRadientDataBlob_EndRead` for the base interface. The corresponding
 `IRadientMutableDataBlob_*` macros expose inherited reads, write access, and `Resize`.
+
+## Encoded texture input
+
+Set `RadientTextureLoadInfo::pDataBlob` to a non-empty blob containing the entire
+encoded image. `LoadTexture()` retains the blob and starts reading during the
+call without copying its bytes. End any write scope before submitting a mutable
+blob; an active writer causes `RADIENT_STATUS_INVALID_OPERATION` and no texture
+handle. The caller can release its blob reference after the call returns.
+
+```cpp
+RadientTextureLoadInfo LoadInfo;
+LoadInfo.pDataBlob = Blob;
+LoadInfo.IsSRGB = True;
+RefCntAutoPtr<IRadientTextureAsset> Texture;
+const RADIENT_STATUS Status = AssetManager->LoadTexture(LoadInfo, &Texture);
+```
+
+`LoadTexture()` retains read access for as long as it needs the blob's bytes.
+Writes and resizing are unavailable during that time.
+
+`OnLastReaderReleased` can run during `LoadTexture()` or later on a worker thread.
+It marks the end of a read cycle, independently of GPU upload completion. A
+mutable blob can then be reused after acquiring write access; other readers
+still prevent writes and resizing. For REFERENCE blobs, external storage remains
+alive and unchanged for the blob's entire lifetime; release its owner through
+`OnDestroy`, as described above.
+
+`pDataBlob` and the decoded-pixel descriptor `pTextureData` are mutually exclusive.
+
+## Decoded texture input
+
+`RadientTextureData::pDataBlob` contains mip 0 pixels beginning at byte zero.
+Set `Width`, `Height`, `Format`, and optionally `Stride`, then pass the descriptor
+through `RadientTextureLoadInfo::pTextureData`. A zero stride means tightly packed
+rows. An explicit stride can include row padding, which is preserved during loading.
+
+The blob must cover `(Height - 1) * effective stride + active row size` bytes.
+Trailing padding after the final row is optional. Row padding and extra bytes
+do not affect texture caching. An undersized blob returns
+`RADIENT_STATUS_INVALID_ARGUMENT`. The read pointer must be aligned to the
+format's component size (1, 2, or 4 bytes). For multiple rows, the stride must
+also be a multiple of that size. Misaligned decoded storage returns
+`RADIENT_STATUS_INVALID_ARGUMENT`.
+
+```cpp
+RadientTextureData Pixels;
+Pixels.Width = 2;
+Pixels.Height = 2;
+Pixels.Format = RADIENT_TEXTURE_FORMAT_RGBA8_UNORM;
+Pixels.pDataBlob = PixelBlob; // At least 16 bytes containing four RGBA pixels.
+
+RadientTextureLoadInfo LoadInfo;
+LoadInfo.pTextureData = &Pixels;
+RefCntAutoPtr<IRadientTextureAsset> Texture;
+const RADIENT_STATUS Status = AssetManager->LoadTexture(LoadInfo, &Texture);
+```
+
+`LoadTexture()` copies the descriptor, retains its blob, and reads the pixels
+without copying the input bytes. It generates the remaining mip levels.
+The caller can discard the descriptor and release its blob reference after the
+call returns. End any write scope before loading; writes and resizing remain
+unavailable while Radient is reading the blob. Read-only COPY, REFERENCE, and
+mutable blobs follow the same ownership and notification rules as encoded
+texture input.

Radient/include/Assets/RadientTextureSource.hpp

@@ -27,11 +27,10 @@
 #pragma once
 
 #include "RadientAssets.h"
-#include "RefCntAutoPtr.hpp"
+#include "Core/RadientDataBlobReadAccess.hpp"
 
 #include <cstddef>
 #include <string>
-#include <vector>
 
 namespace Diligent
 {
@@ -40,7 +39,7 @@ struct ITextureLoader;
 struct IRadientAssetLocation;
 struct IRadientAssetResolver;
 
-/// Describes the valid readable span of RadientTextureData::pData.
+/// Describes the valid readable span of RadientTextureData::pDataBlob.
 struct RadientTextureDataSpan
 {
     /// Number of bytes in each row that contain texture data.
@@ -50,7 +49,7 @@ struct RadientTextureDataSpan
     /// Number of stored source rows. For block-compressed formats, this is the number of block rows.
     Uint32 RowCount = 0;
 
-    /// Minimum number of bytes that may be read from RadientTextureData::pData:
+    /// Minimum number of bytes that may be read from RadientTextureData::pDataBlob:
     /// (RowCount - 1) * Stride + ActiveRowSize.
     /// The final row does not need padding bytes beyond ActiveRowSize.
     Uint64 DataSize = 0;
@@ -61,8 +60,9 @@ struct RadientTextureDataSpan
 /// \returns    true if the format, dimensions, stride, and computed span are valid; false otherwise.
 ///
 /// \remarks    If RadientTextureData::Stride is zero, tightly packed rows are assumed.
-///             The function validates that non-zero stride is at least ActiveRowSize and that
-///             the computed DataSize does not overflow Uint64.
+///             Validates that non-zero stride is at least ActiveRowSize, that multiple rows
+///             start at component-aligned offsets, and that DataSize does not overflow Uint64.
+///             Does not acquire blob access or validate its data pointer or size.
 bool GetRadientTextureDataSpan(const RadientTextureData& TextureData,
                                RadientTextureDataSpan&   Span);
 
@@ -121,13 +121,12 @@ class RadientTextureSource final
         return m_DataSize;
     }
 
-    bool OwnsMemory() const
+    RADIENT_STATUS GetStatus() const
     {
-        return !m_Data.empty() || m_ReleaseData != nullptr;
+        return m_Status;
     }
 
-    void MakeMemoryCopy();
-
+    // For memory input, this source must outlive the returned loader.
     RADIENT_STATUS CreateLoader(IRadientAssetResolver* pAssetResolver,
                                 IRadientAssetLocation* pAssetLocation,
                                 ITextureLoader**       ppLoader) const;
@@ -145,16 +144,16 @@ class RadientTextureSource final
     std::string m_BaseURI;
     Bool        m_IsSRGB = False;
 
-    std::vector<Uint8> m_Data;
-    const void*        m_pData    = nullptr;
-    size_t             m_DataSize = 0;
+    RADIENT_STATUS m_Status = RADIENT_STATUS_OK;
+
+    // Retains the blob and read access while loaders use the source bytes.
+    RadientDataBlobReadAccess m_ReadAccess;
+    const void*               m_pData    = nullptr;
+    size_t                    m_DataSize = 0;
 
     RadientTextureData m_TextureData;
     Uint64             m_TextureDataActiveRowSize = 0;
     Uint32             m_TextureDataRowCount      = 0;
-
-    RadientTextureReleaseDataCallbackType m_ReleaseData          = nullptr;
-    void*                                 m_pReleaseDataUserData = nullptr;
 };
 
 } // namespace Diligent

Radient/interface/RadientAssets.h

@@ -31,6 +31,7 @@
 
 #include "RadientTypes.h"
 #include "RadientAssetResolver.h"
+#include "RadientDataBlob.h"
 
 #include "../../../DiligentCore/Primitives/interface/Object.h"
 
@@ -284,14 +285,6 @@ struct RadientMeshAssetDesc
 typedef struct RadientMeshAssetDesc RadientMeshAssetDesc;
 
 
-/// Texture load attributes.
-/// Optional callback used to release memory passed through RadientTextureLoadInfo::pData or
-/// RadientTextureLoadInfo::pTextureData->pData.
-/// The callback is invoked when Radient no longer needs the source memory.
-/// The callback may be invoked from any thread.
-/// The callback must not throw exceptions.
-typedef void (*RadientTextureReleaseDataCallbackType)(const void* pData, Uint64 DataSize, void* pUserData);
-
 /// Texture format.
 DILIGENT_TYPED_ENUM(RADIENT_TEXTURE_FORMAT, Uint8){
     /// Unknown format.
@@ -381,27 +374,45 @@ DILIGENT_TYPED_ENUM(RADIENT_TEXTURE_FORMAT, Uint8){
     /// Four 32-bit floating-point components.
     RADIENT_TEXTURE_FORMAT_RGBA32_FLOAT};
 
-/// Texture source data.
+/// Decoded mip 0 data for a 2D texture. The descriptor is copied by LoadTexture.
 struct RadientTextureData
 {
-    /// Texture width in pixels.
+    /// Texture width in pixels. Must be nonzero; defaults to zero.
     Uint32 Width DEFAULT_INITIALIZER(0);
 
-    /// Texture height in pixels.
+    /// Texture height in pixels. Must be nonzero; defaults to zero.
     Uint32 Height DEFAULT_INITIALIZER(0);
 
-    /// Texture format.
+    /// Pixel format. Must not be RADIENT_TEXTURE_FORMAT_UNKNOWN, which is the default.
     RADIENT_TEXTURE_FORMAT Format DEFAULT_INITIALIZER(RADIENT_TEXTURE_FORMAT_UNKNOWN);
 
-    /// Pointer to mip 0 pixel data.
-    const void* pData DEFAULT_INITIALIZER(nullptr);
+    /// Required blob containing mip 0 pixel data, starting at byte zero.
+    /// Accepts read-only or mutable blobs. Its size must cover every active source row:
+    /// (Height - 1) * effective stride + active row size. The effective stride is Stride
+    /// when nonzero, otherwise the active row size derived from Format and Width.
+    /// The final row does not require trailing padding; extra bytes are ignored.
+    /// The read pointer must be aligned to the format's component size (1, 2, or 4 bytes).
+    /// Insufficient size or component misalignment returns RADIENT_STATUS_INVALID_ARGUMENT.
+    /// LoadTexture retains the blob and acquires read access before returning, then
+    /// consumes the pixels directly without copying or repacking the source rows.
+    /// Read access lasts while loading or upload preparation references these pixels.
+    /// Other readers are allowed; writes and resizing remain blocked until all readers
+    /// finish. An active writer causes LoadTexture to return RADIENT_STATUS_INVALID_OPERATION.
+    /// The caller may release its blob reference after LoadTexture returns. For REFERENCE
+    /// storage, the bytes remain alive and unchanged for the blob's entire lifetime;
+    /// RadientDataBlobCreateInfo::OnDestroy can release their owner. Last-reader callbacks
+    /// may run during LoadTexture or later on a worker thread; they do not indicate GPU
+    /// upload completion. Defaults to nullptr, which is invalid for decoded texture input.
+    IRadientDataBlob* pDataBlob DEFAULT_INITIALIZER(nullptr);
 
     /// Row stride, in bytes. If zero, Radient derives tightly packed stride from Format and Width.
-    /// Stride must be at least the active row size.
+    /// Stride must be at least the active row size and, when Height is greater than one,
+    /// a multiple of the format's component size, so each row remains component-aligned.
     Uint32 Stride DEFAULT_INITIALIZER(0);
 };
 typedef struct RadientTextureData RadientTextureData;
 
+/// Texture load attributes. Selects encoded bytes, decoded pixels, or a URI source.
 struct RadientTextureLoadInfo
 {
     /// Source URI. For memory-backed textures, this is optional and may be used as the texture identity
@@ -412,31 +423,31 @@ struct RadientTextureLoadInfo
     /// value by the active asset resolver.
     const Char* BaseURI DEFAULT_INITIALIZER(nullptr);
 
-    /// Optional pointer to encoded texture data.
-    const void* pData DEFAULT_INITIALIZER(nullptr);
-
-    /// Size of the encoded texture data, in bytes.
-    Uint64 DataSize DEFAULT_INITIALIZER(0);
-
-    /// Optional pointer to texture data. Only 2D texture data is currently supported.
-    /// Mip 0 data must be provided; Radient always generates mip levels.
+    /// Optional blob containing the complete encoded texture, starting at byte zero.
+    /// Accepts read-only or mutable blobs. The blob must be non-empty and its size must fit in size_t.
+    /// Mutually exclusive with pTextureData. Radient retains the blob and acquires read access during
+    /// LoadTexture(), before returning. The data pointer and size are checked within this read scope.
+    /// The encoded bytes are consumed directly; LoadTexture() does not copy them.
+    /// Read access remains active until Radient no longer needs the source bytes, including any
+    /// decoder references used during upload preparation. The caller may release its blob reference
+    /// after LoadTexture() returns. For REFERENCE storage, the caller keeps the referenced bytes alive
+    /// and unchanged throughout the blob's lifetime; OnDestroy can release their owner. Other readers
+    /// may access the blob while Radient is reading it. Mutable blobs cannot be written or resized
+    /// until all readers finish. Finish any write access before calling LoadTexture(); an active writer
+    /// causes the call to return RADIENT_STATUS_INVALID_OPERATION without creating a texture asset.
+    /// If acquiring read access fails, no matching EndRead() or last-reader callback is performed.
+    /// Once acquired, access is released on completion or failure. OnLastReaderReleased, if set,
+    /// may run before LoadTexture() returns or later on a worker thread. This notification reports
+    /// that all readers have finished; it does not indicate GPU upload completion or end the lifetime
+    /// requirement for REFERENCE storage. See RadientDataBlobCreateInfo for callback details.
+    IRadientDataBlob* pDataBlob DEFAULT_INITIALIZER(nullptr);
+
+    /// Optional pointer to decoded texture data, mutually exclusive with pDataBlob.
+    /// Only 2D texture data is currently supported. Mip 0 data must be provided; Radient always
+    /// generates mip levels. The descriptor is copied during LoadTexture(), and its pDataBlob
+    /// is retained with read access while the pixels are needed; see RadientTextureData::pDataBlob.
     const RadientTextureData* pTextureData DEFAULT_INITIALIZER(nullptr);
 
-    /// Optional callback to release pData or pTextureData->pData when Radient no longer needs it.
-    /// For pTextureData, DataSize is the minimum source span described by RadientTextureData::pData.
-    /// If this callback is null and memory-backed source data is not null, Radient makes an internal copy of the data.
-    /// If this callback is non-null and LoadTexture() validation accepts a memory-backed source, ownership
-    /// of the source memory transfers to Radient before LoadTexture() returns. The callback is invoked exactly
-    /// once even if a later loading step fails and LoadTexture() returns an error status. If LoadTexture()
-    /// returns RADIENT_STATUS_INVALID_ARGUMENT during input validation, ownership remains with the caller and
-    /// the callback is not invoked.
-    /// The caller must not read, write, reuse, or release transferred source memory until the callback is invoked.
-    /// The callback may be invoked from any thread and must not throw exceptions.
-    RadientTextureReleaseDataCallbackType ReleaseData DEFAULT_INITIALIZER(nullptr);
-
-    /// User data passed to ReleaseData.
-    void* pReleaseDataUserData DEFAULT_INITIALIZER(nullptr);
-
     /// Interpret the texture as sRGB.
     Bool IsSRGB DEFAULT_INITIALIZER(False);
 };
@@ -669,9 +680,10 @@ DILIGENT_BEGIN_INTERFACE(IRadientAssetManager, IObject)
     /// The returned status reports source loading and GPU upload scheduling. A successful status
     /// does not guarantee that the texture is already available for sampling.
     /// Returns RADIENT_STATUS_PENDING when loading continues asynchronously.
-    /// If LoadInfo.ReleaseData is non-null and input validation accepts a memory-backed source, ownership
-    /// transfers to Radient before this method returns. The callback will be invoked exactly once even if
-    /// this method returns a non-INVALID_ARGUMENT failure caused by a later admission or loading step.
+    /// Encoded input in LoadInfo.pDataBlob or decoded input in LoadInfo.pTextureData->pDataBlob
+    /// is retained with read access until the source bytes are no longer needed. An active writer
+    /// prevents loading and returns RADIENT_STATUS_INVALID_OPERATION. The caller may release its
+    /// blob reference after the call. Rejected loads leave ownership with the caller.
     VIRTUAL RADIENT_STATUS METHOD(LoadTexture)(THIS_
                                                const RadientTextureLoadInfo REF LoadInfo,
                                                IRadientTextureAsset**           ppTexture) PURE;

Radient/src/Assets/RadientAssetManagerImpl.cpp

@@ -39,7 +39,6 @@
 #include "GPUUploadManager.h"
 #include "ThreadPool.hpp"
 
-#include <array>
 #include <atomic>
 #include <cstring>
 #include <exception>
@@ -254,21 +253,44 @@ RadientMaterialDefaultTextures CreateDefaultMaterialTextures(IThreadPool&
     RadientMaterialDefaultTextures DefaultTextures;
 
     auto LoadDefaultTexture = [&](const char* URI, Uint32 Pixel, IRadientTextureAsset** ppTexture) {
-        std::array<Uint32, DefaultTextureSize * DefaultTextureSize> Pixels;
-        Pixels.fill(Pixel);
+        RadientDataBlobCreateInfo BlobCI;
+        BlobCI.Size = DefaultTextureSize * DefaultTextureSize * sizeof(Pixel);
+        RefCntAutoPtr<IRadientMutableDataBlob> pPixels;
+        RADIENT_STATUS                         Status = CreateRadientMutableDataBlob(BlobCI, &pPixels);
+        if (Status != RADIENT_STATUS_OK)
+        {
+            LOG_ERROR_MESSAGE("Failed to allocate Radient default material texture '", URI, "'");
+            return;
+        }
+
+        void* pData = nullptr;
+        Status      = pPixels->BeginWrite(&pData);
+        if (Status != RADIENT_STATUS_OK)
+        {
+            LOG_ERROR_MESSAGE("Failed to access Radient default material texture '", URI, "'");
+            return;
+        }
+        for (Uint32 Index = 0; Index < DefaultTextureSize * DefaultTextureSize; ++Index)
+            std::memcpy(static_cast<Uint8*>(pData) + Index * sizeof(Pixel), &Pixel, sizeof(Pixel));
+        Status = pPixels->EndWrite();
+        if (Status != RADIENT_STATUS_OK)
+        {
+            LOG_ERROR_MESSAGE("Failed to finish Radient default material texture '", URI, "'");
+            return;
+        }
 
         RadientTextureData TextureData;
-        TextureData.Width  = DefaultTextureSize;
-        TextureData.Height = DefaultTextureSize;
-        TextureData.Format = RADIENT_TEXTURE_FORMAT_RGBA8_UNORM;
-        TextureData.pData  = Pixels.data();
-        TextureData.Stride = DefaultTextureSize * sizeof(Pixel);
+        TextureData.Width     = DefaultTextureSize;
+        TextureData.Height    = DefaultTextureSize;
+        TextureData.Format    = RADIENT_TEXTURE_FORMAT_RGBA8_UNORM;
+        TextureData.pDataBlob = pPixels;
+        TextureData.Stride    = DefaultTextureSize * sizeof(Pixel);
 
         RadientTextureLoadInfo LoadInfo;
         LoadInfo.URI          = URI;
         LoadInfo.pTextureData = &TextureData;
 
-        const RADIENT_STATUS Status = TextureManager.LoadTexture(ThreadPool, LoadInfo, ppTexture);
+        Status = TextureManager.LoadTexture(ThreadPool, LoadInfo, ppTexture);
         if (RADIENT_FAILED(Status))
             LOG_ERROR_MESSAGE("Failed to create Radient default material texture '", URI, "'");
     };