AI/rocm-systems
2
0
フォーク 0
コード イシュー プルリクエスト Actions パッケージ プロジェクト リリース Wiki アクティビティ
ファイル
865a8d4d59814ca00b6e8ca6ee3ae7901acad2f0
rocm-systems/shared/amdgpu-windows-interop/pal/inc/core/palImage.h
T

.git-blame-ignore-revs で指定されたリビジョンは除外しています。 これを迂回して通常のBlame表示を見るには ここをクリック。

984 行
56 KiB
C++
Raw 通常表示 履歴

Revert "Update amdgpu-windows-interop with latest changes (#1718)" (#1725)
2025-11-05 15:38:23 -05:00
/*
***********************************************************************************************************************
*
* Copyright (c) 2014-2025 Advanced Micro Devices, Inc. All Rights Reserved.
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to deal
* in the Software without restriction, including without limitation the rights
* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
* copies of the Software, and to permit persons to whom the Software is
* furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice shall be included in all
* copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
* SOFTWARE.
*
**********************************************************************************************************************/
/**
***********************************************************************************************************************
* @file palImage.h
* @brief Defines the Platform Abstraction Library (PAL) IImage interface and related types.
***********************************************************************************************************************
*/
#pragma once
#include "pal.h"
#include "palGpuMemoryBindable.h"
namespace Pal
{
// Forward declarations.
class IImage;
class IPrivateScreen;
class IScreen;
class ISwapChain;
enum class CompressionMode : uint32;
enum class ClientCompressionMode : uint32;
enum SwizzleMode : uint32;
struct ImageCopyRegion;
/// When used as the value of the viewFormatCount parameter of image creation it indicates that all compatible formats
/// can be used for views of the created image.
constexpr uint32 AllCompatibleFormats = UINT32_MAX;
/// Specifies dimensionality of an image (i.e., 1D, 2D, or 3D).
enum class ImageType : uint32
{
Tex1d = 0x0,
Tex2d = 0x1,
Tex3d = 0x2,
Count
};
/// Specifies the tiling (address swizzling) to use for an image. When a linear tiled image is mapped its contents will
/// be laid out in row-major ordering. All other tiling modes require the use of swizzles equation to locate texels.
enum class ImageTiling : uint32
{
Linear = 0x0, ///< Image is laid out in scan-line (row-major) order.
Optimal = 0x1, ///< Image is laid out in a GPU-optimal order.
Standard64Kb = 0x2, ///< Image is laid out in the cross-IHV, 64KB, standard swizzle tiling.
Count
};
/// Hints to pal to identify a preference for how this image is organized. This is a preference setting, and may be
/// ignored if pal believes better options exist.
enum class ImageTilingPattern : uint32
{
Default = 0x0, ///< No swizzle mode is preferred.
Standard = 0x1, ///< Prefer standard swizzle modes.
XMajor = 0x2, ///< Prefer x-coordinate major swizzle modes.
YMajor = 0x3, ///< Prefer y-coordinate major swizzle modes.
Interleaved = 0x4, ///< Prefer interleaved coordinate swizzle modes.
Count
};
/// Hints to pal to select the appropriate tiling mode for a optimization target.
enum class TilingOptMode : uint32
{
Balanced = 0x0, ///< Balance memory foorprint and rendering performance.
OptForSpace = 0x1, ///< Optimize tiling mode for saving memory footprint
OptForSpeed = 0x2, ///< Optimize tiling mode for rendering performance.
Count
};
/// Image metadata modes.
enum class MetadataMode : uint16
{
Default = 0, ///< Default behavior. PAL chooses if metadata should be present or not.
ForceEnabled, ///< Optimization Hint: The client would prefer Metadata if possible. Useful for scenarios where
/// metadata isn't an obvious win and clients can enable based on some hueristic or app-detect.
Disabled, ///< The Image will not contain any compression metadata.
FmaskOnly, ///< The color msaa Image will only contain Cmask/Fmask metadata; this mode is only valid for color
/// msaa Image. On GPUs with GFX12-style distributed compression (see supportDistributedCompression
/// flag in @ref DeviceProperties), metadataMode only controls UMD metadata (Hi-Z and Hi-S). On such
/// GPUs, the FmaskOnly enum is ignored and treated like Default.
Count,
};
/// Image metadata TC compat modes.
enum class MetadataTcCompatMode : uint16
{
Default = 0, ///< Default behavior. PAL chooses if TC compat should be enabled (if compressed).
ForceEnabled, ///< Optimization Hint: Tells PAL that the client would prefer Metadata is TC compat.
Disabled, ///< Optimization Hint: Tells PAL that the client would prefer Metadata is not TC compat.
Count,
};
/// Image shared metadata support level
enum class MetadataSharingLevel : uint32
{
FullExpand = 0, ///< The metadata need to be fully expanded at ownership transition time.
ReadOnly = 1, ///< The metadata are expected to have read-only usage after the ownership is transitioned.
FullOptimal = 2, ///< The metadata can remain as-is if possible at ownership transition time.
};
/// Specifies the type of PRT map image being created.
enum class PrtMapType : uint32
{
None = 0, ///< This is not an auxillary image used for PRT plus functionality.
Residency = 1, ///< Image data is really a low-resolution map containing the finest populated LOD
/// for a particular UV space region.
SamplingStatus = 2, ///< Indicates the validity of a given tile on a per-mip level basis.
Count,
};
/// Specifies how to interpret a clear color.
enum class ClearColorType : uint32
{
Uint = 0, ///< The color is stored as an unsigned integer in RGBA order in u32Color. It will be swizzled and
/// compacted before it is written to memory.
Sint = 1, ///< The color is stored as a signed integer in RGBA order in i32Color. It will be swizzled and
/// compacted before it is written to memory.
Float = 2, ///< The color is stored as floating point in RGBA order. It will be swizzled and converted to the
/// appropriate numeric format before it is written to memory.
Yuv = 3, ///< The color is stored as an unsigned integer in YUVA order in u32Color. It will be swizzled and
/// compacted before it is written to memory. The client must clamp the clear color within the
/// valid range, e.g. [0, 255] for 8-bit.
Count
};
/// Contains everything necessary to store and interpret a clear color.
struct ClearColor
{
ClearColorType type; ///< How to interpret this clear color.
uint8 disabledChannelMask; ///< This 4 bits are used to selectively disable the A,B,G,R channels
/// from being written. 0 means write ABRG. 0xF means write nothing.
/// 0x8 means write Blue, Green, Red. 0x7 means write Alpha. etc...
union
{
uint32 u32Color[4]; ///< The clear color, interpreted as four unsigned integers.
float f32Color[4]; ///< The clear color, interpreted as four floating point values.
};
};
/// Specifies a set of image creation flags.
union ImageCreateFlags
{
struct
{
uint32 invariant : 1; ///< Images with this flag set and all other creation identical are
/// guaranteed to have a consistent data layout.
uint32 cloneable : 1; ///< Image is valid as a source or destination of a clone operation.
/// See @ref IDevice::ImagePrefersCloneCopy() for more details.
uint32 shareable : 1; ///< Image can be shared between compatible devices.
uint32 presentable : 1; ///< Indicates this image can be used in presents.
uint32 flippable : 1; ///< Image can be used for flip presents.
uint32 stereo : 1; ///< Indicates AMD quad buffer stereo extension (AQBS extension) image
uint32 dxgiStereo : 1; ///< Indicates DXGI stereo (Win8 stereo) image
uint32 cubemap : 1; ///< Image will be used as a cubemap.
uint32 prt : 1; ///< Image is a partially resident texture (aka, sparse image or tiled
/// resource)
uint32 needSwizzleEqs : 1; ///< Image requires valid swizzle equations.
uint32 perSubresInit : 1; ///< The image may have its subresources initialized independently using
/// barrier calls out of the uninitialized layout.
uint32 separateDepthPlaneInit : 1; ///< If set, the caller may transition the stencil and depth planes from
/// "Uninitialized" state at any time. Otherwise, both planes must be
/// transitioned in the same barrier call. Only meaningful if
/// "perSubresInit" is set.
uint32 repetitiveResolve : 1; ///< Optimization: Is this image resolved multiple times to an image which
/// is mostly similar to this image?
uint32 preferSwizzleEqs : 1; ///< Image prefers valid swizzle equations, but an invalid swizzle
/// equation is also acceptable.
uint32 fixedTileSwizzle : 1; ///< Fix this image's tile swizzle to ImageCreateInfo::tileSwizzle. This
/// is only supported for single-sampled color images.
uint32 videoReferenceOnly : 1; ///< Image is used by video hardware for reference buffer only.
/// It uses a different tiling format than the decoder output buffer.
uint32 optimalShareable : 1; ///< Indicates metadata information is to be added into private data on
/// creation time and honored on open time.
uint32 sampleLocsAlwaysKnown : 1; ///< Sample pattern is always known in client driver for MSAA depth image.
uint32 fullResolveDstOnly : 1; ///< Indicates any ICmdBuffer::CmdResolveImage using this image as a
/// desination will overwrite the entire image (width and height of
/// resolve region is same as width and height of resolve dst).
uint32 fullCopyDstOnly : 1; ///< Indicates any copy to this image will overwrite the entire image.
/// A perf optimization of using post-copy metadata fixup to replace heavy
/// expand at barrier to LayoutCopyDst. Unsafe to enable it if there is
/// potential partial copy to the image.
uint32 pipSwapChain : 1; ///< Indicates this image is PIP swap-chain. It is only supported on
/// Windows platforms.
uint32 view3dAs2dArray : 1; ///< If set client can view 3D image as 2D with its depth as array slices.
/// Note that not all 3D images supports it. The image creation will
/// return error if we fail to create a compatible image.
uint32 tmzProtected : 1; ///< Indicate this image is protected or not.
uint32 sharedWithMesa : 1; ///< Indicate this Image was opened from a Mesa shared Image
uint32 enable256KBSwizzleModes : 1; ///< Enable 256 KiB swizzle modes
uint32 hasModifier : 1; ///< Set if the image uses drm format modifier.
uint32 disableDccStateTracking : 1; ///< Disable a PAL optimization which is commonly broken by app bugs.
/// Setting this flag may increase DCC decompress overhead.
#if PAL_CLIENT_EXAMPLE
uint32 useFixedSwizzleMode : 1; ///< If set, require the fixed swizzle mode provided.
/// Fails creation on incompatible swizzles.
#else
uint32 reservedSwMode : 1; ///< Reserved for future use.
#endif
uint32 reserved : 4; ///< Reserved for future use.
};
uint32 u32All; ///< Flags packed as 32-bit uint.
};
/// Specifies a set of ways an image might be used by the GPU (color target, shader read, etc.).
union ImageUsageFlags
{
struct
{
uint32 shaderRead : 1; ///< Image will be read from shader (i.e., texture).
uint32 shaderWrite : 1; ///< Image will be written from a shader (i.e., UAV).
uint32 resolveSrc : 1; ///< Image will be used as resolve source image
uint32 resolveDst : 1; ///< Image will be used as resolve dst image
uint32 colorTarget : 1; ///< Image will be bound as a color target.
uint32 depthStencil : 1; ///< Image will be bound as a depth/stencil target.
uint32 noStencilShaderRead : 1; ///< Image will be neither read as stencil nor resolved on stencil plane.
/// Note that if resolveSrc bit has been set to indicate that the image
/// could be adopted as a resolveSrc image and there could be stencil
/// resolve, noStencilShaderRead must be set to 0, since shader-read
/// based stencil resolve might be performed.
uint32 hiZNeverInvalid : 1; ///< Hint to PAL indicating the client will guarantee that no operations
/// performed on this Image while it is in a decompressed state will cause
/// Hi-Z metadata to become invalid. This allows PAL to avoid an expensive
/// resummarization blit in some resource barriers.
uint32 depthAsZ24 : 1; ///< Use a 24-bit format for HW programming of a native 32-bit surface.
/// If set, border color and Z-reference values are treated as Z-24.
uint32 firstShaderWritableMip : 4; ///< Only relevant if the shaderWrite flag is set. Typically set to 0 so
/// entire image is writable. If non0, such as an image where only level0
/// is used as a color target and compute is used to generate mipmaps,PAL
/// may be able to enable additional compression on the baseLevels which
/// are used exclusively as color target and shader read.
uint32 cornerSampling : 1; ///< Set if this image will use corner sampling in image-read scenarios.
/// With corner sampling, the extent refers to the number of pixel corners
/// which will be one more than the number of pixels. Border color is
/// ignored when corner sampling is enabled.
uint32 vrsDepth : 1; ///< Set if this depth image will be bound when VRS rendering is enabled.
uint32 disableOptimizedDisplay: 1; ///< Do not create Display Dcc
uint32 useLossy : 1; ///< Set if this image may use lossy compression.
uint32 stencilOnlyTarget : 1; ///< This must be set if a stencil-only IDepthStencilView will be created
///< for this image.
uint32 vrsRateImage : 1; ///< This image is potentially used with CmdBindSampleRateImage
uint32 videoDecoder : 1; ///< Indicating this Image is video decoder target
uint32 reserved : 12; ///< Reserved for future use.
};
uint32 u32All; ///< Flags packed as 32-bit uint.
};
/// Specifies properties for @ref IImage creation. Input structure to IDevice::CreateImage().
///
/// Note that by default PAL may instruct the hardware to swizzle the contents of an image in memory; if this occurs
/// two images created with identical properties will not map their texels to the same offsets in GPU memory and may
/// even have different sizes. At the expense of performance this behavior can be limited by setting the invariant flag,
/// which guarantees that images with identical properties will have identical GPU memory layouts.
///
/// For single-sampled color images, there is a middle ground between these two modes. If the fixedTileSwizzle flag is
/// set, PAL will use the tileSwizzle property instead of generating its own swizzle value. The tileSwizzle value must
/// be obtained from the base subresource of a single-sampled color image with identical properties (excluding
/// fixedTileSwizzle and tileSwizzle). This allows the client to force certain similar images to share the same GPU
/// memory layouts without forcing all similar images to a single GPU memory layout.
struct ImageCreateInfo
{
ImageCreateFlags flags; ///< Image creation flags.
ImageUsageFlags usageFlags; ///< Image usage flags.
ImageType imageType; ///< Dimensionality of image (1D/2D/3D).
SwizzledFormat swizzledFormat; ///< Pixel format and channel swizzle.
Extent3d extent; ///< Dimensions in pixels WxHxD.
uint32 mipLevels; ///< Number of mipmap levels. Cannot be 0.
uint32 arraySize; ///< Number of slices. Set to 1 for non-array images.
uint32 samples; ///< Number of coverage samples. Set to 1 for single sample images. Must be
/// greater than or equal to the number of fragments.
uint32 fragments; ///< Number of color/depth fragments. Set to 1 for single sample images.
ImageTiling tiling; ///< Controls layout of pixels in the image.
ImageTilingPattern tilingPreference; ///< Controls preferred tile swizzle organization for this image.
TilingOptMode tilingOptMode; ///< Hints to pal to select the appropriate tiling mode.
uint32 tileSwizzle; ///< If fixedTileSwizzle is set, use this value for the image's base swizzle.
#if PAL_CLIENT_EXAMPLE
SwizzleMode fixedSwizzleMode; ///< For directed image tests, force a particular swizzle mode.
#endif
/// Metadata behavior mode for this image. On GPUs with GFX12-style distributed compression
/// (see supportDistributedCompression flag in @ref DeviceProperties), metadataMode only controls UMD metadata
/// (Hi-Z and Hi-S). On such GPUs, the FmaskOnly enum is ignored and treated like Default.
MetadataMode metadataMode;
MetadataTcCompatMode metadataTcCompatMode; ///< TC compat mode for this image.
/// Distributed compression contains GL2/DF DCC compression and RB backend client compression which includes
/// fragment client compression (previous FMASK compression alike) on color MSAA images and Z Plane client
/// compression on depth stencil images. Only relevant if the backing memory pages enable compression, controllable
/// by client with @ref GpuMemoryCreateInfo::compression.
CompressionMode compressionMode;
#if PAL_CLIENT_INTERFACE_MAJOR_VERSION >= 876
/// Client compression is part of distributed compression (aka physical compression); it can only be enabled if
/// physical compression is enabled.
///
/// On Gfx12, controls (legacy FMask based) color fragment compression and Z plane compression.
ClientCompressionMode clientCompressionMode; ///< Controls client compression behavior for this resource.
#else
TriState clientCompressionMode; ///< Controls client compression behavior for this resource.
#endif
uint32 maxBaseAlign; ///< Maximum address alignment for this image or zero for an unbounded alignment.
float imageMemoryBudget; ///< The memoryBudget value used in SW addrlib to determine the minSizeBlk for textures.
/// It must be >= 0.0. When in [0.0, 1.0) addrlib uses legacy logic to decide minSizeBlk.
/// When == 1.0, addrlib uses minimizeAlign. When > 1.0, addrlib applies memory budget
/// algorithm. Despite 1.5 in tests show significant texture allocation size reduction,
/// default value 0.0 (legacy behavior) is recommended if not specified by client.
struct
{
PrtMapType mapType; ///< Indicates what sort of PRT metadata is stored in this image. If this image is PRT
/// metadata, then it can only be associated with an image that is a power-of-two
/// multiple bigger (or the same size). Image properties needs to include
/// "PrtFeaturePrtPlus" to create PRT map images. Format must be set to X8_Unorm for
/// residency map and sampling-status map types.
Extent3d lodRegion; ///< Useful only if mapType is not "none". Defines the region size of the parent image
/// that one pixel of this image matches with. The map image can only be paired with a
/// parent image of matching dimensions. This parameter can be left at zero.
} prtPlus;
/// The following "pitch" members must be zeroed unless the client is creating a @ref ImageTiling::Linear image and
/// wishes to directly specify the image's row and depth pitches. In that case, they must be integer multiples of
/// the alignments given by @ref IDevice::GetLinearImageAlignments, called with an appropriate maxElementSize.
uint32 rowPitch; ///< The image must have this row pitch for the first mip level (in bytes).
uint32 depthPitch; ///< The image must have this depth pitch for the first mip level (in bytes).
Rational refreshRate; ///< The expected refresh rate when presenting this flippable or stereo image.
/// By default an image can only be used with image views that exactly match @ref swizzledFormat (the base format).
/// If the client wishes to create image views with other formats they must fill out the following fields.
///
/// Valid combinations of these fields include:
/// - pViewFormats = nullptr, viewFormatCount = 0: all image views must use the base format.
/// - pViewFormats = nullptr, viewFormatCount = AllCompatibleFormats: image views can use any compatible formats.
/// - Otherwise pViewFormats is an array of additional image view formats (excluding the base format) and
/// viewFormatCount is the length of that array.
///
/// @warning pViewFormats is consumed at image creation time and should not be accessed afterwards through
/// @ref GetImageCreateInfo.
uint32 viewFormatCount; ///< Must be 0, AllCompatibleFormats, or the length of pViewFormats.
const SwizzledFormat* pViewFormats; ///< See the block comment above for a full description.
#if defined(__unix__)
uint64 modifier; ///< Drm format modifier. Ignored if flags.hasModifier unset.
uint32 modifierPlaneCount; ///< Number of memory planes of drm format modifier.
gpusize modifierMemoryPlaneOffset[3]; ///< Offset of main surface, display Dcc surface and gfx Dcc surface.
#endif
};
inline constexpr bool operator==(const ImageCreateInfo& lhs, const ImageCreateInfo& rhs)
{
bool same = (lhs.flags.u32All == rhs.flags.u32All) &&
(lhs.usageFlags.u32All == rhs.usageFlags.u32All) &&
(lhs.imageType == rhs.imageType) &&
(lhs.swizzledFormat == rhs.swizzledFormat) &&
(lhs.extent == rhs.extent) &&
(lhs.mipLevels == rhs.mipLevels) &&
(lhs.arraySize == rhs.arraySize) &&
(lhs.samples == rhs.samples) &&
(lhs.fragments == rhs.fragments) &&
(lhs.tiling == rhs.tiling) &&
(lhs.tilingPreference == rhs.tilingPreference) &&
(lhs.tilingOptMode == rhs.tilingOptMode) &&
(lhs.tileSwizzle == rhs.tileSwizzle) &&
#if PAL_CLIENT_EXAMPLE
(lhs.fixedSwizzleMode == rhs.fixedSwizzleMode) &&
#endif
(lhs.metadataMode == rhs.metadataMode) &&
(lhs.metadataTcCompatMode == rhs.metadataTcCompatMode) &&
(lhs.compressionMode == rhs.compressionMode) &&
(lhs.clientCompressionMode == rhs.clientCompressionMode) &&
(lhs.maxBaseAlign == rhs.maxBaseAlign) &&
(lhs.imageMemoryBudget == rhs.imageMemoryBudget) &&
(lhs.prtPlus.mapType == rhs.prtPlus.mapType) &&
(lhs.prtPlus.lodRegion == rhs.prtPlus.lodRegion) &&
(lhs.rowPitch == rhs.rowPitch) &&
(lhs.depthPitch == rhs.depthPitch) &&
(lhs.refreshRate.numerator == rhs.refreshRate.numerator) &&
(lhs.refreshRate.denominator == rhs.refreshRate.denominator) &&
(lhs.viewFormatCount == rhs.viewFormatCount) &&
true;
#if defined(__unix__)
if (same && (lhs.flags.hasModifier != 0))
{
same = (lhs.modifier == rhs.modifier) &&
(lhs.modifierPlaneCount == rhs.modifierPlaneCount) &&
(memcmp(&lhs.modifierMemoryPlaneOffset[0],
&rhs.modifierMemoryPlaneOffset[0],
sizeof(gpusize) * lhs.modifierPlaneCount) == 0);
}
#endif
if (same && (lhs.viewFormatCount > 0) && (lhs.viewFormatCount != AllCompatibleFormats))
{
same = (memcmp(lhs.pViewFormats, rhs.pViewFormats, lhs.viewFormatCount * sizeof(SwizzledFormat)) == 0);
}
return same;
}
/// Specifies properties for presentable @ref IImage creation. Input structure to IDevice::CreatePresentableImage().
struct PresentableImageCreateInfo
{
union
{
struct
{
uint32 fullscreen : 1; ///< Image supports fullscreen presentation.
uint32 stereo : 1; ///< Image supports stereoscopic rendering and display.
/// Implies an array size of 2. Fullscreen must be set.
uint32 turbosync : 1; ///< Image supports turbosync flip
uint32 peerWritable : 1; ///< Indicates if the memory allocated will be writable by other devices
uint32 tmzProtected : 1; ///< Indicates this presenatble image's memory is tmz Protected.
#if PAL_AMDGPU_BUILD
uint32 initializeToZero : 1; ///< If set, PAL will request that the host OS zero-initializes
/// the allocation upon creation, currently, only GpuHeapLocal and
/// GpuHeapInvisible are supported.
#else
uint32 placeholder0 : 1; ///< Placeholder.
#endif
uint32 enable256KBSwizzleModes : 1; ///< Enable 256 KiB swizzle modes.
uint32 reserved : 25; ///< Reserved for future use.
};
uint32 u32All; ///< Flags packed as 32-bit uint.
} flags; ///< Presentable image creation flags.
SwizzledFormat swizzledFormat; ///< Pixel format and channel swizzle.
ImageUsageFlags usage; ///< Image usage flags.
Extent2d extent; ///< Width/height of the image.
CompressionMode compressionMode; ///< Specify GFX12-style distributed compression behavior for this resource.
/// Only relevant if the backing memory pages enable compression (controllable by
/// client with the distributedCompression field in @ref GpuMemoryCreateInfo).
const IScreen* pScreen; ///< Target screen for fullscreen presentable images. Can be null if the fullscreen
/// flag is 0.
OsDisplayHandle hDisplay; ///< Display handle of the local display system only for WSI.
OsWindowHandle hWindow; ///< Window handle only for WSI.
ISwapChain* pSwapChain; ///< SwapChain object which the presentable image belongs to.
/// By default an image can only be used with image views that exactly match @ref swizzledFormat (the base format).
/// If the client wishes to create image views with other formats they must fill out the following fields.
///
/// Valid combinations of these fields include:
/// - pViewFormats = nullptr, viewFormatCount = 0: all image views must use the base format.
/// - pViewFormats = nullptr, viewFormatCount = AllCompatibleFormats: image views can use any compatible formats.
/// - Otherwise pViewFormats is an array of additional image view formats (excluding the base format) and
/// viewFormatCount is the length of that array.
///
/// @warning pViewFormats is consumed at image creation time and should not be accessed afterwards through
/// @ref GetImageCreateInfo.
uint32 viewFormatCount; ///< Must be 0, AllCompatibleFormats, or the length of pViewFormats.
const SwizzledFormat* pViewFormats; ///< See the block comment above for a full description.
};
/// Specifies properties for private screen @ref IImage image creation. Input structure to
/// IDevice::CreatePrivateScreenImage().
struct PrivateScreenImageCreateInfo
{
union
{
struct
{
uint32 invariant : 1; ///< Images with this flag set and all other creation identical are guaranteed
/// to have a consistent data layout.
uint32 reserved : 31; ///< Reserved for future use.
};
uint32 u32All; ///< Flags packed as 32-bit uint.
} flags; ///< Private screen image creation flags.
SwizzledFormat swizzledFormat; ///< Pixel format and channel swizzle.
ImageUsageFlags usage; ///< Image usage flags.
Extent2d extent; ///< Width/height of the image.
IPrivateScreen* pScreen; ///< Private screen this image is created on (then this image can be used to be
/// presented on this private screen).
CompressionMode compressionMode;///< Specify GFX12-style distributed compression behavior for this resource.
/// Only relevant if the backing memory pages enable compression (controllable by
/// client with the distributedCompression field in @ref GpuMemoryCreateInfo).
/// By default an image can only be used with image views that exactly match @ref swizzledFormat (the base format).
/// If the client wishes to create image views with other formats they must fill out the following fields.
///
/// Valid combinations of these fields include:
/// - pViewFormats = nullptr, viewFormatCount = 0: all image views must use the base format.
/// - pViewFormats = nullptr, viewFormatCount = AllCompatibleFormats: image views can use any compatible formats.
/// - Otherwise pViewFormats is an array of additional image view formats (excluding the base format) and
/// viewFormatCount is the length of that array.
///
/// @warning pViewFormats is consumed at image creation time and should not be accessed afterwards through
/// @ref GetImageCreateInfo.
uint32 viewFormatCount; ///< Must be 0, AllCompatibleFormats, or the length of pViewFormats.
const SwizzledFormat* pViewFormats; ///< See the block comment above for a full description.
};
/// Specifies parameters for opening another device's image for peer access from this device. Input structure to
/// IDevice::OpenPeerImage().
struct PeerImageOpenInfo
{
const IImage* pOriginalImage; ///< Other device's image to be opened for peer access.
};
/// Specifies parameters for opening another non-PAL device's image for access from this device. Input structure to
/// IDevice::OpenExternalSharedImage().
struct ExternalImageOpenInfo
{
ExternalResourceOpenInfo resourceInfo; ///< Information describing the external image.
Extent3d extent; ///< Expected extent for the external image. This reference value would be
/// ignored and use extents from shared metadata if any dimension of the
/// reference extent is zero.
SwizzledFormat swizzledFormat; ///< Pixel format and channel swizzle. Or UndefinedFormat to infer the
/// format internally.
ImageCreateFlags flags; ///< Image Creation flags.
ImageUsageFlags usage; ///< Image usage flags.
IPrivateScreen* pScreen; ///< Private screen this image is created on, or null.
gpusize gpuMemOffset; ///< GpuMemory offset
#if defined(__unix__)
gpusize dccOffset; ///< Offset of gfx Dcc surface if nonzero.
gpusize displayDccOffset; ///< Offset of display Dcc surface if nonzero.
uint64 modifier; ///< Drm format modifier, if flags.hasModifier is set.
uint32 modifierPlaneCount; ///< Number of memory planes of drm format modifier.
#endif
/// The following members must be set to zero unless the client is opening a @ref ImageTiling::Linear image with
/// specified row and depth pitches. In that case, they must be integer multiples of the alignments given by
/// @ref IDevice::GetLinearImageAlignments, called with an appropriate maxElementSize.
gpusize rowPitch; ///< Offset in bytes between the same X position on two consecutive lines
/// of the subresource.
gpusize depthPitch; ///< Offset in bytes between the same X,Y position of two consecutive
/// slices.
};
/// Reports the overall GPU memory layout of the entire image. Output structure for IImage::GetMemoryLayout(). Unused
/// sections will have a size of zero, an offset of zero, and an alignment of one. The layout is split into:
/// + Image Data: The raw texel values for all subresources of the image.
/// + Image Metadata: Additional data that will be used to optimize GPU operations that access the image.
/// + Image Metadata Header: A special subsection of the metadata for small bits of data with weaker alignment.
struct ImageMemoryLayout
{
gpusize dataSize; ///< The size, in bytes, of the image's core data section.
gpusize dataAlignment; ///< The alignment, in bytes, of the image's core data section.
gpusize metadataOffset; ///< The offset, in bytes, of the image's metadata section.
gpusize metadataSize; ///< The size, in bytes, of the image's metadata section.
gpusize metadataAlignment; ///< The alignment, in bytes, of the image's metadata section.
gpusize metadataHeaderOffset; ///< The offset, in bytes, of the image's metadata header.
gpusize metadataHeaderSize; ///< The size, in bytes, of the image's metadata header.
gpusize metadataHeaderAlignment; ///< The alignment, in bytes, of the image's metadata header.
uint8 swizzleEqIndices[2]; ///< Which swizzle equations this image uses or InvalidSwizzleEqIndex if
/// there are no swizzle equations for this image's layout.
uint8 swizzleEqTransitionMip; ///< Before this mip level, the image uses swizzleEqIndices[0]; from this
/// mip level onwards, the image uses swizzleEqIndices[1].
uint8 swizzleEqTransitionPlane; ///< Before this mip plane, the image uses swizzleEqIndices[0]; from this
/// plane onward, the image uses swizzleEqIndices[1].
uint32 prtTileWidth; ///< Width, in texels, of a PRT tile
uint32 prtTileHeight; ///< Height, in texels, of a PRT tile
uint32 prtTileDepth; ///< Depth, in texels, of a PRT tile
uint32 prtMinPackedLod; ///< First mip level that is packed into the PRT mip tail.
uint32 prtMipTailTileCount; ///< Number of tiles in the packed mip tail. This may either indicate the
/// size per slice or per image depending on the support for
/// PrtFeaturePerLayerMipTail (@see PrtFeatureFlags)
uint32 stereoLineOffset; ///< Y offset to the right eye data, in texels
};
/// Collection of bitmasks specifying which operations are currently allowed on an image, and which queues are allowed
/// to perform those operations. Based on this information, PAL can determine the best compression state of the image.
struct ImageLayout
{
uint32 usages : 24; ///< Bitmask of @ref ImageLayoutUsageFlags values.
uint32 engines : 8; ///< Bitmask of @ref ImageLayoutEngineFlags values.
};
/**
****************************************************************************************************
* @brief
* Enumerates swizzle modes useable on any supported GPU.
* @note
* For details please check _AddrSwizzleMode
*
****************************************************************************************************
*/
enum SwizzleMode : uint32
{
SwizzleModeLinear = 0,
SwizzleMode256BS,
SwizzleMode256BD,
SwizzleMode256BR,
SwizzleMode4KbZ,
SwizzleMode4KbS,
SwizzleMode4KbD,
SwizzleMode4KbR,
SwizzleMode64KbZ,
SwizzleMode64KbS,
SwizzleMode64KbD,
SwizzleMode64KbR,
SwizzleMode64KbZT,
SwizzleMode64KbST,
SwizzleMode64KbDT,
SwizzleMode64KbRT,
SwizzleMode4KbZX,
SwizzleMode4KbSX,
SwizzleMode4KbDX,
SwizzleMode4KbRX,
SwizzleMode64KbZX,
SwizzleMode64KbSX,
SwizzleMode64KbDX,
SwizzleMode64KbRX,
SwizzleMode256KbVarZX,
SwizzleMode256KbVarSX,
SwizzleMode256KbVarDX,
SwizzleMode256KbVarRX,
///< the meaning of swizzle mode varies by generation,
/// do not compare directly with the _R / _S / _D / _S types".
SwizzleMode256B2D,
SwizzleMode4Kb2D,
SwizzleMode4Kb3D,
SwizzleMode64Kb2D,
SwizzleMode64Kb3D,
SwizzleMode256Kb2D,
SwizzleMode256Kb3D,
SwizzleMode64Kb2Dz,
SwizzleMode256Kb2Dz,
SwizzleModeCount,
};
/// Reports position and memory layout information for a specific subresource in an image. Output structure for
/// IImage::GetSubresourceLayout().
struct SubresLayout
{
uint32 elementBytes; ///< size of each element in bytes
gpusize offset; ///< Offset in bytes from the base of the image's GPU memory where the subresource starts.
gpusize swizzleOffset; ///< Offset in bytes used for supporting parameterized swizzle
gpusize size; ///< Size of the subresource in bytes.
gpusize rowPitch; ///< Offset in bytes between the same X position on two consecutive lines of the subresource.
gpusize depthPitch; ///< Offset in bytes between the same X,Y position of two consecutive slices.
uint32 tileToken; ///< Token representing various tiling information necessary for determining compatible
/// optimally tiled copies.
uint32 tileSwizzle; ///< Bank/Pipe swizzle bits for macro-tiling modes.
Extent3d blockSize; ///< Size of a tile block in texels - micro tile for 1D tiling and macro tile for 2D tiling.
Offset3d mipTailCoord; ///< coords of the subresource within the mip tail
Extent3d extentTexels; ///< Unpadded extent of the subresource in texels.
Extent3d extentElements; ///< Unpadded extent of the subresource in elements.
Extent3d paddedExtent; ///< Extent of the subresource in elements, including all internal padding for this subresource.
#if PAL_CLIENT_INTERFACE_MAJOR_VERSION < 912
/// Reports supported engines and usages for this subresource while it can remain in its optimal compression state.
/// Clients using CmdRelease()/CmdAcquire() without complete knowledge of the application's next usage during
/// CmdRelease() or its previous usage at CmdAcquire() can treat this layout as a performant target for an
/// intermediate state that will avoid unnecessary decompressions.
///
/// This value is only valid if supportSplitReleaseAcquire is set in @ref DeviceProperties.
ImageLayout defaultGfxLayout;
#endif
SwizzledFormat planeFormat; ///< Swizzled format for plane. Planar resource like D32-S8
/// will have different swizzled format per plane.
SwizzleMode swizzleMode; ///< Swizzle mode for plane, based on AddrSwizzleMode
uint32 hwSwizzleMode; ///< Hardware Swizzle enum, enum type dependent on gfx version
};
/// Selects a specific subresource of an image resource.
///
/// Most images only have a single data plane but in some cases conceptually related data will be stored in physically
/// separate locations which we call planes. If an image only has a single plane it will always be plane 0.
/// We define the following fixed mappings for all multi-plane formats.
/// + Depth-stencil: if the image format contains depth and stencil data, plane 0 is depth and plane 1 is stencil.
/// + YUV-planar: if the image format is @ref YuvPlanar it has either two or three planes. The luma plane
/// is always plane 0. If the format is @ref ChNumFormat::YV12 it has three planes where plane 1 is the
/// red-difference chrominance plane and plane 2 is the blue-difference chrominance plane. Otherwise, plane 1
/// interleaves blue-difference and red-difference chrominance values.
#if PAL_CLIENT_INTERFACE_MAJOR_VERSION >= 886
struct SubresId
{
uint8 plane; ///< Selects a data plane.
uint8 mipLevel; ///< Selects a mip level.
uint16 arraySlice; ///< Selects an array slice.
};
/// Defines a range of subresources.
struct SubresRange
{
SubresId startSubres; ///< First subresource in the range.
uint8 numPlanes; ///< Number of planes in the range.
uint8 numMips; ///< Number of mip levels in the range.
uint16 numSlices; ///< Number of slices in the range.
};
#else
struct SubresId
{
uint32 plane; ///< Selects a data plane.
uint32 mipLevel; ///< Selects a mip level.
uint32 arraySlice; ///< Selects an array slice.
};
/// Defines a range of subresources.
struct SubresRange
{
SubresId startSubres; ///< First subresource in the range.
uint32 numPlanes; ///< Number of planes in the range.
uint32 numMips; ///< Number of mip levels in the range.
uint32 numSlices; ///< Number of slices in the range.
};
#endif
/// A variant struct of MemoryImageCopyRegion
/// Specifies parameters for a copy from CPU memory to Image.
/// An input for Image::CopyMemoryToImage().
struct MemoryToImageCopyRegion
{
SubresId imageSubres; ///< Selects the image subresource.
Offset3d imageOffset; ///< Pixel offset to the start of the chosen subresource region.
Extent3d imageExtent; ///< Size of the image region in elements.
uint32 numSlices; ///< Number of slices the copy will span.
const void* pHostPtr; ///< Pointer to the host memory copy from.
gpusize gpuMemoryRowPitch; ///< Offset in bytes between the same X position on two consecutive lines.
gpusize gpuMemoryDepthPitch; ///< Offset in bytes between the same X,Y position of two consecutive slices.
};
/// A variant struct of MemoryImageCopyRegion
/// Specifies parameters for a copy from Image to CPU memory.
/// An input for Image::CopyImageToMemory().
struct ImageToMemoryCopyRegion
{
SubresId imageSubres; ///< Selects the image subresource.
Offset3d imageOffset; ///< Pixel offset to the start of the chosen subresource region.
Extent3d imageExtent; ///< Size of the image region in elements.
uint32 numSlices; ///< Number of slices the copy will span.
void* pHostPtr; ///< Pointer to the host memory copy to.
gpusize gpuMemoryRowPitch; ///< Offset in bytes between the same X position on two consecutive lines.
gpusize gpuMemoryDepthPitch; ///< Offset in bytes between the same X,Y position of two consecutive slices.
};
inline constexpr bool operator==(const SubresId& lhs, const SubresId& rhs)
{
return (lhs.plane == rhs.plane) &&
(lhs.mipLevel == rhs.mipLevel) &&
(lhs.arraySlice == rhs.arraySlice);
}
inline constexpr bool operator!=(const SubresId& lhs, const SubresId& rhs)
{
return ((lhs == rhs) == false);
}
inline constexpr bool operator==(const SubresRange& lhs, const SubresRange& rhs)
{
return (lhs.startSubres == rhs.startSubres) &&
(lhs.numPlanes == rhs.numPlanes) &&
(lhs.numMips == rhs.numMips) &&
(lhs.numSlices == rhs.numSlices);
}
/// Determines if two subresource ranges are overlapped.
///
/// @returns True if two subresource ranges are overlapped, false otherwise.
inline constexpr bool OverlappedSubresRanges(
const SubresRange& a,
const SubresRange& b)
{
const SubresId aStart = a.startSubres;
const SubresId bStart = b.startSubres;
return (aStart.plane < (bStart.plane + b.numPlanes)) &&
(bStart.plane < (aStart.plane + a.numPlanes)) &&
(aStart.mipLevel < (bStart.mipLevel + b.numMips)) &&
(bStart.mipLevel < (aStart.mipLevel + a.numMips)) &&
(aStart.arraySlice < (bStart.arraySlice + b.numSlices)) &&
(bStart.arraySlice < (aStart.arraySlice + a.numSlices));
}
/**
***********************************************************************************************************************
* @interface IImage
* @brief Represents an image resource that can be accessed by the GPU.
*
* @see IDevice::CreateImage()
* @see IDevice::OpenPeerImage()
***********************************************************************************************************************
*/
class IImage : public IGpuMemoryBindable
{
public:
/// Reports information on the layout of the image in memory such as core data size and metadata alignment.
///
/// @returns the reference to ImageCreateInfo
virtual const ImageMemoryLayout& GetMemoryLayout() const = 0;
/// Reports information on the full range of the image's subresources.
///
/// @param [out] pRange Reports info on the full range of the image's subresources such as number of mips and
/// planes.
///
/// @returns Success if the layout was successfully reported. Otherwise, one of the following error codes may be
/// returned:
/// + ErrorInvalidPointer if pRange is null.
virtual Result GetFullSubresourceRange(SubresRange* pRange) const = 0;
/// Reports information on the layout of the specified subresource in memory.
///
/// @param [in] subresId Selects a subresource from the image (aspect/mip/slice).
/// @param [out] pLayout Reports info on the subresource layout such as size and pitch.
///
/// @returns Success if the layout was successfully reported. Otherwise, one of the following error codes may be
/// returned:
/// + ErrorInvalidPointer if pLayout is null.
/// + ErrorInvalidValue is the subresId is out of range for this image.
virtual Result GetSubresourceLayout(
SubresId subresId,
SubresLayout* pLayout) const = 0;
#if defined(__unix__)
/// Reports information on the memory plane layout of the specified subresource in memory for image with modifier.
///
/// @param [in] memoryPlane Selects a memory plane from the image.
/// @param [out] pLayout Reports info on the subresource layout such as size and pitch.
///
/// @returns Success if the layout was successfully reported. Otherwise, one of the following error codes may be
/// returned:
/// + ErrorInvalidValue is the memory plane is out of range for this image.
virtual Result GetModifierSubresourceLayout(
uint32 memoryPlane,
SubresLayout* pLayout) const = 0;
#endif
/// Reports the create info of image.
///
/// @returns the reference to ImageCreateInfo
const ImageCreateInfo& GetImageCreateInfo() const { return m_createInfo; }
/// Returns the value of the associated arbitrary client data pointer.
/// Can be used to associate arbitrary data with a particular PAL object.
///
/// @returns Pointer to client data.
void* GetClientData() const
{
return m_pClientData;
}
/// Sets the value of the associated arbitrary client data pointer.
/// Can be used to associate arbitrary data with a particular PAL object.
///
/// @param [in] pClientData A pointer to arbitrary client data.
void SetClientData(
void* pClientData)
{
m_pClientData = pClientData;
}
#if defined(_WIN32)
/// This method checks if the image is an opened cross-adapter shared image on MS hybrid graphics system.
///
/// @returns True if the image is an opened cross-adapter shared image. False otherwise.
virtual bool IsCrossAdapter() const = 0;
/// Returns a special resource ID. Can be used to associate an opened resource with its original resource.
///
/// @returns The optimal sharing ID.
virtual uint64 GetOptimalSharingId() const = 0;
#endif
/// Sets level of optimal sharing by opening APIs using this optimal sharable image and pass this information to the
/// creator. This function is supposed to be called by openers only. The call by creator is ignored.
///
/// @param [in] level Level to be set to specified client API.
virtual void SetOptimalSharingLevel(
MetadataSharingLevel level) = 0;
/// Returns support level set by all possible opening APIs.
///
/// @returns A summarized supporting level.
virtual MetadataSharingLevel GetOptimalSharingLevel() const = 0;
/// Gives the client access to the resource ID used for internal Pal events.
/// EX: Resource Create, Resource Bind, Resource Destroy.
///
/// @returns The Resource ID.
virtual const void* GetResourceId() const = 0;
/// Copies data directly from CPU memory to an Image.
///
/// @param [in] pRegions Pointer to an array of Image regions to copy from.
/// @param [in] regionCount Number of regions to copy.
/// @param [in] useMemcpy Indicates that it could be copied more efficiently from host memory to image with
/// image data is already swizzled in host memory
///
/// @returns Success if the copy between the image and memory was successfully performed. Otherwise, one of the
/// returned:
/// + ErrorInvalidPointer if the memory object bound to image is null.
/// + ErrorGpuMemoryMapFailed if the memory object is busy and cannot be mapped by the OS.
/// + ErrorOutOfMemory if out of system memory.
/// + ErrorInvalidValue if copy between image and memory failed.
virtual Result CopyMemoryToImage(
const MemoryToImageCopyRegion* pRegions,
const uint32 regionCount,
bool useMemcpy) const = 0;
/// Copies data directly from an Image to CPU memory.
///
/// @param [in] pRegions Pointer to an array of Image regions to copy to.
/// @param [in] regionCount Number of regions to copy.
/// @param [in] useMemcpy Indicates that it could be copied more efficiently from image to host memory and the
/// image data will be obtained while retaining the physical layout of the image.
///
/// @returns Success if the copy between the image and memory was successfully performed. Otherwise, one of the
/// returned:
/// + ErrorInvalidPointer if the memory object bound to image is null.
/// + ErrorGpuMemoryMapFailed if the memory object is busy and cannot be mapped by the OS.
/// + ErrorOutOfMemory if out of system memory.
/// + ErrorInvalidValue if copy between image and memory failed.
virtual Result CopyImageToMemory(
const ImageToMemoryCopyRegion* pRegions,
const uint32 regionCount,
bool useMemcpy) const = 0;
/// Copies data between two images with specified regions.
///
/// @param [in] pDstImage Pointer to the destination image where the data will be copied.
/// @param [in] pImgRegions Pointer to an array of regions specifying the area of image to be copied.
/// @param [in] regionCount Number of regions to copy between the source and destination images.
///
/// @returns Success if the copy operation was successfully performed. Otherwise, one of the following error codes
/// may be returned:
/// + ErrorInvalidPointer if any of the input pointers are null.
/// + ErrorGpuMemoryMapFailed if the memory object is busy and cannot be mapped by the OS.
/// + ErrorOutOfMemory if there is insufficient memory to perform the operation.
/// + ErrorInvalidValue if copy between images failed.
virtual Result CopyBetweenImages(
IImage* pDstImage,
const ImageCopyRegion* pImgRegions,
const uint32 regionCount) const = 0;
protected:
/// @internal Constructor.
///
/// @param [in] createInfo App-specified parameters describing the desired image properties.
IImage(const ImageCreateInfo& createInfo) : m_createInfo(createInfo), m_pClientData(nullptr) { }
/// @internal Destructor. Prevent use of delete operator on this interface. Client must destroy objects by
/// explicitly calling IDestroyable::Destroy() and is responsible for freeing the system memory allocated for the
/// object on their own.
virtual ~IImage() { }
/// Retained Image create info
const ImageCreateInfo m_createInfo;
private:
/// @internal Client data pointer. This can have an arbitrary value and can be returned by calling GetClientData()
/// and set via SetClientData().
/// For non-top-layer objects, this will point to the layer above the current object.
void* m_pClientData;
};
} // Pal
新しいイシューから参照 パーマリンクをコピー