MayaFlux::Portal::Graphics::TextureLoom Class Reference

Portal-level texture creation and management. More...

#include <TextureLoom.hpp>

Collaboration diagram for MayaFlux::Portal::Graphics::TextureLoom:

Public Member Functions
std::shared_ptr< Core::VKImage >	acquire_cached_image (ImageCacheEntry &entry, const ImageKey &key)
	Reuse a matching image in an owner-held entry or create it once.
bool	blit_layer (const std::shared_ptr< Core::VKImage > &src, const std::shared_ptr< Core::VKImage > &dst, const LayerBlit &blit={}, bool deferred=false)
	Copy a layer of one image into a layer of another, scaling to fit.
bool	can_blit (const std::shared_ptr< Core::VKImage > &src, const std::shared_ptr< Core::VKImage > &dst, FilterMode filter=FilterMode::LINEAR) const
	Whether the device can blit between two images with a filter.
std::shared_ptr< Core::VKImage >	create_2d (const Kakshya::DataVariant &variant, uint32_t width, uint32_t height, ImageFormat format=ImageFormat::RGBA32F)
	Create a 2D texture from a DataVariant in one shot.
std::shared_ptr< Core::VKImage >	create_2d (uint32_t width, uint32_t height, ImageFormat format=ImageFormat::RGBA8, const void *data=nullptr, uint32_t mip_levels=1)
	Create a 2D texture.
std::shared_ptr< Core::VKImage >	create_2d_array (uint32_t width, uint32_t height, uint32_t layers, ImageFormat format=ImageFormat::RGBA8, const void *data=nullptr)
	Create a 2D texture array.
std::shared_ptr< Core::VKImage >	create_2d_uninitialized (uint32_t width, uint32_t height, ImageFormat format=ImageFormat::RGBA8, uint32_t mip_levels=1)
	Allocate a 2D texture without uploading data or transitioning its layout - left VK_IMAGE_LAYOUT_UNDEFINED.
std::shared_ptr< Core::VKImage >	create_3d (uint32_t width, uint32_t height, uint32_t depth, ImageFormat format=ImageFormat::RGBA8, const void *data=nullptr)
	Create a 3D texture (volumetric)
std::shared_ptr< Core::VKImage >	create_cubemap (uint32_t size, ImageFormat format=ImageFormat::RGBA8, const void *data=nullptr)
	Create a cubemap texture.
std::shared_ptr< Core::VKImage >	create_depth_buffer (uint32_t width, uint32_t height, bool with_stencil=false)
	Create a depth buffer.
std::shared_ptr< Core::VKImage >	create_render_target (uint32_t width, uint32_t height, ImageFormat format=ImageFormat::RGBA8)
	Create a render target (color attachment)
std::shared_ptr< Core::VKImage >	create_storage_image (uint32_t width, uint32_t height, ImageFormat format=ImageFormat::RGBA8)
	Create a storage image (compute shader read/write)
void	download_data (const std::shared_ptr< Core::VKImage > &image, void *data, size_t size, const std::shared_ptr< Buffers::VKBuffer > &staging, bool deferred=false, vk::ImageLayout restore_layout=vk::ImageLayout::eShaderReadOnlyOptimal, vk::PipelineStageFlags restore_stage=vk::PipelineStageFlagBits::eFragmentShader)
	Download pixel data from a VKImage, reusing a caller-supplied persistent staging buffer.
std::optional< Kakshya::ImageData >	download_image (const std::shared_ptr< Core::VKImage > &image, const std::shared_ptr< Buffers::VKBuffer > &staging=nullptr, vk::ImageLayout restore_layout=vk::ImageLayout::eShaderReadOnlyOptimal, vk::PipelineStageFlags restore_stage=vk::PipelineStageFlagBits::eFragmentShader)
	Download the base level of an image as typed pixels.
vk::Sampler	get_default_sampler ()
	Get a default linear sampler (for convenience)
vk::Sampler	get_nearest_sampler ()
	Get a default nearest sampler (for pixel-perfect sampling)
vk::Sampler	get_or_create_sampler (const SamplerConfig &config)
	Get or create a sampler with the given configuration.
bool	initialize (const std::shared_ptr< Core::VulkanBackend > &backend)
	Initialize texture manager.
bool	is_initialized () const
	Check if manager is initialized.
TextureLoom &	operator= (const TextureLoom &)=delete
TextureLoom &	operator= (TextureLoom &&) noexcept=default
std::shared_ptr< Core::VKImage >	refresh_cached_image (ImageCacheEntry &entry, const ImageKey &key, std::span< const uint8_t > pixels, const std::shared_ptr< Buffers::VKBuffer > &staging={})
	Refresh a sampled image in an owner-held cache entry.
