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

[Henri Verbeet]

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.

> + * \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.