#include <StreamingImage.h>
Inherits AZ::RPI::Image, and AZ::Data::AssetBus::MultiHandler.
Public Types | |
| using | Priority = uint64_t |
| Returns the image's streaming priority. | |
Public Member Functions | |
| AZ_INSTANCE_DATA (StreamingImage, "{E48A7FF0-3065-42C6-9673-4FE7C8905629}", Image) | |
| AZ_CLASS_ALLOCATOR (StreamingImage, SystemAllocator) | |
| void | SetTargetMip (uint16_t targetMipLevel) |
| const Data::Instance< StreamingImagePool > & | GetPool () const |
| bool | IsStreamable () const |
| Returns whether the streaming image is allowed to evict or expand mip chains. | |
| RHI::ResultCode | TrimToMipChainLevel (size_t mipChainLevel) |
| RHI::ResultCode | TrimOneMipChain () |
| Trims the highest res mip chain from current resident mipchains. | |
| void | QueueExpandToMipChainLevel (size_t mipChainLevel) |
| void | QueueExpandToNextMipChainLevel () |
| Queues an expansion to the mip chain that is one level higher than the resident mip chain. | |
| void | CancelExpanding () |
| Cancel ongoing mip expanding. | |
| RHI::ResultCode | ExpandMipChain () |
| uint16_t | GetResidentMipLevel () |
| Returns the most detailed mip level currently resident in memory, where a value of 0 is the highest detailed mip. | |
| Color | GetAverageColor () const |
| Returns the average color of this image (alpha-weighted in case of 4-component images). | |
| Priority | GetStreamingPriority () const |
| void | SetStreamingPriority (Priority priority) |
| Set the image's streaming priority. | |
| bool | IsTrimmable () const |
| Returns whether the image has mipchains which can be evicted from device memory. | |
| bool | IsExpanding () const |
| bool | IsStreamed () const |
 Public Member Functions inherited from AZ::RPI::Image | |
| AZ_INSTANCE_DATA (Image, "{4E4B1092-1BEE-4DC4-BE4B-8FBC83B0F48C}") | |
| AZ_CLASS_ALLOCATOR (Image, AZ::SystemAllocator) | |
| bool | IsInitialized () const |
| Returns whether Image is currently initialized. | |
| RHI::Image * | GetRHIImage () |
| Returns the mutable GPU image instance initialized at asset load time. | |
| const RHI::Image * | GetRHIImage () const |
| Returns the immutable GPU image instance initialized at asset load time. | |
| const RHI::ImageView * | GetImageView () const |
| Returns the default image view instance, mapping the full (resident) image. | |
| const RHI::ImageDescriptor & | GetDescriptor () const |
| Returns the image descriptor which contains some image information. | |
| uint16_t | GetMipLevelCount () |
| Returns the number of mip levels of this image. | |
| virtual RHI::ResultCode | UpdateImageContents (const RHI::ImageUpdateRequest &request) |
| Updates content of a single sub-resource in the image from the CPU. | |
Static Public Member Functions | |
| static Data::Instance< StreamingImage > | FindOrCreate (const Data::Asset< StreamingImageAsset > &streamingImageAsset) |
| Instantiates or returns an existing streaming image instance using its paired asset. | |
| static Data::Instance< StreamingImage > | CreateFromCpuData (const StreamingImagePool &streamingImagePool, RHI::ImageDimension imageDimension, RHI::Size imageSize, RHI::Format imageFormat, const void *imageData, size_t imageDataSize, Uuid id=Uuid::CreateRandom()) |
| Helper method to instantiate a single-mip, single array streaming image from CPU data. | |
Friends | |
| class | ImageSystem |
| class | StreamingImageController |
| class | StreamingImageContext |
Additional Inherited Members | |
| Protected Attributes inherited from AZ::RPI::Image | |
| RHI::Ptr< RHI::Image > | m_image |
| RHI::Ptr< RHI::ImageView > | m_imageView |
Detailed Description
A runtime streaming image, containing GPU data and streaming state. StreamingImage is the runtime instance of a StreamingImageAsset. Both are immutable (on GPU and CPU, respectively), and thus should remain 1-to-1. StreamingImage connects to its parent pool and parent streaming controller. The pool provides the allocation context for the RHI image. The controller provides the logic for streaming events based on priority and budget.
STREAMING CONTROLLER USAGE: StreamingImage exposes an internal API to the streaming controller. Its the sole responsibility of the controller to fetch and evict mip chains from the streaming image, as this is the only system with enough context to budget properly.
Streaming works like a cache hierarchy. The GPU is the final 'L0' cache, the CPU is the 'L1' cache, and the disk is 'L2'. The GPU image allocation grows or shrinks to fit a target mip level. When expanding the image, the controller fetches mips from disk, using 'QueueExpandToMipChainLevel'. This establishes a connection with the asset system, which begins asynchronously streaming content from disk. When content arrives in CPU memory, the image queues itself on the controller for expansion. The expansion operation is done at a specific time in the streaming phase of the controller, in order to make uploads deterministic.
A trim operation will immediately trim the GPU image down and cancel any in-flight mip chain fetches.
Member Function Documentation
◆ ExpandMipChain()
| RHI::ResultCode AZ::RPI::StreamingImage::ExpandMipChain | ( | ) |
Performs the GPU mip chain expansion for any contiguous range of ready (loaded) mip chain assets. Returns the result of the RHI pool residency update. If no new mip chains are available, this will no-op and return success.
◆ IsExpanding()
| bool AZ::RPI::StreamingImage::IsExpanding | ( | ) | const |
Returns whether the image is expanding its mipmaps This is true when any queue expand functions (asset requested) are called until the mipmap expand requested are submitted successfully
◆ IsStreamed()
| bool AZ::RPI::StreamingImage::IsStreamed | ( | ) | const |
Returns whether the image is fully streamed to the GPU. For non-streamable image, all its mipmap should be resident. For streamable image, its target mip should be resident. (The target mip can be affected by streaming image controller's mip bias)
◆ QueueExpandToMipChainLevel()
| void AZ::RPI::StreamingImage::QueueExpandToMipChainLevel | ( | size_t | mipChainLevel | ) |
Queues an expansion operation which fetches mip chain assets from disk. Each time a contiguous range of mip chain assets are ready, an expansion is triggered for non-streamable image or is queued on the parent controller for streamable image.
◆ SetTargetMip()
| void AZ::RPI::StreamingImage::SetTargetMip | ( | uint16_t | targetMipLevel | ) |
Requests the image mips be made available. A value of 0 is the most detailed mip level. The value is clamped to the last mip in the chain.
◆ TrimToMipChainLevel()
| RHI::ResultCode AZ::RPI::StreamingImage::TrimToMipChainLevel | ( | size_t | mipChainLevel | ) |
Trims the image to (and including) the requested mip chain index. Mip chains of higher detail than the requested mip chain are evicted from the GPU and any in-flight fetch requests are aborted.
- Parameters
-
mipChainLevel The index of the mip chain (where 0 is most detailed) to target.
The documentation for this class was generated from the following file:
- Gems/Atom/RPI/Code/Include/Atom/RPI.Public/Image/StreamingImage.h
