Merge pull request #82 from bboczula/codex/issue-41-blob-lifecycle

[codex] Implement blob lifecycle storage

Author: bboczula

include/AssetSuite/AssetSuite.h

@@ -37,4 +37,31 @@ namespace AssetSuite
 		LoggingCallback callback,
 		LogLevel minLevel,
 		void* userData);
+
+	// Loads a file into a runtime-owned blob. outBlob must point to a null
+	// handle and receives ownership of the created blob handle on success.
+	//
+	// The blob bytes and source metadata are owned by the context. The caller
+	// retains ownership of filePath and may release or mutate that string after
+	// the call returns. A returned blob remains valid until ReleaseBlob is
+	// called for the same context, or until the owning context is destroyed.
+	// Blob operations follow the context's external synchronization
+	// requirements.
+	//
+	// Passing a null context returns Result::ErrorInvalidContext. Passing a
+	// null filePath, null outBlob, or non-null *outBlob returns
+	// Result::ErrorInvalidArgument. Missing files return
+	// Result::ErrorFileNotFound.
+	ASSET_SUITE_API Result LoadFile(ContextHandle context, const char* filePath, BlobHandle* outBlob);
+
+	// Releases a runtime-owned blob and sets the caller's handle to nullptr on
+	// success. Memory and metadata behind the blob are invalid immediately
+	// after a successful release.
+	//
+	// The blob must have been created by LoadFile on the same context. Passing
+	// a null context returns Result::ErrorInvalidContext. Passing nullptr, a
+	// pointer to a null blob handle, a stale handle, or a handle from another
+	// context returns Result::ErrorInvalidHandle. On failure, the caller's blob
+	// value is preserved.
+	ASSET_SUITE_API Result ReleaseBlob(ContextHandle context, BlobHandle* blob);
 }

include/AssetSuite/AssetSuiteDescriptors.h

@@ -16,9 +16,14 @@ namespace AssetSuite
 
 	struct BlobDesc
 	{
+		// Must be exactly sizeof(BlobDesc) when a descriptor is supplied.
 		uint32_t structSize;
+		// Number of bytes owned by the blob.
 		uint64_t byteSize;
+		// Best-known asset format. May be Unknown when the source extension or
+		// signature does not identify a supported asset type.
 		AssetFormat format;
+		// Reserved for future use. Must be zero.
 		uint32_t flags;
 	};
 

include/AssetSuite/AssetSuiteTypes.h

@@ -18,6 +18,7 @@ namespace AssetSuite
 		ErrorOutputBufferTooSmall = -5,
 		ErrorOutOfMemory = -6,
 		ErrorInvalidContext = -7,
+		ErrorInvalidHandle = -8,
 		ErrorUnknown = -1000
 	};
 

source/common/AssetSuite.cpp

@@ -41,6 +41,19 @@ namespace
 		normalizedDesc = *desc;
 		return AssetSuite::Result::Success;
 	}
+
+	AssetSuite::Result MapFileLoadResult(AssetSuite::ErrorCode error)
+	{
+		switch (error)
+		{
+		case AssetSuite::ErrorCode::OK:
+			return AssetSuite::Result::Success;
+		case AssetSuite::ErrorCode::NonExistingFile:
+			return AssetSuite::Result::ErrorFileNotFound;
+		default:
+			return AssetSuite::Result::ErrorUnknown;
+		}
+	}
 }
 
 AssetSuite::Result AssetSuite::GetVersion(Version* outVersion)
@@ -76,6 +89,8 @@ const char* AssetSuite::GetResultString(Result result)
 		return "Error: out of memory";
 	case Result::ErrorInvalidContext:
 		return "Error: invalid context";
+	case Result::ErrorInvalidHandle:
+		return "Error: invalid handle";
 	case Result::ErrorUnknown:
 		return "Error: unknown";
 	default:
@@ -125,6 +140,59 @@ AssetSuite::Result AssetSuite::SetLoggingCallback(
 	return Result::Success;
 }
 
+AssetSuite::Result AssetSuite::LoadFile(ContextHandle context, const char* filePath, BlobHandle* outBlob)
+{
+	if (!context)
+	{
+		return Result::ErrorInvalidContext;
+	}
+
+	if (!filePath || !outBlob || *outBlob)
+	{
+		return Result::ErrorInvalidArgument;
+	}
+
+	std::vector<uint8_t> rawBytes;
+	const ErrorCode loadResult = context->Runtime().FileLoader().LoadToMemory(filePath, true, rawBytes);
+	const Result mappedResult = MapFileLoadResult(loadResult);
+	if (mappedResult != Result::Success)
+	{
+		context->Runtime().Diagnostics().Add(loadResult, "Failed to load blob source file.");
+		return mappedResult;
+	}
+
+	try
+	{
+		Internal::Blob blob(std::move(rawBytes), Internal::MakeBlobSourceMetadata(filePath));
+		*outBlob = context->Runtime().BlobStorage().Create(std::move(blob));
+	}
+	catch (const std::bad_alloc&)
+	{
+		return Result::ErrorOutOfMemory;
+	}
+	catch (...)
+	{
+		return Result::ErrorUnknown;
+	}
+
+	return Result::Success;
+}
+
+AssetSuite::Result AssetSuite::ReleaseBlob(ContextHandle context, BlobHandle* blob)
+{
+	if (!context)
+	{
+		return Result::ErrorInvalidContext;
+	}
+
+	if (!blob || !*blob)
+	{
+		return Result::ErrorInvalidHandle;
+	}
+
+	return context->Runtime().BlobStorage().Release(blob);
+}
+
 AssetSuite::Manager::Manager()
 	: runtimeState(new Internal::RuntimeState())
 	, ownsRuntimeState(true)

source/runtime/AssetSuiteBlob.cpp

