[PATCH vkd3d 2/5] include: Document struct vkd3d_shader_scan_descriptor_info.

[Zebediah Figura]

On 9/3/20 10:08 AM, Henri Verbeet wrote:
> On Thu, 3 Sep 2020 at 05:41, Zebediah Figura <z.figura12 at gmail.com> wrote:
>> +/**
>> + * The dimension of a shader resource, returned as part of
>> + * struct vkd3d_shader_descriptor_info.
>> + */
>>  enum vkd3d_shader_resource_type
>>  {
>> +    /**
>> +     * The dimension is invalid or not applicable for this resource. This value
>> +     * is returned for samplers.
>> +     */
>>      VKD3D_SHADER_RESOURCE_NONE              = 0x0,
>> +    /** Dimensionless buffer. */
>>      VKD3D_SHADER_RESOURCE_BUFFER            = 0x1,
>> +    /** 1-dimensional texture. */
>>      VKD3D_SHADER_RESOURCE_TEXTURE_1D        = 0x2,
>> +    /** 2-dimensional texture. */
>>      VKD3D_SHADER_RESOURCE_TEXTURE_2D        = 0x3,
>> +    /** Multisampled 2-dimensional texture. */
>>      VKD3D_SHADER_RESOURCE_TEXTURE_2DMS      = 0x4,
>> +    /** 3-dimensional texture. */
>>      VKD3D_SHADER_RESOURCE_TEXTURE_3D        = 0x5,
>> +    /** Cubemap texture. */
>>      VKD3D_SHADER_RESOURCE_TEXTURE_CUBE      = 0x6,
>> +    /** 1-dimensional array texture. */
>>      VKD3D_SHADER_RESOURCE_TEXTURE_1DARRAY   = 0x7,
>> +    /** 2-dimensional array texture. */
>>      VKD3D_SHADER_RESOURCE_TEXTURE_2DARRAY   = 0x8,
>> +    /** Multisampled 2-dimensional array texture. */
>>      VKD3D_SHADER_RESOURCE_TEXTURE_2DMSARRAY = 0x9,
>> +    /** Cubemap array texture. */
>>      VKD3D_SHADER_RESOURCE_TEXTURE_CUBEARRAY = 0xa,
>>
>>      VKD3D_FORCE_32_BIT_ENUM(VKD3D_SHADER_RESOURCE_TYPE),
>>  };
> It's possible to describe this in terms of dimension (although it's a
> bit of a stretch to include multisample and arrays there; at that
> point "topology" would perhaps be more appropriate), but in that case
> it's a little awkward that the enumeration is called
> "vkd3d_shader_resource_type".

I was mostly trying to find a nice way to distinguish it from
vkd3d_shader_resource_data_type. The term "type" is quite overloaded.

Suggestions welcome, and if not I'll just rely on the enums to explain
themselves.

> 
>> +/**
>> + * The format of a shader resource, returned as part of
>> + * struct vkd3d_shader_descriptor_info. All formats are 32-bit.
>> + */
>>  enum vkd3d_shader_resource_data_type
>>  {
>> +    /** Unsigned normalized integer. */
>>      VKD3D_SHADER_RESOURCE_DATA_UNORM = 0x1,
>> +    /** Signed normalized integer. */
>>      VKD3D_SHADER_RESOURCE_DATA_SNORM = 0x2,
>> +    /** Signed integer. */
>>      VKD3D_SHADER_RESOURCE_DATA_INT   = 0x3,
>> +    /** Unsigned integer. */
>>      VKD3D_SHADER_RESOURCE_DATA_UINT  = 0x4,
>> +    /** IEEE floating-point. */
>>      VKD3D_SHADER_RESOURCE_DATA_FLOAT = 0x5,
>>
>>      VKD3D_FORCE_32_BIT_ENUM(VKD3D_SHADER_RESOURCE_DATA_TYPE),
>>  };
>>
> "Format" tends to have a specific association in the context of these
> kinds of APIs. (I.e., VkFormat/DXGI_FORMAT/etc.) What this describes
> is more like the type of format; what SPIR-V calls the "sampled type"
> (as opposed to the "image format"), and GLSL calls "sampler
> type"/"internal texture format"

Same problem as the above, plus misreading OpenGL documentation :-/

> 
>> +/**
>> + * Additional flags describing a shader resource; returned as part of
>> + * struct vkd3d_shader_descriptor_info.
>> + */
>>  enum vkd3d_shader_descriptor_info_flag
>>  {
>> +    /**
>> +     * The counter associated with this UAV resource is read from or written to
>> +     * by the shader.
>> +     */
>>      VKD3D_SHADER_DESCRIPTOR_INFO_FLAG_UAV_COUNTER             = 0x00000001,
>> +    /** This UAV resource is read from by the shader. */
>>      VKD3D_SHADER_DESCRIPTOR_INFO_FLAG_UAV_READ                = 0x00000002,
>> +    /** This sampler is a comparison sampler. */
>>      VKD3D_SHADER_DESCRIPTOR_INFO_FLAG_SAMPLER_COMPARISON_MODE = 0x00000004,
>>
>>      VKD3D_FORCE_32_BIT_ENUM(VKD3D_SHADER_DESCRIPTOR_INFO_FLAG),
>>  };
>>
> Well, they're *descriptor* flags. The SAMPLER_COMPARISON_MODE flag in
> particular applies to sampler descriptors, not resource view
> descriptors.

Sure. I guess I already used "resource" to describe views + samplers in
enum vkd3d_shader_descriptor_type, although that's certainly not quite
accurate. I guess that should be changed too.

> 
>> +/**
>> + * Describes a single shader resource; returned as part of
>> + * struct vkd3d_shader_scan_descriptor_info.
>> + */
>>  struct vkd3d_shader_descriptor_info
>>  {
>> +    /** Type of this resource (eg SRV, CBV, UAV, or sampler). */
>>      enum vkd3d_shader_descriptor_type type;
>> +    /**
>> +     * Register space of the resource, or 0 if the shader does not
>> +     * support multiple register spaces.
>> +     */
>>      unsigned int register_space;
>> +    /** Register index of the resource. */
>>      unsigned int register_index;
>> +    /** Dimension of the resource. */
>>      enum vkd3d_shader_resource_type resource_type;
>> +    /** Format of the data contained in the resource (eg float or integer). */
>>      enum vkd3d_shader_resource_data_type resource_data_type;
>> -    unsigned int flags; /* vkd3d_shader_descriptor_info_flag */
>> +    /**
>> +     * Bitwise combination of zero or more members of
>> +     * \ref vkd3d_shader_descriptor_info_flag.
>> +     */
>> +    unsigned int flags;
>> +    /** Size of this descriptor array, or 1 if a single descriptor. */
>>      unsigned int count;
>>  };
>>
> A bunch more descriptor/resource conflation here. (And, to complicate
> it a little more, note that e.g. VKD3D_SHADER_DESCRIPTOR_TYPE_CBV
> refers to a descriptor for a *view* into a buffer resource.)
> 


-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 488 bytes
Desc: OpenPGP digital signature
URL: <http://www.winehq.org/pipermail/wine-devel/attachments/20200903/0dfc7592/attachment.sig>