[PATCH vkd3d 4/5] include: Document vkd3d-shader compilation and scanning functions.

[Zebediah Figura]

On 8/27/20 11:18 AM, Henri Verbeet wrote:
> On Thu, 27 Aug 2020 at 07:46, Zebediah Figura <z.figura12 at gmail.com> wrote:
>> +/**
>> + * Returns the source types supported, with any target type, by
>> + * vkd3d_shader_compile().
>> + *
>> + * Use vkd3d_shader_get_supported_target_types() to determine which target types
>> + * are supported for each source type.
>> + *
>> + * \param count Output location for the size, in elements, of the returned
>> + * array.
>> + *
>> + * \return An array of source types supported by this version of vkd3d-shader.
>> + * This array may be a pointer to static data in libvkd3d-shader; it should not
>> + * be freed.
>> + */
>>  const enum vkd3d_shader_source_type *vkd3d_shader_get_supported_source_types(unsigned int *count);
> "pointer to an array"
> 
>> +/**
>> + * Returns the target types supported, with the given source type, by
>> + * vkd3d_shader_compile().
>> + *
>> + * \param source_type Source type for which to enumerate supported target types.
>> + *
>> + * \param count Output location for the size, in elements, of the returned
>> + * array.
>> + *
>> + * \return An array of target types supported by this version of vkd3d-shader.
>> + * This array may be a pointer to static data in libvkd3d-shader; it should not
>> + * be freed.
>> + */
>>  const enum vkd3d_shader_target_type *vkd3d_shader_get_supported_target_types(
>>          enum vkd3d_shader_source_type source_type, unsigned int *count);
> Likewise.
> 
>> +/**
>> + * Transform a form of GPU shader source code or byte code into another form of
>> + * source code or byte code.
>> + *
>> + * Currently this function supports the following transformations:
>> + * - VKD3D_SHADER_SOURCE_DXBC_TPF to VKD3D_SHADER_TARGET_SPIRV_BINARY
>> + *
> "This version of vkd3d-shader supports ...", maybe.
> 
>> + * Supported transformations can also be detected at runtime with the functions
>> + * vkd3d_shader_get_supported_source_types() and
>> + * vkd3d_shader_get_supported_target_types().
>> + *
>> + * The DXBC_TPF to SPIRV_BINARY compiler supports the following chained
>> + * structures, all of which are optional:
>> + * - vkd3d_shader_interface_info
>> + * - vkd3d_shader_spirv_domain_shader_target_info
>> + * - vkd3d_shader_spirv_target_info
>> + * - vkd3d_shader_transform_feedback_info
>> + *
> I think this is generally fine. In case it helps though, note that
> there's also a basic structure to these; interface_info and its
> extension transform_feedback_info contain generic information about
> how the shader interacts with its target environment, while
> spirv_target_info and spirv_domain_shader_target_info contain
> information specific to the target format. Likewise, we may have
> source format specific information in the future.

Sure. Maybe it'd be better to document the conditions under which the
structure is supported inside the structure definition itself, and
inside this function just have a list like

 * This function may support the following chained structures:
 * - vkd3d_shader_interface_info
 * - vkd3d_shader_spirv_domain_shader_target_info
 * - vkd3d_shader_spirv_target_info
 * - vkd3d_shader_transform_feedback_info

> 
>> + * \param compile_info A chained structure containing compilation parameters.
>> + *
>> + * \param out A pointer to a vkd3d_shader_code structure in which the compiled
>> + * code will be stored.
>> + * \n
>> + * The compiled shader is allocated by vkd3d-shader and should be freed with
>> + * vkd3d_shader_free_shader_code() when no longer needed.
>> + *
>> + * \param messages Optional output location for error or informational messages
>> + * produced by the compiler.
>> + * \n
>> + * The messages are allocated by vkd3d-shader and should be freed with
>> + * vkd3d_shader_free_messages() when no longer needed.
>> + * \n
>> + * The messages returned can be regulated with the \a log_level member of struct
>> + * vkd3d_shader_compile_info. Regardless of the requested level, if this
>> + * parameter is NULL, no compilation messages will be returned.
>> + * \n
>> + * If no compilation messages are produced by the compiler, this parameter may
>> + * receive NULL instead of a valid string pointer.
>> + *
> Null-terminated, UTF-8 encoded.
> 

-------------- 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/20200827/bb4957c0/attachment-0001.sig>