@@ -0,0 +1,91 @@
+#include "AssetSuiteBlob.h"
+
+#include <algorithm>
+#include <cctype>
+#include <string>
+#include <utility>
+
+namespace
+{
+	AssetSuite::AssetFormat ResolveBlobFormat(const std::filesystem::path& extension) noexcept
+	{
+		std::string normalizedExtension = extension.string();
+		std::transform(
+			normalizedExtension.begin(),
+			normalizedExtension.end(),
+			normalizedExtension.begin(),
+			[](unsigned char character)
+			{
+				return static_cast<char>(std::tolower(character));
+			});
+
+		if (normalizedExtension == ".bmp")
+		{
+			return AssetSuite::AssetFormat::BMP;
+		}
+
+		if (normalizedExtension == ".png")
+		{
+			return AssetSuite::AssetFormat::PNG;
+		}
+
+		if (normalizedExtension == ".ppm")
+		{
+			return AssetSuite::AssetFormat::PPM;
+		}
+
+		if (normalizedExtension == ".obj")
+		{
+			return AssetSuite::AssetFormat::WavefrontObj;
+		}
+
+		return AssetSuite::AssetFormat::Unknown;
+	}
+}
+
+AssetSuite::Internal::Blob::Blob(std::vector<uint8_t> bytes, BlobSourceMetadata metadata)
+	: bytes(std::move(bytes))
+	, metadata(std::move(metadata))
+{
+}
+
+AssetSuite::Internal::Blob::Blob(Blob&&) noexcept = default;
+
+AssetSuite::Internal::Blob& AssetSuite::Internal::Blob::operator=(Blob&&) noexcept = default;
+
+const uint8_t* AssetSuite::Internal::Blob::Data() const noexcept
+{
+	return bytes.empty() ? nullptr : bytes.data();
+}
+
+uint64_t AssetSuite::Internal::Blob::ByteSize() const noexcept
+{
+	return static_cast<uint64_t>(bytes.size());
+}
+
+const AssetSuite::Internal::BlobSourceMetadata&
+AssetSuite::Internal::Blob::SourceMetadata() const noexcept
+{
+	return metadata;
+}
+
+AssetSuite::BlobDesc AssetSuite::Internal::Blob::Describe() const noexcept
+{
+	return BlobDesc
+	{
+		sizeof(BlobDesc),
+		ByteSize(),
+		metadata.format,
+		0
+	};
+}
+
+AssetSuite::Internal::BlobSourceMetadata
+AssetSuite::Internal::MakeBlobSourceMetadata(const std::filesystem::path& sourcePath)
+{
+	BlobSourceMetadata metadata = {};
+	metadata.sourcePath = sourcePath;
+	metadata.extension = sourcePath.extension();
+	metadata.format = ResolveBlobFormat(metadata.extension);
+	return metadata;
+}

source/runtime/AssetSuiteBlob.h

@@ -0,0 +1,48 @@
+#pragma once
+
+#include <AssetSuite/AssetSuiteDescriptors.h>
+#include <AssetSuite/AssetSuiteHandles.h>
+#include <AssetSuite/AssetSuiteTypes.h>
+
+#include <cstdint>
+#include <filesystem>
+#include <vector>
+
+namespace AssetSuite::Internal
+{
+	struct BlobSourceMetadata final
+	{
+		std::filesystem::path sourcePath;
+		std::filesystem::path extension;
+		AssetFormat format = AssetFormat::Unknown;
+	};
+
+	class Blob final
+	{
+	public:
+		Blob(std::vector<uint8_t> bytes, BlobSourceMetadata metadata);
+
+		Blob(const Blob&) = delete;
+		Blob& operator=(const Blob&) = delete;
+		Blob(Blob&&) noexcept;
+		Blob& operator=(Blob&&) noexcept;
+
+		const uint8_t* Data() const noexcept;
+		uint64_t ByteSize() const noexcept;
+		const BlobSourceMetadata& SourceMetadata() const noexcept;
+		BlobDesc Describe() const noexcept;
+
+	private:
+		std::vector<uint8_t> bytes;
+		BlobSourceMetadata metadata;
+	};
+
+	BlobSourceMetadata MakeBlobSourceMetadata(const std::filesystem::path& sourcePath);
+}
+
+namespace AssetSuite
+{
+	struct AssetSuiteBlob_t
+	{
+	};
+}

source/runtime/AssetSuiteRuntime.cpp

@@ -49,6 +49,18 @@ AssetSuite::Internal::RuntimeContext::FileLoader() noexcept
 	return state.fileLoader;
 }
 
+AssetSuite::Internal::RuntimeState::BlobStorage&
+AssetSuite::Internal::RuntimeContext::BlobStorage() noexcept
+{
+	return state.blobStorage;
+}
+
+const AssetSuite::Internal::RuntimeState::BlobStorage&
+AssetSuite::Internal::RuntimeContext::BlobStorage() const noexcept
+{
+	return state.blobStorage;
+}
+
 AssetSuite::Internal::RuntimeState::CodecRegistry&
 AssetSuite::Internal::RuntimeContext::CodecRegistry() noexcept
 {

source/runtime/AssetSuiteRuntime.h

@@ -23,6 +23,8 @@ namespace AssetSuite::Internal
 		RuntimeState::Diagnostics& Diagnostics() noexcept;
 		const RuntimeState::Diagnostics& Diagnostics() const noexcept;
 		RuntimeState::FileLoader& FileLoader() noexcept;
+		RuntimeState::BlobStorage& BlobStorage() noexcept;
+		const RuntimeState::BlobStorage& BlobStorage() const noexcept;
 		RuntimeState::CodecRegistry& CodecRegistry() noexcept;
 		const RuntimeState::CodecRegistry& CodecRegistry() const noexcept;