void	shutdown ()
	Shutdown and cleanup all textures.
	TextureLoom (const TextureLoom &)=delete
	TextureLoom (TextureLoom &&) noexcept=default
void	transition_layout (const std::shared_ptr< Core::VKImage > &image, vk::ImageLayout old_layout, vk::ImageLayout new_layout, uint32_t mip_levels=1, uint32_t array_layers=1, vk::ImageAspectFlags aspect_mask=vk::ImageAspectFlagBits::eColor)
	Transition a VKImage to a new Vulkan layout via an immediate submission.
void	upload_data (const std::shared_ptr< Core::VKImage > &image, const void *data, size_t size)
	Upload pixel data to an existing texture.
void	upload_data (const std::shared_ptr< Core::VKImage > &image, const void *data, size_t size, const std::shared_ptr< Buffers::VKBuffer > &staging, bool deferred=false)
	Upload pixel data reusing a caller-supplied persistent staging buffer.
bool	upload_layer (const std::shared_ptr< Core::VKImage > &image, uint32_t layer, const void *data, size_t size, const std::shared_ptr< Buffers::VKBuffer > &staging=nullptr, bool deferred=false)
	Upload pixels into one layer of an array image.

Static Public Member Functions
static size_t	calculate_image_size (uint32_t width, uint32_t height, uint32_t depth, ImageFormat format)
	Calculate image data size.
static std::optional< ImageFormat >	from_vulkan_format (vk::Format vk_format)
	Convert Vulkan format to Portal ImageFormat.
static size_t	get_bytes_per_pixel (ImageFormat format)
	Get bytes per pixel for a format.
static uint32_t	get_channel_count (ImageFormat format)
	Get the number of color channels for a given format.
static TextureLoom &	instance ()
static std::optional< ImageFormat >	readable_format (const std::shared_ptr< Core::VKImage > &image)
	ImageFormat of an image that can be read back as one flat block.
static vk::Format	to_vulkan_format (ImageFormat format)
	Convert Portal ImageFormat to Vulkan format.
static std::optional< ImageFormat >	writable_format (const std::shared_ptr< Core::VKImage > &image)
	ImageFormat of an image that can be written as one flat block.

Private Member Functions
vk::Sampler	create_sampler (const SamplerConfig &config)
	TextureLoom ()=default
	~TextureLoom ()

Static Private Member Functions
static size_t	hash_sampler_config (const SamplerConfig &config)
static std::optional< ImageFormat >	transfer_format (const std::shared_ptr< Core::VKImage > &image, vk::ImageUsageFlagBits required_usage)

Private Attributes
std::shared_ptr< Core::VulkanBackend >	m_backend
Core::BackendResourceManager *	m_resource_manager = nullptr
std::unordered_map< size_t, vk::Sampler >	m_sampler_cache
std::vector< std::shared_ptr< Core::VKImage > >	m_textures

Static Private Attributes
static bool	s_initialized = false

Detailed Description

Portal-level texture creation and management.

TextureLoom is the primary Portal::Graphics class for creating and managing GPU textures. It bridges between user-friendly Portal API and backend VKImage resources via BufferService registry.

Key Responsibilities:

• Create textures (2D, 3D, cubemaps, render targets)
• Load textures from files (delegates to IO namespace)
• Manage sampler objects (filtering, addressing)
• Track texture lifecycle for cleanup
• Provide convenient format conversions

Design Philosophy:

• Manages creation, NOT rendering (that's Pipeline/RenderPass)
• Returns VKImage directly (no wrapping yet)
• Simple, focused API (file loading deferred to IO)
• Integrates with BufferService for backend independence

Usage: auto& mgr = Portal::Graphics::TextureLoom::instance();

// Create basic texture auto texture = mgr.create_2d(512, 512, ImageFormat::RGBA8);

// Create with data std::vector<uint8_t> pixels = {...}; auto texture = mgr.create_2d(512, 512, ImageFormat::RGBA8, pixels.data());

// Create render target auto target = mgr.create_render_target(1920, 1080);

// Get sampler SamplerConfig config; config.mag_filter = FilterMode::LINEAR; auto sampler = mgr.get_or_create_sampler(config);

Definition at line 105 of file TextureLoom.hpp.

---

The documentation for this class was generated from the following files:

• TextureLoom.hpp
• TextureLoom.cpp