Win32 API 日本語リファレンス
ホームGraphics.Direct3D12 › D3D12_RESOURCE_DESC

D3D12_RESOURCE_DESC

構造体
サイズx64: 56 バイト / x86: 56 バイト

サイズ=各フィールドのバイト数(x64/x86 で異なる場合は x64/x86 と併記)。x64/x86 列=フィールドのバイトオフセット(HSPで dupptr / lpoke / wpoke 等に使用)。

フィールド

フィールドサイズx64x86説明
DimensionD3D12_RESOURCE_DIMENSION4+0+0D3D12_RESOURCE_DIMENSION のいずれかのメンバーで、リソースの次元 (たとえば D3D12_RESOURCE_DIMENSION_TEXTURE1D)、またはバッファーであるかどうか ((D3D12_RESOURCE_DIMENSION_BUFFER) を指定します。
AlignmentULONGLONG8+8+8リソースのアラインメントをバイト単位で指定します。0 を指定すると、ランタイムが自動的にアラインメントを選択します。D3D12_RESOURCE_FLAG_USE_TIGHT_ALIGNMENT が設定されている場合、この値は最小アラインメントの下限として機能します。詳細については D3D12 Tight Placed Resource Alignment specification を参照してください。
WidthULONGLONG8+16+16リソースの幅を指定します。
HeightDWORD4+24+24リソースの高さを指定します。
DepthOrArraySizeWORD2+28+28リソースが 3D の場合はその深度を、1D または 2D リソースの配列の場合は配列サイズを指定します。
MipLevelsWORD2+30+30MIP レベルの数を指定します。
FormatDXGI_FORMAT4+32+32DXGI_FORMAT のいずれかのメンバーを指定します。
SampleDescDXGI_SAMPLE_DESC8+36+36DXGI_SAMPLE_DESC 構造体を指定します。
LayoutD3D12_TEXTURE_LAYOUT4+44+44D3D12_TEXTURE_LAYOUT のいずれかのメンバーを指定します。
FlagsD3D12_RESOURCE_FLAGS4+48+48D3D12_RESOURCE_FLAGS 列挙型の定数をビット単位の OR で組み合わせたフラグです。

公式ドキュメント

テクスチャなどのリソースを記述します。この構造体は広範に使用されます。

解説(Remarks)

この構造体は次のものと共に使用します:

代表的なリソースはバッファーとテクスチャの 2 つで、どちらもこの構造体を使用しますが、各フィールドの使い方はかなり異なります。

バッファー

バッファーは連続したメモリ領域です。 Width には、1 から、予約済みリソースの場合は D3D12_FEATURE_DATA_GPU_VIRTUAL_ADDRESS_SUPPORTMaxGPUVirtualAddressBitsPerResource フィールド、コミット済みリソースの場合は MaxGPUVirtualAddressBitsPerProcess フィールドまでの値を指定できます。ただし、GPU 仮想アドレス空間、メモリ常駐予算 (IDXGIAdapter3::QueryVideoMemoryInfo を参照)、またはシステムメモリのいずれかが先に枯渇する場合があります。

Alignment は 64KB (D3D12_DEFAULT_RESOURCE_PLACEMENT_ALIGNMENT) または 0 でなければなりません。0 は実質的に 64KB を意味します。

HeightDepthOrArraySizeMipLevels は 1 でなければなりません。

FormatDXGI_FORMAT_UNKNOWN でなければなりません。

SampleDesc.Count は 1、Quality は 0 でなければなりません。

LayoutD3D12_TEXTURE_LAYOUT_ROW_MAJOR でなければなりません。バッファーのメモリレイアウトはアプリケーション側で把握されており、行優先 (row-major) のテクスチャデータは一般にバッファーを介して受け渡されるためです。

バッファーの場合でも、わずかな例外を除き、アプリケーションは Flags を正確に設定する必要があります。ただしバッファーでは、効率への影響を気にせずに最大限の機能サポートを利用できます。このフラグのフィールドは、主にテクスチャに関連するプロパティを制御するためのものです。

テクスチャ

テクスチャは、連続したメモリ領域内にテクセルを多次元に配置したもので、レンダリングとサンプリングの帯域幅を最大化するように高度に最適化されています。テクスチャのサイズは予測が難しく、アダプターごとに異なります。アプリケーションは、そのサイズを正確に把握するために ID3D12Device::GetResourceAllocationInfo を使用する必要があります。

TEXTURE1D、TEXTURE2D、TEXTURE3D は、すべてのフォーマットで一律にサポートされるわけではありません。D3D12_FORMAT_SUPPORT1 における D3D12_FORMAT_SUPPORT1_TEXTURE1DD3D12_FORMAT_SUPPORT1_TEXTURE2DD3D12_FORMAT_SUPPORT1_TEXTURE3D の使い方を参照してください。

WidthHeightDepthOrArraySize は、1 から、対象の機能レベルおよびテクスチャの次元でサポートされる最大サイズまでの範囲でなければなりません。ただし、GPU 仮想アドレス空間、メモリ常駐予算 (IDXGIAdapter3::QueryVideoMemoryInfo を参照)、またはシステムメモリのいずれかが先に枯渇する場合があります。圧縮フォーマットの場合、これらのサイズは論理的な値です。例:

以下の注意事項は、すべてのテクスチャサイズに適用されます。

アラインメント

Alignment には 0、4KB、64KB、4MB のいずれかを指定できます。

Alignment に 0 を指定した場合、ランタイムは MSAA テクスチャには 4MB を、それ以外にはすべて 64KB を使用します。テクスチャが小さい場合、いくつかの種類のテクスチャについては、アプリケーションがこれらの既定値より小さいアラインメントを選択できます。 UNKNOWN レイアウトで MSAA のテクスチャは、(後述の小サイズの制限を満たす場合) 64KB アラインメントで作成できます。

UNKNOWN レイアウトで MSAA を使用せず、レンダーターゲットフラグも深度ステンシルフラグも指定していないテクスチャは、(同じく小サイズの制限を満たす場合) 4KB アラインメントで作成できます。

最も詳細な MIP レベルの推定サイズが、大きい方のアラインメント制限の合計以下である場合、アプリケーションはより小さいアラインメントのリソースを作成できます。ランタイムは、標準スウィズルおよび D3D12 タイルリソースのサイズ算出方法を模した、アーキテクチャに依存しないサイズ推定の仕組みを使用します。ただし、この計算でのタイルサイズは、小さい方のアラインメント制限に基づく値になります。 レンダーターゲットでも深度ステンシルでもないテクスチャを例にとると、ランタイムは 4KB のほぼ正方形に近いタイル形状を想定し、最も詳細な MIP レベルに必要なタイル数を計算します。タイル数が 16 以下であれば、アプリケーションは 4KB アラインメントのリソースを作成できます。したがって、幅と高さが対象のフォーマットおよび MSAA に対して十分小さければ、任意の配列サイズと任意の MIP レベル数を持つ MIP 付き tex2d 配列も 4KB にできます。

MipLevels

MipLevels には 0、または 1 から WidthHeightDepthOrArraySize の各サイズでサポートされる最大 MIP レベル数までの値を指定できます。0 を指定した場合、API はサポートされる最大 MIP レベル数を自動的に計算して使用します。ただし、一部のリソースプロパティやヒーププロパティでは MIP レベルを使用できないため、その場合アプリケーションは値として 1 を指定する必要があります。

フォーマットごとの制限については、D3D12_FORMAT_SUPPORT1D3D12_FORMAT_SUPPORT1_MIP フィールドを参照してください。MSAA リソース、D3D12_RESOURCE_FLAG_ALLOW_CROSS_ADAPTER を指定したテクスチャ、D3D12_HEAP_FLAG_ALLOW_DISPLAY を指定したヒープでは、いずれも MIP レベルを使用できません。

Format

Format は、デバイスの機能レベルでサポートされる有効なフォーマットでなければなりません。

SampleDesc

1 より大きい SampleDesc.Count、または 0 以外の Quality は、TEXTURE2D で、かつ D3D12_RESOURCE_FLAG_ALLOW_RENDER_TARGET または D3D12_RESOURCE_FLAG_ALLOW_DEPTH_STENCIL のいずれかが設定されている場合にのみサポートされます。

次のものはサポートされません:

有効な CountQuality の値を判別するには、D3D12_FEATURE_DATA_MULTISAMPLE_QUALITY_LEVELS を参照してください。
出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

各言語での定義

#include <windows.h>

// DXGI_SAMPLE_DESC  (x64 8 / x86 8 バイト)
typedef struct DXGI_SAMPLE_DESC {
    DWORD Count;
    DWORD Quality;
} DXGI_SAMPLE_DESC;

// D3D12_RESOURCE_DESC  (x64 56 / x86 56 バイト)
typedef struct D3D12_RESOURCE_DESC {
    D3D12_RESOURCE_DIMENSION Dimension;
    ULONGLONG Alignment;
    ULONGLONG Width;
    DWORD Height;
    WORD DepthOrArraySize;
    WORD MipLevels;
    DXGI_FORMAT Format;
    DXGI_SAMPLE_DESC SampleDesc;
    D3D12_TEXTURE_LAYOUT Layout;
    D3D12_RESOURCE_FLAGS Flags;
} D3D12_RESOURCE_DESC;
using System;
using System.Runtime.InteropServices;

[StructLayout(LayoutKind.Sequential, CharSet = CharSet.Unicode)]
public struct DXGI_SAMPLE_DESC
{
    public uint Count;
    public uint Quality;
}

[StructLayout(LayoutKind.Sequential, CharSet = CharSet.Unicode)]
public struct D3D12_RESOURCE_DESC
{
    public int Dimension;
    public ulong Alignment;
    public ulong Width;
    public uint Height;
    public ushort DepthOrArraySize;
    public ushort MipLevels;
    public int Format;
    public DXGI_SAMPLE_DESC SampleDesc;
    public int Layout;
    public int Flags;
}
Imports System.Runtime.InteropServices

<StructLayout(LayoutKind.Sequential, CharSet:=CharSet.Unicode)>
Public Structure DXGI_SAMPLE_DESC
    Public Count As UInteger
    Public Quality As UInteger
End Structure

<StructLayout(LayoutKind.Sequential, CharSet:=CharSet.Unicode)>
Public Structure D3D12_RESOURCE_DESC
    Public Dimension As Integer
    Public Alignment As ULong
    Public Width As ULong
    Public Height As UInteger
    Public DepthOrArraySize As UShort
    Public MipLevels As UShort
    Public Format As Integer
    Public SampleDesc As DXGI_SAMPLE_DESC
    Public Layout As Integer
    Public Flags As Integer
End Structure
import ctypes
from ctypes import wintypes

class DXGI_SAMPLE_DESC(ctypes.Structure):
    _fields_ = [
        ("Count", wintypes.DWORD),
        ("Quality", wintypes.DWORD),
    ]

class D3D12_RESOURCE_DESC(ctypes.Structure):
    _fields_ = [
        ("Dimension", ctypes.c_int),
        ("Alignment", ctypes.c_ulonglong),
        ("Width", ctypes.c_ulonglong),
        ("Height", wintypes.DWORD),
        ("DepthOrArraySize", ctypes.c_ushort),
        ("MipLevels", ctypes.c_ushort),
        ("Format", ctypes.c_int),
        ("SampleDesc", DXGI_SAMPLE_DESC),
        ("Layout", ctypes.c_int),
        ("Flags", ctypes.c_int),
    ]
#[repr(C)]
pub struct DXGI_SAMPLE_DESC {
    pub Count: u32,
    pub Quality: u32,
}

#[repr(C)]
pub struct D3D12_RESOURCE_DESC {
    pub Dimension: i32,
    pub Alignment: u64,
    pub Width: u64,
    pub Height: u32,
    pub DepthOrArraySize: u16,
    pub MipLevels: u16,
    pub Format: i32,
    pub SampleDesc: DXGI_SAMPLE_DESC,
    pub Layout: i32,
    pub Flags: i32,
}
import "golang.org/x/sys/windows"

type DXGI_SAMPLE_DESC struct {
	Count uint32
	Quality uint32
}

type D3D12_RESOURCE_DESC struct {
	Dimension int32
	Alignment uint64
	Width uint64
	Height uint32
	DepthOrArraySize uint16
	MipLevels uint16
	Format int32
	SampleDesc DXGI_SAMPLE_DESC
	Layout int32
	Flags int32
}
type
  DXGI_SAMPLE_DESC = record
    Count: DWORD;
    Quality: DWORD;
  end;

  D3D12_RESOURCE_DESC = record
    Dimension: Integer;
    Alignment: UInt64;
    Width: UInt64;
    Height: DWORD;
    DepthOrArraySize: Word;
    MipLevels: Word;
    Format: Integer;
    SampleDesc: DXGI_SAMPLE_DESC;
    Layout: Integer;
    Flags: Integer;
  end;
const DXGI_SAMPLE_DESC = extern struct {
    Count: u32,
    Quality: u32,
};

const D3D12_RESOURCE_DESC = extern struct {
    Dimension: i32,
    Alignment: u64,
    Width: u64,
    Height: u32,
    DepthOrArraySize: u16,
    MipLevels: u16,
    Format: i32,
    SampleDesc: DXGI_SAMPLE_DESC,
    Layout: i32,
    Flags: i32,
};
type
  DXGI_SAMPLE_DESC {.bycopy.} = object
    Count: uint32
    Quality: uint32

  D3D12_RESOURCE_DESC {.bycopy.} = object
    Dimension: int32
    Alignment: uint64
    Width: uint64
    Height: uint32
    DepthOrArraySize: uint16
    MipLevels: uint16
    Format: int32
    SampleDesc: DXGI_SAMPLE_DESC
    Layout: int32
    Flags: int32
struct DXGI_SAMPLE_DESC
{
    uint Count;
    uint Quality;
}

struct D3D12_RESOURCE_DESC
{
    int Dimension;
    ulong Alignment;
    ulong Width;
    uint Height;
    ushort DepthOrArraySize;
    ushort MipLevels;
    int Format;
    DXGI_SAMPLE_DESC SampleDesc;
    int Layout;
    int Flags;
}

HSP用 定義

HSP3.7/3.8 は構造体機能が無いため4byte整数配列(dim)+peek/poke で操作(32/64bitでサイズ・位置が異なる場合はタブで分割)。IronHSP は NSTRUCT(#defstruct/stdim/->)で32/64bit共通。

; HSP3.7/3.8 は構造体機能が無いため、4byte整数の配列変数で操作します。(x64 レイアウト)
; D3D12_RESOURCE_DESC サイズ: 56 バイト(x64)
dim st, 14    ; 4byte整数×14(構造体サイズ 56 / 4 切り上げ)
; Dimension : D3D12_RESOURCE_DIMENSION (+0, 4byte)  st.0 = 値  /  値 = st.0   (lpoke/lpeek も可)
; Alignment : ULONGLONG (+8, 8byte)  qpoke st,8,値 / qpeek(st,8)  ※IronHSPのみ。3.7/3.8は lpoke st,8,下位 : lpoke st,12,上位
; Width : ULONGLONG (+16, 8byte)  qpoke st,16,値 / qpeek(st,16)  ※IronHSPのみ。3.7/3.8は lpoke st,16,下位 : lpoke st,20,上位
; Height : DWORD (+24, 4byte)  st.6 = 値  /  値 = st.6   (lpoke/lpeek も可)
; DepthOrArraySize : WORD (+28, 2byte)  wpoke st,28,値  /  値 = wpeek(st,28)
; MipLevels : WORD (+30, 2byte)  wpoke st,30,値  /  値 = wpeek(st,30)
; Format : DXGI_FORMAT (+32, 4byte)  st.8 = 値  /  値 = st.8   (lpoke/lpeek も可)
; SampleDesc : DXGI_SAMPLE_DESC (+36, 8byte)  varptr(st)+36 を基点に操作(8byte:入れ子/配列)
; Layout : D3D12_TEXTURE_LAYOUT (+44, 4byte)  st.11 = 値  /  値 = st.11   (lpoke/lpeek も可)
; Flags : D3D12_RESOURCE_FLAGS (+48, 4byte)  st.12 = 値  /  値 = st.12   (lpoke/lpeek も可)
; ※4byte境界の整数は添字 st.N(N=オフセット/4)で読み書き可。それ以外は peek/poke 系を使用。
; IronHSP は NSTRUCT(構造体)をサポート。32bit/64bit どちらでも同じコードで動作します。
; ※GUID・入れ子構造体はデフォルト型でないため、依存する #defstruct を先に定義(下記に同梱)。
#defstruct global DXGI_SAMPLE_DESC
    #field int Count
    #field int Quality
#endstruct

#defstruct global D3D12_RESOURCE_DESC
    #field int Dimension
    #field int64 Alignment
    #field int64 Width
    #field int Height
    #field short DepthOrArraySize
    #field short MipLevels
    #field int Format
    #field DXGI_SAMPLE_DESC SampleDesc
    #field int Layout
    #field int Flags
#endstruct

stdim st, D3D12_RESOURCE_DESC        ; NSTRUCT 変数を確保
st->Dimension = 100
mes "Dimension=" + st->Dimension