Signed-off-by: Zebediah Figura z.figura12@gmail.com --- This is built on Doxygen. I'm not personally attached to Doxygen, but it was easy enough to set up and write for, and I've found its compiled HTML to be reasonably legible.
Note that Doxygen does allow for specifying documentation in external files, if keeping the documentation out of the header is desired.
.gitignore | 2 + Doxyfile.in | 17 ++ Makefile.am | 2 + configure.ac | 3 + include/vkd3d_types.h | 15 +- m4/ax_prog_doxygen.m4 | 586 ++++++++++++++++++++++++++++++++++++++++++ 6 files changed, 624 insertions(+), 1 deletion(-) create mode 100644 Doxyfile.in create mode 100644 m4/ax_prog_doxygen.m4
diff --git a/.gitignore b/.gitignore index 72037ddb..51cba319 100644 --- a/.gitignore +++ b/.gitignore @@ -3,6 +3,8 @@ autom4te.cache config.log config.status configure +doc +Doxyfile libtool Makefile Makefile.in diff --git a/Doxyfile.in b/Doxyfile.in new file mode 100644 index 00000000..f5f88dbf --- /dev/null +++ b/Doxyfile.in @@ -0,0 +1,17 @@ +# Doxyfile 1.8.18 + +DOXYFILE_ENCODING = UTF-8 +PROJECT_NAME = @PACKAGE_NAME@ +PROJECT_NUMBER = @PACKAGE_VERSION@ +PROJECT_BRIEF = "D3D12 to Vulkan translation library" +OUTPUT_DIRECTORY = @srcdir@/doc +JAVADOC_AUTOBRIEF = YES +OPTIMIZE_OUTPUT_FOR_C = YES +EXTRACT_STATIC = YES + +INPUT = @srcdir@/include/vkd3d.h \ + @srcdir@/include/vkd3d_shader.h \ + @srcdir@/include/vkd3d_types.h \ + @srcdir@/include/vkd3d_utils.h + +EXCLUDE_SYMBOLS = VKD3D_FORCE_32_BIT_ENUM diff --git a/Makefile.am b/Makefile.am index 58b3174c..b3d3eb63 100644 --- a/Makefile.am +++ b/Makefile.am @@ -167,6 +167,8 @@ demos_triangle_CFLAGS = $(DEMOS_CFLAGS) demos_triangle_LDADD = $(DEMOS_LDADD) endif
+@DX_RULES@ + EXTRA_DIST += $(vkd3d_test_headers) $(vkd3d_demos_headers)
VKD3D_V_WIDL = $(vkd3d_v_widl_@AM_V@) diff --git a/configure.ac b/configure.ac index ca9d7600..2ce226b6 100644 --- a/configure.ac +++ b/configure.ac @@ -29,6 +29,9 @@ AC_PROG_MKDIR_P VKD3D_PROG_WIDL(3, 20) AS_IF([test "x$WIDL" = "xno"], [AC_MSG_WARN([widl is required to build header files.])])
+DX_INIT_DOXYGEN(vkd3d, [Doxyfile], [doc]) +AC_CONFIG_FILES([Doxyfile]) + AM_INIT_AUTOMAKE([1.11 foreign silent-rules subdir-objects no-dist-gzip dist-xz -Wall -Werror]) AM_MAINTAINER_MODE([enable]) AM_SILENT_RULES([yes]) diff --git a/include/vkd3d_types.h b/include/vkd3d_types.h index 34c66748..cdb8ee61 100644 --- a/include/vkd3d_types.h +++ b/include/vkd3d_types.h @@ -23,15 +23,28 @@ extern "C" { #endif /* __cplusplus */
+/** + * \file vkd3d_types.h + * + * This file contains definitions for basic types used by vkd3d libraries. + */ + #define VKD3D_FORCE_32_BIT_ENUM(name) name##_FORCE_32BIT = 0x7fffffff
+/** Result codes returned by some vkd3d functions. */ enum vkd3d_result { + /** Success. */ VKD3D_OK = 0, - VKD3D_ERROR = -1, /* unspecified failure */ + /** An unspecified failure occurred. */ + VKD3D_ERROR = -1, + /** There are not enough resources available to complete the operation. */ VKD3D_ERROR_OUT_OF_MEMORY = -2, + /** One or more parameters passed to a vkd3d function were invalid. */ VKD3D_ERROR_INVALID_ARGUMENT = -3, + /** A shader passed to a vkd3d function was invalid. */ VKD3D_ERROR_INVALID_SHADER = -4, + /** The operation is not implemented in this version of vkd3d. */ VKD3D_ERROR_NOT_IMPLEMENTED = -5,
VKD3D_FORCE_32_BIT_ENUM(VKD3D_RESULT), diff --git a/m4/ax_prog_doxygen.m4 b/m4/ax_prog_doxygen.m4 new file mode 100644 index 00000000..ed1dc83b --- /dev/null +++ b/m4/ax_prog_doxygen.m4 @@ -0,0 +1,586 @@ +# =========================================================================== +# https://www.gnu.org/software/autoconf-archive/ax_prog_doxygen.html +# =========================================================================== +# +# SYNOPSIS +# +# DX_INIT_DOXYGEN(PROJECT-NAME, [DOXYFILE-PATH], [OUTPUT-DIR], ...) +# DX_DOXYGEN_FEATURE(ON|OFF) +# DX_DOT_FEATURE(ON|OFF) +# DX_HTML_FEATURE(ON|OFF) +# DX_CHM_FEATURE(ON|OFF) +# DX_CHI_FEATURE(ON|OFF) +# DX_MAN_FEATURE(ON|OFF) +# DX_RTF_FEATURE(ON|OFF) +# DX_XML_FEATURE(ON|OFF) +# DX_PDF_FEATURE(ON|OFF) +# DX_PS_FEATURE(ON|OFF) +# +# DESCRIPTION +# +# The DX_*_FEATURE macros control the default setting for the given +# Doxygen feature. Supported features are 'DOXYGEN' itself, 'DOT' for +# generating graphics, 'HTML' for plain HTML, 'CHM' for compressed HTML +# help (for MS users), 'CHI' for generating a separate .chi file by the +# .chm file, and 'MAN', 'RTF', 'XML', 'PDF' and 'PS' for the appropriate +# output formats. The environment variable DOXYGEN_PAPER_SIZE may be +# specified to override the default 'a4wide' paper size. +# +# By default, HTML, PDF and PS documentation is generated as this seems to +# be the most popular and portable combination. MAN pages created by +# Doxygen are usually problematic, though by picking an appropriate subset +# and doing some massaging they might be better than nothing. CHM and RTF +# are specific for MS (note that you can't generate both HTML and CHM at +# the same time). The XML is rather useless unless you apply specialized +# post-processing to it. +# +# The macros mainly control the default state of the feature. The use can +# override the default by specifying --enable or --disable. The macros +# ensure that contradictory flags are not given (e.g., +# --enable-doxygen-html and --enable-doxygen-chm, +# --enable-doxygen-anything with --disable-doxygen, etc.) Finally, each +# feature will be automatically disabled (with a warning) if the required +# programs are missing. +# +# Once all the feature defaults have been specified, call DX_INIT_DOXYGEN +# with the following parameters: a one-word name for the project for use +# as a filename base etc., an optional configuration file name (the +# default is '$(srcdir)/Doxyfile', the same as Doxygen's default), and an +# optional output directory name (the default is 'doxygen-doc'). To run +# doxygen multiple times for different configuration files and output +# directories provide more parameters: the second, forth, sixth, etc +# parameter are configuration file names and the third, fifth, seventh, +# etc parameter are output directories. No checking is done to catch +# duplicates. +# +# Automake Support +# +# The DX_RULES substitution can be used to add all needed rules to the +# Makefile. Note that this is a substitution without being a variable: +# only the @DX_RULES@ syntax will work. +# +# The provided targets are: +# +# doxygen-doc: Generate all doxygen documentation. +# +# doxygen-run: Run doxygen, which will generate some of the +# documentation (HTML, CHM, CHI, MAN, RTF, XML) +# but will not do the post processing required +# for the rest of it (PS, PDF). +# +# doxygen-ps: Generate doxygen PostScript documentation. +# +# doxygen-pdf: Generate doxygen PDF documentation. +# +# Note that by default these are not integrated into the automake targets. +# If doxygen is used to generate man pages, you can achieve this +# integration by setting man3_MANS to the list of man pages generated and +# then adding the dependency: +# +# $(man3_MANS): doxygen-doc +# +# This will cause make to run doxygen and generate all the documentation. +# +# The following variable is intended for use in Makefile.am: +# +# DX_CLEANFILES = everything to clean. +# +# Then add this variable to MOSTLYCLEANFILES. +# +# LICENSE +# +# Copyright (c) 2009 Oren Ben-Kiki oren@ben-kiki.org +# Copyright (c) 2015 Olaf Mandel olaf@mandel.name +# +# Copying and distribution of this file, with or without modification, are +# permitted in any medium without royalty provided the copyright notice +# and this notice are preserved. This file is offered as-is, without any +# warranty. + +#serial 24 + +## ----------## +## Defaults. ## +## ----------## + +DX_ENV="" +AC_DEFUN([DX_FEATURE_doc], ON) +AC_DEFUN([DX_FEATURE_dot], OFF) +AC_DEFUN([DX_FEATURE_man], OFF) +AC_DEFUN([DX_FEATURE_html], ON) +AC_DEFUN([DX_FEATURE_chm], OFF) +AC_DEFUN([DX_FEATURE_chi], OFF) +AC_DEFUN([DX_FEATURE_rtf], OFF) +AC_DEFUN([DX_FEATURE_xml], OFF) +AC_DEFUN([DX_FEATURE_pdf], ON) +AC_DEFUN([DX_FEATURE_ps], ON) + +## --------------- ## +## Private macros. ## +## --------------- ## + +# DX_ENV_APPEND(VARIABLE, VALUE) +# ------------------------------ +# Append VARIABLE="VALUE" to DX_ENV for invoking doxygen and add it +# as a substitution (but not a Makefile variable). The substitution +# is skipped if the variable name is VERSION. +AC_DEFUN([DX_ENV_APPEND], +[AC_SUBST([DX_ENV], ["$DX_ENV $1='$2'"])dnl +m4_if([$1], [VERSION], [], [AC_SUBST([$1], [$2])dnl +AM_SUBST_NOTMAKE([$1])])dnl +]) + +# DX_DIRNAME_EXPR +# --------------- +# Expand into a shell expression prints the directory part of a path. +AC_DEFUN([DX_DIRNAME_EXPR], + [[expr ".$1" : '(.)[^/]*$' | "x$1" : 'x(.*)/[^/]*$']]) + +# DX_IF_FEATURE(FEATURE, IF-ON, IF-OFF) +# ------------------------------------- +# Expands according to the M4 (static) status of the feature. +AC_DEFUN([DX_IF_FEATURE], [ifelse(DX_FEATURE_$1, ON, [$2], [$3])]) + +# DX_REQUIRE_PROG(VARIABLE, PROGRAM) +# ---------------------------------- +# Require the specified program to be found for the DX_CURRENT_FEATURE to work. +AC_DEFUN([DX_REQUIRE_PROG], [ +AC_PATH_TOOL([$1], [$2]) +if test "$DX_FLAG_[]DX_CURRENT_FEATURE$$1" = 1; then + AC_MSG_WARN([$2 not found - will not DX_CURRENT_DESCRIPTION]) + AC_SUBST(DX_FLAG_[]DX_CURRENT_FEATURE, 0) +fi +]) + +# DX_TEST_FEATURE(FEATURE) +# ------------------------ +# Expand to a shell expression testing whether the feature is active. +AC_DEFUN([DX_TEST_FEATURE], [test "$DX_FLAG_$1" = 1]) + +# DX_CHECK_DEPEND(REQUIRED_FEATURE, REQUIRED_STATE) +# ------------------------------------------------- +# Verify that a required features has the right state before trying to turn on +# the DX_CURRENT_FEATURE. +AC_DEFUN([DX_CHECK_DEPEND], [ +test "$DX_FLAG_$1" = "$2" \ +|| AC_MSG_ERROR([doxygen-DX_CURRENT_FEATURE ifelse([$2], 1, + requires, contradicts) doxygen-$1]) +]) + +# DX_CLEAR_DEPEND(FEATURE, REQUIRED_FEATURE, REQUIRED_STATE) +# ---------------------------------------------------------- +# Turn off the DX_CURRENT_FEATURE if the required feature is off. +AC_DEFUN([DX_CLEAR_DEPEND], [ +test "$DX_FLAG_$1" = "$2" || AC_SUBST(DX_FLAG_[]DX_CURRENT_FEATURE, 0) +]) + +# DX_FEATURE_ARG(FEATURE, DESCRIPTION, +# CHECK_DEPEND, CLEAR_DEPEND, +# REQUIRE, DO-IF-ON, DO-IF-OFF) +# -------------------------------------------- +# Parse the command-line option controlling a feature. CHECK_DEPEND is called +# if the user explicitly turns the feature on (and invokes DX_CHECK_DEPEND), +# otherwise CLEAR_DEPEND is called to turn off the default state if a required +# feature is disabled (using DX_CLEAR_DEPEND). REQUIRE performs additional +# requirement tests (DX_REQUIRE_PROG). Finally, an automake flag is set and +# DO-IF-ON or DO-IF-OFF are called according to the final state of the feature. +AC_DEFUN([DX_ARG_ABLE], [ + AC_DEFUN([DX_CURRENT_FEATURE], [$1]) + AC_DEFUN([DX_CURRENT_DESCRIPTION], [$2]) + AC_ARG_ENABLE(doxygen-$1, + [AS_HELP_STRING(DX_IF_FEATURE([$1], [--disable-doxygen-$1], + [--enable-doxygen-$1]), + DX_IF_FEATURE([$1], [don't $2], [$2]))], + [ +case "$enableval" in +#( +y|Y|yes|Yes|YES) + AC_SUBST([DX_FLAG_$1], 1) + $3 +;; #( +n|N|no|No|NO) + AC_SUBST([DX_FLAG_$1], 0) +;; #( +*) + AC_MSG_ERROR([invalid value '$enableval' given to doxygen-$1]) +;; +esac +], [ +AC_SUBST([DX_FLAG_$1], [DX_IF_FEATURE([$1], 1, 0)]) +$4 +]) +if DX_TEST_FEATURE([$1]); then + $5 + : +fi +if DX_TEST_FEATURE([$1]); then + $6 + : +else + $7 + : +fi +]) + +## -------------- ## +## Public macros. ## +## -------------- ## + +# DX_XXX_FEATURE(DEFAULT_STATE) +# ----------------------------- +AC_DEFUN([DX_DOXYGEN_FEATURE], [AC_DEFUN([DX_FEATURE_doc], [$1])]) +AC_DEFUN([DX_DOT_FEATURE], [AC_DEFUN([DX_FEATURE_dot], [$1])]) +AC_DEFUN([DX_MAN_FEATURE], [AC_DEFUN([DX_FEATURE_man], [$1])]) +AC_DEFUN([DX_HTML_FEATURE], [AC_DEFUN([DX_FEATURE_html], [$1])]) +AC_DEFUN([DX_CHM_FEATURE], [AC_DEFUN([DX_FEATURE_chm], [$1])]) +AC_DEFUN([DX_CHI_FEATURE], [AC_DEFUN([DX_FEATURE_chi], [$1])]) +AC_DEFUN([DX_RTF_FEATURE], [AC_DEFUN([DX_FEATURE_rtf], [$1])]) +AC_DEFUN([DX_XML_FEATURE], [AC_DEFUN([DX_FEATURE_xml], [$1])]) +AC_DEFUN([DX_XML_FEATURE], [AC_DEFUN([DX_FEATURE_xml], [$1])]) +AC_DEFUN([DX_PDF_FEATURE], [AC_DEFUN([DX_FEATURE_pdf], [$1])]) +AC_DEFUN([DX_PS_FEATURE], [AC_DEFUN([DX_FEATURE_ps], [$1])]) + +# DX_INIT_DOXYGEN(PROJECT, [CONFIG-FILE], [OUTPUT-DOC-DIR], ...) +# -------------------------------------------------------------- +# PROJECT also serves as the base name for the documentation files. +# The default CONFIG-FILE is "$(srcdir)/Doxyfile" and OUTPUT-DOC-DIR is +# "doxygen-doc". +# More arguments are interpreted as interleaved CONFIG-FILE and +# OUTPUT-DOC-DIR values. +AC_DEFUN([DX_INIT_DOXYGEN], [ + +# Files: +AC_SUBST([DX_PROJECT], [$1]) +AC_SUBST([DX_CONFIG], ['ifelse([$2], [], [$(srcdir)/Doxyfile], [$2])']) +AC_SUBST([DX_DOCDIR], ['ifelse([$3], [], [doxygen-doc], [$3])']) +m4_if(m4_eval(3 < m4_count($@)), 1, [m4_for([DX_i], 4, m4_count($@), 2, + [AC_SUBST([DX_CONFIG]m4_eval(DX_i[/2]), + 'm4_default_nblank_quoted(m4_argn(DX_i, $@), + [$(srcdir)/Doxyfile])')])])dnl +m4_if(m4_eval(3 < m4_count($@)), 1, [m4_for([DX_i], 5, m4_count($@,), 2, + [AC_SUBST([DX_DOCDIR]m4_eval([(]DX_i[-1)/2]), + 'm4_default_nblank_quoted(m4_argn(DX_i, $@), + [doxygen-doc])')])])dnl +m4_define([DX_loop], m4_dquote(m4_if(m4_eval(3 < m4_count($@)), 1, + [m4_for([DX_i], 4, m4_count($@), 2, [, m4_eval(DX_i[/2])])], + [])))dnl + +# Environment variables used inside doxygen.cfg: +DX_ENV_APPEND(SRCDIR, $srcdir) +DX_ENV_APPEND(PROJECT, $DX_PROJECT) +DX_ENV_APPEND(VERSION, $PACKAGE_VERSION) + +# Doxygen itself: +DX_ARG_ABLE(doc, [generate any doxygen documentation], + [], + [], + [DX_REQUIRE_PROG([DX_DOXYGEN], doxygen) + DX_REQUIRE_PROG([DX_PERL], perl)], + [DX_ENV_APPEND(PERL_PATH, $DX_PERL)]) + +# Dot for graphics: +DX_ARG_ABLE(dot, [generate graphics for doxygen documentation], + [DX_CHECK_DEPEND(doc, 1)], + [DX_CLEAR_DEPEND(doc, 1)], + [DX_REQUIRE_PROG([DX_DOT], dot)], + [DX_ENV_APPEND(HAVE_DOT, YES) + DX_ENV_APPEND(DOT_PATH, [`DX_DIRNAME_EXPR($DX_DOT)`])], + [DX_ENV_APPEND(HAVE_DOT, NO)]) + +# Man pages generation: +DX_ARG_ABLE(man, [generate doxygen manual pages], + [DX_CHECK_DEPEND(doc, 1)], + [DX_CLEAR_DEPEND(doc, 1)], + [], + [DX_ENV_APPEND(GENERATE_MAN, YES)], + [DX_ENV_APPEND(GENERATE_MAN, NO)]) + +# RTF file generation: +DX_ARG_ABLE(rtf, [generate doxygen RTF documentation], + [DX_CHECK_DEPEND(doc, 1)], + [DX_CLEAR_DEPEND(doc, 1)], + [], + [DX_ENV_APPEND(GENERATE_RTF, YES)], + [DX_ENV_APPEND(GENERATE_RTF, NO)]) + +# XML file generation: +DX_ARG_ABLE(xml, [generate doxygen XML documentation], + [DX_CHECK_DEPEND(doc, 1)], + [DX_CLEAR_DEPEND(doc, 1)], + [], + [DX_ENV_APPEND(GENERATE_XML, YES)], + [DX_ENV_APPEND(GENERATE_XML, NO)]) + +# (Compressed) HTML help generation: +DX_ARG_ABLE(chm, [generate doxygen compressed HTML help documentation], + [DX_CHECK_DEPEND(doc, 1)], + [DX_CLEAR_DEPEND(doc, 1)], + [DX_REQUIRE_PROG([DX_HHC], hhc)], + [DX_ENV_APPEND(HHC_PATH, $DX_HHC) + DX_ENV_APPEND(GENERATE_HTML, YES) + DX_ENV_APPEND(GENERATE_HTMLHELP, YES)], + [DX_ENV_APPEND(GENERATE_HTMLHELP, NO)]) + +# Separate CHI file generation. +DX_ARG_ABLE(chi, [generate doxygen separate compressed HTML help index file], + [DX_CHECK_DEPEND(chm, 1)], + [DX_CLEAR_DEPEND(chm, 1)], + [], + [DX_ENV_APPEND(GENERATE_CHI, YES)], + [DX_ENV_APPEND(GENERATE_CHI, NO)]) + +# Plain HTML pages generation: +DX_ARG_ABLE(html, [generate doxygen plain HTML documentation], + [DX_CHECK_DEPEND(doc, 1) DX_CHECK_DEPEND(chm, 0)], + [DX_CLEAR_DEPEND(doc, 1) DX_CLEAR_DEPEND(chm, 0)], + [], + [DX_ENV_APPEND(GENERATE_HTML, YES)], + [DX_TEST_FEATURE(chm) || DX_ENV_APPEND(GENERATE_HTML, NO)]) + +# PostScript file generation: +DX_ARG_ABLE(ps, [generate doxygen PostScript documentation], + [DX_CHECK_DEPEND(doc, 1)], + [DX_CLEAR_DEPEND(doc, 1)], + [DX_REQUIRE_PROG([DX_LATEX], latex) + DX_REQUIRE_PROG([DX_MAKEINDEX], makeindex) + DX_REQUIRE_PROG([DX_DVIPS], dvips) + DX_REQUIRE_PROG([DX_EGREP], egrep)]) + +# PDF file generation: +DX_ARG_ABLE(pdf, [generate doxygen PDF documentation], + [DX_CHECK_DEPEND(doc, 1)], + [DX_CLEAR_DEPEND(doc, 1)], + [DX_REQUIRE_PROG([DX_PDFLATEX], pdflatex) + DX_REQUIRE_PROG([DX_MAKEINDEX], makeindex) + DX_REQUIRE_PROG([DX_EGREP], egrep)]) + +# LaTeX generation for PS and/or PDF: +if DX_TEST_FEATURE(ps) || DX_TEST_FEATURE(pdf); then + DX_ENV_APPEND(GENERATE_LATEX, YES) +else + DX_ENV_APPEND(GENERATE_LATEX, NO) +fi + +# Paper size for PS and/or PDF: +AC_ARG_VAR(DOXYGEN_PAPER_SIZE, + [a4wide (default), a4, letter, legal or executive]) +case "$DOXYGEN_PAPER_SIZE" in +#( +"") + AC_SUBST(DOXYGEN_PAPER_SIZE, "") +;; #( +a4wide|a4|letter|legal|executive) + DX_ENV_APPEND(PAPER_SIZE, $DOXYGEN_PAPER_SIZE) +;; #( +*) + AC_MSG_ERROR([unknown DOXYGEN_PAPER_SIZE='$DOXYGEN_PAPER_SIZE']) +;; +esac + +# Rules: +AS_IF([[test $DX_FLAG_html -eq 1]], +[[DX_SNIPPET_html="## ------------------------------- ## +## Rules specific for HTML output. ## +## ------------------------------- ## + +DX_CLEAN_HTML = $(DX_DOCDIR)/html]dnl +m4_foreach([DX_i], [m4_shift(DX_loop)], [[\ + $(DX_DOCDIR]DX_i[)/html]])[ + +"]], +[[DX_SNIPPET_html=""]]) +AS_IF([[test $DX_FLAG_chi -eq 1]], +[[DX_SNIPPET_chi=" +DX_CLEAN_CHI = $(DX_DOCDIR)/$(PACKAGE).chi]dnl +m4_foreach([DX_i], [m4_shift(DX_loop)], [[\ + $(DX_DOCDIR]DX_i[)/$(PACKAGE).chi]])["]], +[[DX_SNIPPET_chi=""]]) +AS_IF([[test $DX_FLAG_chm -eq 1]], +[[DX_SNIPPET_chm="## ------------------------------ ## +## Rules specific for CHM output. ## +## ------------------------------ ## + +DX_CLEAN_CHM = $(DX_DOCDIR)/chm]dnl +m4_foreach([DX_i], [m4_shift(DX_loop)], [[\ + $(DX_DOCDIR]DX_i[)/chm]])[\ +${DX_SNIPPET_chi} + +"]], +[[DX_SNIPPET_chm=""]]) +AS_IF([[test $DX_FLAG_man -eq 1]], +[[DX_SNIPPET_man="## ------------------------------ ## +## Rules specific for MAN output. ## +## ------------------------------ ## + +DX_CLEAN_MAN = $(DX_DOCDIR)/man]dnl +m4_foreach([DX_i], [m4_shift(DX_loop)], [[\ + $(DX_DOCDIR]DX_i[)/man]])[ + +"]], +[[DX_SNIPPET_man=""]]) +AS_IF([[test $DX_FLAG_rtf -eq 1]], +[[DX_SNIPPET_rtf="## ------------------------------ ## +## Rules specific for RTF output. ## +## ------------------------------ ## + +DX_CLEAN_RTF = $(DX_DOCDIR)/rtf]dnl +m4_foreach([DX_i], [m4_shift(DX_loop)], [[\ + $(DX_DOCDIR]DX_i[)/rtf]])[ + +"]], +[[DX_SNIPPET_rtf=""]]) +AS_IF([[test $DX_FLAG_xml -eq 1]], +[[DX_SNIPPET_xml="## ------------------------------ ## +## Rules specific for XML output. ## +## ------------------------------ ## + +DX_CLEAN_XML = $(DX_DOCDIR)/xml]dnl +m4_foreach([DX_i], [m4_shift(DX_loop)], [[\ + $(DX_DOCDIR]DX_i[)/xml]])[ + +"]], +[[DX_SNIPPET_xml=""]]) +AS_IF([[test $DX_FLAG_ps -eq 1]], +[[DX_SNIPPET_ps="## ----------------------------- ## +## Rules specific for PS output. ## +## ----------------------------- ## + +DX_CLEAN_PS = $(DX_DOCDIR)/$(PACKAGE).ps]dnl +m4_foreach([DX_i], [m4_shift(DX_loop)], [[\ + $(DX_DOCDIR]DX_i[)/$(PACKAGE).ps]])[ + +DX_PS_GOAL = doxygen-ps + +doxygen-ps: $(DX_CLEAN_PS) + +]m4_foreach([DX_i], [DX_loop], +[[$(DX_DOCDIR]DX_i[)/$(PACKAGE).ps: $(DX_DOCDIR]DX_i[)/$(PACKAGE).tag + $(DX_V_LATEX)cd $(DX_DOCDIR]DX_i[)/latex; \ + rm -f *.aux *.toc *.idx *.ind *.ilg *.log *.out; \ + $(DX_LATEX) refman.tex; \ + $(DX_MAKEINDEX) refman.idx; \ + $(DX_LATEX) refman.tex; \ + countdown=5; \ + while $(DX_EGREP) 'Rerun (LaTeX|to get cross-references right)' \ + refman.log > /dev/null 2>&1 \ + && test $$countdown -gt 0; do \ + $(DX_LATEX) refman.tex; \ + countdown=`expr $$countdown - 1`; \ + done; \ + $(DX_DVIPS) -o ../$(PACKAGE).ps refman.dvi + +]])["]], +[[DX_SNIPPET_ps=""]]) +AS_IF([[test $DX_FLAG_pdf -eq 1]], +[[DX_SNIPPET_pdf="## ------------------------------ ## +## Rules specific for PDF output. ## +## ------------------------------ ## + +DX_CLEAN_PDF = $(DX_DOCDIR)/$(PACKAGE).pdf]dnl +m4_foreach([DX_i], [m4_shift(DX_loop)], [[\ + $(DX_DOCDIR]DX_i[)/$(PACKAGE).pdf]])[ + +DX_PDF_GOAL = doxygen-pdf + +doxygen-pdf: $(DX_CLEAN_PDF) + +]m4_foreach([DX_i], [DX_loop], +[[$(DX_DOCDIR]DX_i[)/$(PACKAGE).pdf: $(DX_DOCDIR]DX_i[)/$(PACKAGE).tag + $(DX_V_LATEX)cd $(DX_DOCDIR]DX_i[)/latex; \ + rm -f *.aux *.toc *.idx *.ind *.ilg *.log *.out; \ + $(DX_PDFLATEX) refman.tex; \ + $(DX_MAKEINDEX) refman.idx; \ + $(DX_PDFLATEX) refman.tex; \ + countdown=5; \ + while $(DX_EGREP) 'Rerun (LaTeX|to get cross-references right)' \ + refman.log > /dev/null 2>&1 \ + && test $$countdown -gt 0; do \ + $(DX_PDFLATEX) refman.tex; \ + countdown=`expr $$countdown - 1`; \ + done; \ + mv refman.pdf ../$(PACKAGE).pdf + +]])["]], +[[DX_SNIPPET_pdf=""]]) +AS_IF([[test $DX_FLAG_ps -eq 1 -o $DX_FLAG_pdf -eq 1]], +[[DX_SNIPPET_latex="## ------------------------------------------------- ## +## Rules specific for LaTeX (shared for PS and PDF). ## +## ------------------------------------------------- ## + +DX_V_LATEX = $(_DX_v_LATEX_$(V)) +_DX_v_LATEX_ = $(_DX_v_LATEX_$(AM_DEFAULT_VERBOSITY)) +_DX_v_LATEX_0 = @echo " LATEX " $][@; + +DX_CLEAN_LATEX = $(DX_DOCDIR)/latex]dnl +m4_foreach([DX_i], [m4_shift(DX_loop)], [[\ + $(DX_DOCDIR]DX_i[)/latex]])[ + +"]], +[[DX_SNIPPET_latex=""]]) + +AS_IF([[test $DX_FLAG_doc -eq 1]], +[[DX_SNIPPET_doc="## --------------------------------- ## +## Format-independent Doxygen rules. ## +## --------------------------------- ## + +${DX_SNIPPET_html}\ +${DX_SNIPPET_chm}\ +${DX_SNIPPET_man}\ +${DX_SNIPPET_rtf}\ +${DX_SNIPPET_xml}\ +${DX_SNIPPET_ps}\ +${DX_SNIPPET_pdf}\ +${DX_SNIPPET_latex}\ +DX_V_DXGEN = $(_DX_v_DXGEN_$(V)) +_DX_v_DXGEN_ = $(_DX_v_DXGEN_$(AM_DEFAULT_VERBOSITY)) +_DX_v_DXGEN_0 = @echo " DXGEN " $<; + +.PHONY: doxygen-run doxygen-doc $(DX_PS_GOAL) $(DX_PDF_GOAL) + +.INTERMEDIATE: doxygen-run $(DX_PS_GOAL) $(DX_PDF_GOAL) + +doxygen-run:]m4_foreach([DX_i], [DX_loop], + [[ $(DX_DOCDIR]DX_i[)/$(PACKAGE).tag]])[ + +doxygen-doc: doxygen-run $(DX_PS_GOAL) $(DX_PDF_GOAL) + +]m4_foreach([DX_i], [DX_loop], +[[$(DX_DOCDIR]DX_i[)/$(PACKAGE).tag: $(DX_CONFIG]DX_i[) $(pkginclude_HEADERS) + $(A""M_V_at)rm -rf $(DX_DOCDIR]DX_i[) + $(DX_V_DXGEN)$(DX_ENV) DOCDIR=$(DX_DOCDIR]DX_i[) $(DX_DOXYGEN) $(DX_CONFIG]DX_i[) + $(A""M_V_at)echo Timestamp >$][@ + +]])dnl +[DX_CLEANFILES = \] +m4_foreach([DX_i], [DX_loop], +[[ $(DX_DOCDIR]DX_i[)/doxygen_sqlite3.db \ + $(DX_DOCDIR]DX_i[)/$(PACKAGE).tag \ +]])dnl +[ -r \ + $(DX_CLEAN_HTML) \ + $(DX_CLEAN_CHM) \ + $(DX_CLEAN_CHI) \ + $(DX_CLEAN_MAN) \ + $(DX_CLEAN_RTF) \ + $(DX_CLEAN_XML) \ + $(DX_CLEAN_PS) \ + $(DX_CLEAN_PDF) \ + $(DX_CLEAN_LATEX)"]], +[[DX_SNIPPET_doc=""]]) +AC_SUBST([DX_RULES], +["${DX_SNIPPET_doc}"])dnl +AM_SUBST_NOTMAKE([DX_RULES]) + +#For debugging: +#echo DX_FLAG_doc=$DX_FLAG_doc +#echo DX_FLAG_dot=$DX_FLAG_dot +#echo DX_FLAG_man=$DX_FLAG_man +#echo DX_FLAG_html=$DX_FLAG_html +#echo DX_FLAG_chm=$DX_FLAG_chm +#echo DX_FLAG_chi=$DX_FLAG_chi +#echo DX_FLAG_rtf=$DX_FLAG_rtf +#echo DX_FLAG_xml=$DX_FLAG_xml +#echo DX_FLAG_pdf=$DX_FLAG_pdf +#echo DX_FLAG_ps=$DX_FLAG_ps +#echo DX_ENV=$DX_ENV +])
Signed-off-by: Zebediah Figura z.figura12@gmail.com --- In this (ongoing) series I have omitted documentation for some declarations, either because the name is too self-explanatory to provide a non-awkward explanation, or because I am not knowledgeable enough to adequately provide documentation.
include/vkd3d_shader.h | 19 ++++++++++++++++++- 1 file changed, 18 insertions(+), 1 deletion(-)
diff --git a/include/vkd3d_shader.h b/include/vkd3d_shader.h index 1f2a9c20..da05f2c3 100644 --- a/include/vkd3d_shader.h +++ b/include/vkd3d_shader.h @@ -27,14 +27,31 @@ extern "C" { #endif /* __cplusplus */
+/** + * \file vkd3d_shader.h + * + * \since 1.2 + * + * This file contains definitions for the vkd3d-shader library. + * + * The vkd3d-shader library provides multiple utilities related to the + * compilation, transformation, and reflection of GPU shaders. + */ + +/** The type of a chained structure. */ enum vkd3d_shader_structure_type { - /* 1.2 */ + /** The structure is a vkd3d_shader_compile_info structure. */ VKD3D_SHADER_STRUCTURE_TYPE_COMPILE_INFO, + /** The structure is a vkd3d_shader_interface_info structure. */ VKD3D_SHADER_STRUCTURE_TYPE_INTERFACE_INFO, + /** The structure is a vkd3d_shader_scan_descriptor_info structure. */ VKD3D_SHADER_STRUCTURE_TYPE_SCAN_DESCRIPTOR_INFO, + /** The structure is a vkd3d_shader_spirv_domain_shader_target_info structure. */ VKD3D_SHADER_STRUCTURE_TYPE_SPIRV_DOMAIN_SHADER_TARGET_INFO, + /** The structure is a vkd3d_shader_spirv_target_info structure. */ VKD3D_SHADER_STRUCTURE_TYPE_SPIRV_TARGET_INFO, + /** The structure is a vkd3d_shader_transform_feedback_info structure. */ VKD3D_SHADER_STRUCTURE_TYPE_TRANSFORM_FEEDBACK_INFO,
VKD3D_FORCE_32_BIT_ENUM(VKD3D_SHADER_STRUCTURE_TYPE),
Signed-off-by: Zebediah Figura z.figura12@gmail.com --- include/vkd3d_shader.h | 90 +++++++++++++++++++++++++++++++++++++++--- 1 file changed, 85 insertions(+), 5 deletions(-)
diff --git a/include/vkd3d_shader.h b/include/vkd3d_shader.h index da05f2c3..19fafae2 100644 --- a/include/vkd3d_shader.h +++ b/include/vkd3d_shader.h @@ -57,13 +57,17 @@ enum vkd3d_shader_structure_type VKD3D_FORCE_32_BIT_ENUM(VKD3D_SHADER_STRUCTURE_TYPE), };
-/* This also affects UAV counters in Vulkan environments. In OpenGL - * environments, atomic counter buffers are always used for UAV counters. */ +/** + * Determines how buffer UAVs are stored when compiling DXBC to SPIR-V. + * + * This also affects UAV counters in Vulkan environments. In OpenGL + * environments, atomic counter buffers are always used for UAV counters. + */ enum vkd3d_shader_compile_option_buffer_uav { - /* Use buffer textures for buffer UAVs, this is the default. */ + /** Use buffer textures for buffer UAVs. This is the default option. */ VKD3D_SHADER_COMPILE_OPTION_BUFFER_UAV_STORAGE_TEXEL_BUFFER = 0x00000000, - /* Use storage buffers for buffer UAVs. */ + /** Use storage buffers for buffer UAVs. */ VKD3D_SHADER_COMPILE_OPTION_BUFFER_UAV_STORAGE_BUFFER = 0x00000001,
VKD3D_FORCE_32_BIT_ENUM(VKD3D_SHADER_COMPILE_OPTION_BUFFER_UAV), @@ -71,15 +75,33 @@ enum vkd3d_shader_compile_option_buffer_uav
enum vkd3d_shader_compile_option_name { + /** + * If \a value is nonzero, do not include debug information in the + * compiled shader. The default value is zero. + * + * This option is supported by vkd3d_compiler. However, not all compilers + * support generating debug information. + */ VKD3D_SHADER_COMPILE_OPTION_STRIP_DEBUG = 0x00000001, - VKD3D_SHADER_COMPILE_OPTION_BUFFER_UAV = 0x00000002, /* vkd3d_shader_compile_option_buffer_uav */ + /** \a value is a member of enum vkd3d_shader_compile_option_buffer_uav. */ + VKD3D_SHADER_COMPILE_OPTION_BUFFER_UAV = 0x00000002,
VKD3D_FORCE_32_BIT_ENUM(VKD3D_SHADER_COMPILE_OPTION_NAME), };
+/** + * Various settings which may affect shader compilation or scanning, passed as + * part of struct vkd3d_shader_compile_info. For more details, see the + * documentation for individual options. + */ struct vkd3d_shader_compile_option { + /** Name of the setting. */ enum vkd3d_shader_compile_option_name name; + /** + * A value associated with the setting. The type and interpretation of the + * value depends on the setting in question. + */ unsigned int value; };
@@ -97,9 +119,12 @@ enum vkd3d_shader_visibility VKD3D_FORCE_32_BIT_ENUM(VKD3D_SHADER_VISIBILITY), };
+/** A generic structure containing GPU shader source or byte code. */ struct vkd3d_shader_code { + /** Pointer to the byte code. */ const void *code; + /** Size of \a code, in bytes. */ size_t size; };
@@ -264,46 +289,101 @@ struct vkd3d_shader_transform_feedback_info unsigned int buffer_stride_count; };
+/** The format of a shader to be compiled or scanned. */ enum vkd3d_shader_source_type { + /** + * The shader has no type or is to be ignored. This is not a valid value + * for vkd3d_shader_compile() or vkd3d_shader_scan(). + */ VKD3D_SHADER_SOURCE_NONE, + /** + * A 'Tokenized Program Format' shader embedded in a DXBC container. This is + * the format used for Direct3D shader model 4 and 5 shaders. + */ VKD3D_SHADER_SOURCE_DXBC_TPF,
VKD3D_FORCE_32_BIT_ENUM(VKD3D_SHADER_SOURCE_TYPE), };
+/** The output format of a compiled shader. */ enum vkd3d_shader_target_type { + /** + * The shader has no type or is to be ignored. This is not a valid value + * for vkd3d_shader_compile() or vkd3d_shader_scan(). + */ VKD3D_SHADER_TARGET_NONE, + /** + * A SPIR-V shader in binary form. This is the format used for Vulkan + * shaders. + */ VKD3D_SHADER_TARGET_SPIRV_BINARY,
VKD3D_FORCE_32_BIT_ENUM(VKD3D_SHADER_TARGET_TYPE), };
+/** + * Describes the maximum severity of compilation messages returned by + * vkd3d_shader_compile() and similar functions. + */ enum vkd3d_shader_log_level { + /** No messages will be returned. */ VKD3D_SHADER_LOG_NONE, + /** Only fatal errors which prevent successful compilation will be returned. */ VKD3D_SHADER_LOG_ERROR, + /** Non-fatal warnings and fatal errors will be returned. */ VKD3D_SHADER_LOG_WARNING, + /** + * All messages, including general informational messages, will be returned. + */ VKD3D_SHADER_LOG_INFO,
VKD3D_FORCE_32_BIT_ENUM(VKD3D_SHADER_LOG_LEVEL), };
+/** + * A chained structure containing compilation parameters. + */ struct vkd3d_shader_compile_info { + /** Must be set to VKD3D_SHADER_STRUCTURE_TYPE_COMPILE_INFO. */ enum vkd3d_shader_structure_type type; + /** + * Optional pointer to a structure containing further parameters. For a list + * of valid structures, refer to the respective function documentation. If + * no further parameters are needed, this field should be set to NULL. + */ const void *next;
+ /** Input source code or byte code. */ struct vkd3d_shader_code source;
+ /** Format of the input code passed in \ref source. */ enum vkd3d_shader_source_type source_type; + /** Desired output format. */ enum vkd3d_shader_target_type target_type;
+ /** + * An array of compilation options. This field is ignored if + * \ref option_count is zero, but must be valid otherwise. + * + * It is undefined behaviour to pass the same option multiple times. + * + * Options not relevant to or not supported by a particular shader compiler + * or scanner will be ignored. + */ const struct vkd3d_shader_compile_option *options; + /** Size, in elements, of \ref options. */ unsigned int option_count;
+ /** Minimum severity of messages returned from the shader function. */ enum vkd3d_shader_log_level log_level; + /** + * Name of the initial source file, used only in error messages. This + * parameter is optional and may be NULL. + */ const char *source_name; };
On Thu, 27 Aug 2020 at 07:46, Zebediah Figura z.figura12@gmail.com wrote:
+/**
- Determines how buffer UAVs are stored when compiling DXBC to SPIR-V.
This is slightly awkward; the actual shader in VKD3D_SHADER_SOURCE_DXBC_TPF is the "TPF" part, while "DXBC" is the container format, although people (including Microsoft) often use them interchangeably. Perhaps reword "how buffer UAVs are stored" to something along the lines of "the type of resource to use for buffer UAV bindings". Note that in the future this may apply to e.g. a GLSL target as well.
enum vkd3d_shader_compile_option_buffer_uav {
- /* Use buffer textures for buffer UAVs, this is the default. */
- /** Use buffer textures for buffer UAVs. This is the default option. */ VKD3D_SHADER_COMPILE_OPTION_BUFFER_UAV_STORAGE_TEXEL_BUFFER = 0x00000000,
Should that be "the default value"?
enum vkd3d_shader_compile_option_name {
- /**
* If \a value is nonzero, do not include debug information in the* compiled shader. The default value is zero.** This option is supported by vkd3d_compiler. However, not all compilers* support generating debug information.*/
I'm not sure I understand the vkd3d_compiler (vkd3d-compiler?) reference. For what it's worth, in the context of SPIR-V, debug information is things like variable names (i.e., it gets you names like "%main" instead of "%1"), and source information. We don't currently use the latter, but we could embed the D3D assembly for the source shader, which would probably help a little with debugging SPIR-V shaders.
+/**
- Various settings which may affect shader compilation or scanning, passed as
- part of struct vkd3d_shader_compile_info. For more details, see the
- documentation for individual options.
- */
struct vkd3d_shader_compile_option {
- /** Name of the setting. */ enum vkd3d_shader_compile_option_name name;
- /**
* A value associated with the setting. The type and interpretation of the* value depends on the setting in question.*/};
"Compile option"/"option" instead of "setting" above?
+/** A generic structure containing GPU shader source or byte code. */ struct vkd3d_shader_code {
- /** Pointer to the byte code. */ const void *code;
- /** Size of \a code, in bytes. */ size_t size;
};
We use this for the output as well, which may not necessarily be byte code. (E.g. GLSL or SPIR-V text.)
struct vkd3d_shader_compile_info {
/** Must be set to VKD3D_SHADER_STRUCTURE_TYPE_COMPILE_INFO. */ enum vkd3d_shader_structure_type type;
/**
* Optional pointer to a structure containing further parameters. For a list* of valid structures, refer to the respective function documentation. If* no further parameters are needed, this field should be set to NULL.*/const void *next;
/** Input source code or byte code. */ struct vkd3d_shader_code source;
/** Format of the input code passed in \ref source. */ enum vkd3d_shader_source_type source_type;
/** Desired output format. */ enum vkd3d_shader_target_type target_type;
/**
* An array of compilation options. This field is ignored if* \ref option_count is zero, but must be valid otherwise.*
A pointer to an array, strictly speaking, because C.
* It is undefined behaviour to pass the same option multiple times.*
I'd be happy to provide a stronger guarantee than "undefined" here. E.g., "if the same option is specified multiple times, the last value is used".
* Options not relevant to or not supported by a particular shader compiler* or scanner will be ignored.*/const struct vkd3d_shader_compile_option *options;
/** Size, in elements, of \ref options. */ unsigned int option_count;
/** Minimum severity of messages returned from the shader function. */ enum vkd3d_shader_log_level log_level;
/**
* Name of the initial source file, used only in error messages. This* parameter is optional and may be NULL.*/const char *source_name;
};
I think the HLSL preprocessor defines __FILE__.
On 8/27/20 11:17 AM, Henri Verbeet wrote:
On Thu, 27 Aug 2020 at 07:46, Zebediah Figura z.figura12@gmail.com wrote:
+/**
- Determines how buffer UAVs are stored when compiling DXBC to SPIR-V.
This is slightly awkward; the actual shader in VKD3D_SHADER_SOURCE_DXBC_TPF is the "TPF" part, while "DXBC" is the container format, although people (including Microsoft) often use them interchangeably. Perhaps reword "how buffer UAVs are stored" to something along the lines of "the type of resource to use for buffer UAV bindings". Note that in the future this may apply to e.g. a GLSL target as well.
Right, I can drop the reference to source and target types.
enum vkd3d_shader_compile_option_buffer_uav {
- /* Use buffer textures for buffer UAVs, this is the default. */
- /** Use buffer textures for buffer UAVs. This is the default option. */ VKD3D_SHADER_COMPILE_OPTION_BUFFER_UAV_STORAGE_TEXEL_BUFFER = 0x00000000,
Should that be "the default value"?
Probably, yes.
enum vkd3d_shader_compile_option_name {
- /**
* If \a value is nonzero, do not include debug information in the* compiled shader. The default value is zero.** This option is supported by vkd3d_compiler. However, not all compilers* support generating debug information.*/I'm not sure I understand the vkd3d_compiler (vkd3d-compiler?) reference.
That was an error for "vkd3d_shader_compile()".
For what it's worth, in the context of SPIR-V, debug information is things like variable names (i.e., it gets you names like "%main" instead of "%1"), and source information. We don't currently use the latter, but we could embed the D3D assembly for the source shader, which would probably help a little with debugging SPIR-V shaders.
Do you think it's a good idea to go into exact detail on what kind of debug information is included for each target, then? I kind of figured that'd be out of scope for this documentation.
+/**
- Various settings which may affect shader compilation or scanning, passed as
- part of struct vkd3d_shader_compile_info. For more details, see the
- documentation for individual options.
- */
struct vkd3d_shader_compile_option {
- /** Name of the setting. */ enum vkd3d_shader_compile_option_name name;
- /**
* A value associated with the setting. The type and interpretation of the* value depends on the setting in question.*/};
"Compile option"/"option" instead of "setting" above?
Yes, probably.
+/** A generic structure containing GPU shader source or byte code. */ struct vkd3d_shader_code {
- /** Pointer to the byte code. */ const void *code;
- /** Size of \a code, in bytes. */ size_t size;
};
We use this for the output as well, which may not necessarily be byte code. (E.g. GLSL or SPIR-V text.)
I tried to cover that with "source code or byte code". I guess maybe it'd be better to just remove that phrase.
struct vkd3d_shader_compile_info {
/** Must be set to VKD3D_SHADER_STRUCTURE_TYPE_COMPILE_INFO. */ enum vkd3d_shader_structure_type type;
/**
* Optional pointer to a structure containing further parameters. For a list* of valid structures, refer to the respective function documentation. If* no further parameters are needed, this field should be set to NULL.*/const void *next;
/** Input source code or byte code. */ struct vkd3d_shader_code source;
/** Format of the input code passed in \ref source. */ enum vkd3d_shader_source_type source_type;
/** Desired output format. */ enum vkd3d_shader_target_type target_type;
/**
* An array of compilation options. This field is ignored if* \ref option_count is zero, but must be valid otherwise.*A pointer to an array, strictly speaking, because C.
* It is undefined behaviour to pass the same option multiple times.*I'd be happy to provide a stronger guarantee than "undefined" here. E.g., "if the same option is specified multiple times, the last value is used".
* Options not relevant to or not supported by a particular shader compiler* or scanner will be ignored.*/const struct vkd3d_shader_compile_option *options;
/** Size, in elements, of \ref options. */ unsigned int option_count;
/** Minimum severity of messages returned from the shader function. */ enum vkd3d_shader_log_level log_level;
/**
* Name of the initial source file, used only in error messages. This* parameter is optional and may be NULL.*/const char *source_name;
};
I think the HLSL preprocessor defines __FILE__.
On Thu, 27 Aug 2020 at 23:21, Zebediah Figura z.figura12@gmail.com wrote:
enum vkd3d_shader_compile_option_name {
- /**
* If \a value is nonzero, do not include debug information in the* compiled shader. The default value is zero.** This option is supported by vkd3d_compiler. However, not all compilers* support generating debug information.*/I'm not sure I understand the vkd3d_compiler (vkd3d-compiler?) reference.
That was an error for "vkd3d_shader_compile()".
For what it's worth, in the context of SPIR-V, debug information is things like variable names (i.e., it gets you names like "%main" instead of "%1"), and source information. We don't currently use the latter, but we could embed the D3D assembly for the source shader, which would probably help a little with debugging SPIR-V shaders.
Do you think it's a good idea to go into exact detail on what kind of debug information is included for each target, then? I kind of figured that'd be out of scope for this documentation.
Probably not, no. The above was mostly me trying to clarify what debug information is stripped in practice, due to being confused by "vkd3d_compiler".
Signed-off-by: Zebediah Figura z.figura12@gmail.com --- include/vkd3d_shader.h | 108 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 108 insertions(+)
diff --git a/include/vkd3d_shader.h b/include/vkd3d_shader.h index 19fafae2..01393327 100644 --- a/include/vkd3d_shader.h +++ b/include/vkd3d_shader.h @@ -863,13 +863,97 @@ static inline uint32_t vkd3d_shader_create_swizzle(enum vkd3d_shader_swizzle_com #ifndef VKD3D_SHADER_NO_PROTOTYPES
const char *vkd3d_shader_get_version(unsigned int *major, unsigned int *minor); +/** + * 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); +/** + * 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);
+/** + * 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 + * + * 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 + * + * \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. + * + * \return A member of \ref vkd3d_result. + */ int vkd3d_shader_compile(const struct vkd3d_shader_compile_info *compile_info, struct vkd3d_shader_code *out, char **messages); +/** + * Free shader messages allocated by another vkd3d-shader function, such as + * vkd3d_shader_compile(). + * + * \param messages Messages to free. This pointer is optional and may be NULL, + * in which case no action will be taken. + */ void vkd3d_shader_free_messages(char *messages); +/** + * Free shader code allocated by another vkd3d-shader function, such as + * vkd3d_shader_compile(). + * + * This function frees the \ref vkd3d_shader_code.code member, but does not free + * the structure itself. + * + * \param code Code to free. + */ void vkd3d_shader_free_shader_code(struct vkd3d_shader_code *code);
int vkd3d_shader_parse_root_signature(const struct vkd3d_shader_code *dxbc, @@ -882,6 +966,30 @@ int vkd3d_shader_serialize_root_signature(const struct vkd3d_shader_versioned_ro int vkd3d_shader_convert_root_signature(struct vkd3d_shader_versioned_root_signature_desc *dst, enum vkd3d_shader_root_signature_version version, const struct vkd3d_shader_versioned_root_signature_desc *src);
+/** + * Parse shader source code or byte code, returning various types of requested + * information. + * + * Currently this function supports the following code types: + * - VKD3D_SHADER_SOURCE_DXBC_TPF + * + * \param compile_info A chained structure containing scan parameters. + * \n + * The DXBC_TPF scanner supports the following chained structures: + * - vkd3d_shader_scan_descriptor_info + * \n + * Although the \a compile_info parameter is read-only, chained structures + * passed to this function need not be, and may serve as output parameters, + * depending on their structure type. + * + * \param messages Optional output location for error or informational messages + * produced by the compiler. + * \n + * This parameter behaves identically to the \a messages parameter of + * vkd3d_shader_compile(). + * + * \return A member of \ref vkd3d_result. + */ int vkd3d_shader_scan(const struct vkd3d_shader_compile_info *compile_info, char **messages); void vkd3d_shader_free_scan_descriptor_info(struct vkd3d_shader_scan_descriptor_info *scan_descriptor_info);
On Thu, 27 Aug 2020 at 07:46, Zebediah Figura z.figura12@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.
On 8/27/20 11:18 AM, Henri Verbeet wrote:
On Thu, 27 Aug 2020 at 07:46, Zebediah Figura z.figura12@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.
Signed-off-by: Zebediah Figura z.figura12@gmail.com --- include/vkd3d_shader.h | 108 ++++++++++++++++++++++++++++++++++++++--- 1 file changed, 100 insertions(+), 8 deletions(-)
diff --git a/include/vkd3d_shader.h b/include/vkd3d_shader.h index 01393327..96a6e7fe 100644 --- a/include/vkd3d_shader.h +++ b/include/vkd3d_shader.h @@ -105,15 +105,23 @@ struct vkd3d_shader_compile_option unsigned int value; };
+/** Describes which shader stages a resource is visible to. */ enum vkd3d_shader_visibility { + /** The resource is visible to all shader stages. */ VKD3D_SHADER_VISIBILITY_ALL = 0, + /** The resource is visible only to the vertex shader. */ VKD3D_SHADER_VISIBILITY_VERTEX = 1, + /** The resource is visible only to the hull shader. */ VKD3D_SHADER_VISIBILITY_HULL = 2, + /** The resource is visible only to the domain shader. */ VKD3D_SHADER_VISIBILITY_DOMAIN = 3, + /** The resource is visible only to the geometry shader. */ VKD3D_SHADER_VISIBILITY_GEOMETRY = 4, + /** The resource is visible only to the pixel shader. */ VKD3D_SHADER_VISIBILITY_PIXEL = 5,
+ /** The resource is visible only to the compute shader. */ VKD3D_SHADER_VISIBILITY_COMPUTE = 1000000000,
VKD3D_FORCE_32_BIT_ENUM(VKD3D_SHADER_VISIBILITY), @@ -128,21 +136,36 @@ struct vkd3d_shader_code size_t size; };
+/** The type of a shader resource descriptor. */ enum vkd3d_shader_descriptor_type { - VKD3D_SHADER_DESCRIPTOR_TYPE_SRV = 0x0, /* t# */ + /** The descriptor is a shader resource view, bound to a t# register. */ + VKD3D_SHADER_DESCRIPTOR_TYPE_SRV = 0x0, + /** The descriptor is an unordered access view, bound to a u# register. */ VKD3D_SHADER_DESCRIPTOR_TYPE_UAV = 0x1, /* u# */ + /** The descriptor is a constant buffer view, bound to a cb# register. */ VKD3D_SHADER_DESCRIPTOR_TYPE_CBV = 0x2, /* cb# */ + /** The descriptor is a sampler, bound to a s# register. */ VKD3D_SHADER_DESCRIPTOR_TYPE_SAMPLER = 0x3, /* s# */
VKD3D_FORCE_32_BIT_ENUM(VKD3D_SHADER_DESCRIPTOR_TYPE), };
+/** + * A common structure describing the mapping a DXBC descriptor or descriptor + * array to a SPIR-V descriptor or descriptor array. + */ struct vkd3d_shader_descriptor_binding { + /** The set of the Vulkan descriptor. */ unsigned int set; + /** The binding index, within the set, of the Vulkan descriptor. */ unsigned int binding; - unsigned int count; /* This must be 1 in this version of vkd3d-shader. */ + /** + * The size of this descriptor array. Descriptor arrays are not supported in + * this version of vkd3d-shader, and therefore this value must be 1. + */ + unsigned int count; };
enum vkd3d_shader_binding_flag @@ -203,67 +226,136 @@ struct vkd3d_shader_parameter } u; };
+/** + * Describes the mapping of a single DXBC resource or resource array to SPIR-V. + * This structure is used in struct vkd3d_shader_interface_info. + */ struct vkd3d_shader_resource_binding { + /** The type of this descriptor. */ enum vkd3d_shader_descriptor_type type; + /** + * Register space of the DXBC descriptor. If the source format does not + * support multiple register spaces, this parameter must be set to 0. + */ unsigned int register_space; + /** Register index of the DXBC descriptor. */ unsigned int register_index; enum vkd3d_shader_visibility shader_visibility; - unsigned int flags; /* vkd3d_shader_binding_flag */ + /** A combination of zero or more elements of vkd3d_shader_binding_flag. */ + unsigned int flags;
struct vkd3d_shader_descriptor_binding binding; };
#define VKD3D_SHADER_DUMMY_SAMPLER_INDEX ~0u
+/** + * Describes the mapping of a DXBC resource-sampler pair to a SPIR-V combined + * sampler (i.e. sampled image). This structure is used in struct + * vkd3d_shader_interface_info. + */ struct vkd3d_shader_combined_resource_sampler { + /** + * Register space of the DXBC resource. Ifthe source format does not + * support multiple register spaces, this parameter must be set to 0. + */ unsigned int resource_space; + /** Register index of the DXBC resource. */ unsigned int resource_index; + /** + * Register space of the DXBC sampler. Ifthe source format does not + * support multiple register spaces, this parameter must be set to 0. + */ unsigned int sampler_space; + /** Register index of the DXBC sampler. */ unsigned int sampler_index; enum vkd3d_shader_visibility shader_visibility; - unsigned int flags; /* vkd3d_shader_binding_flag */ + /** A combination of zero or more elements of vkd3d_shader_binding_flag. */ + unsigned int flags;
struct vkd3d_shader_descriptor_binding binding; };
+/** + * Describes the mapping of a single DXBC UAV counter to SPIR-V. This structure + * is used in struct vkd3d_shader_interface_info. + */ struct vkd3d_shader_uav_counter_binding { + /** + * Register space of the DXBC UAV descriptor. If the source format does not + * support multiple register spaces, this parameter must be set to 0. + */ unsigned int register_space; - unsigned int register_index; /* u# */ + /** Register index of the DXBC UAV descriptor. */ + unsigned int register_index; enum vkd3d_shader_visibility shader_visibility;
struct vkd3d_shader_descriptor_binding binding; unsigned int offset; };
+/** + * Describes the mapping of a single Direct3D push constant buffer to SPIR-V. + * This structure is used in struct vkd3d_shader_interface_info. + */ struct vkd3d_shader_push_constant_buffer { + /** + * Register space of the Direct3D descriptor. If the source format does not + * support multiple register spaces, this parameter must be set to 0. + */ unsigned int register_space; + /** Register index of the DXBC descriptor. */ unsigned int register_index; enum vkd3d_shader_visibility shader_visibility;
- unsigned int offset; /* in bytes */ - unsigned int size; /* in bytes */ + /** Offset, in bytes, in the SPIR-V push constant buffer. */ + unsigned int offset; + /** Size, in bytes. */ + unsigned int size; };
-/* Extends vkd3d_shader_compile_info. */ +/** + * A chained structure describing the correspondence between source and target + * bindings of a compiled shader. This structure consists of several similar + * arrays of structures, each element of which describes a single mapping from + * a DXBC binding descriptor to a SPIR-V binding descriptor. + * + * This structure is optional. If omitted, vkd3d_shader_compile() will behave + * as if no descriptors had been passed. + * + * This structure extends vkd3d_shader_compile_info. + * + * This structure contains only input parameters. + */ struct vkd3d_shader_interface_info { + /** Must be set to VKD3D_SHADER_STRUCTURE_TYPE_INTERFACE_INFO. */ enum vkd3d_shader_structure_type type; + /** Optional pointer to a structure containing further parameters. */ const void *next;
+ /** An array of bindings for shader resource descriptors. */ const struct vkd3d_shader_resource_binding *bindings; + /** Size, in elements, of \ref bindings. */ unsigned int binding_count;
+ /** An array of bindings for push constant buffers. */ const struct vkd3d_shader_push_constant_buffer *push_constant_buffers; + /** Size, in elements, of \ref push_constant_buffers. */ unsigned int push_constant_buffer_count;
+ /** An array of bindings for combined samplers. */ const struct vkd3d_shader_combined_resource_sampler *combined_samplers; + /** Size, in elements, of \ref combined_samplers. */ unsigned int combined_sampler_count;
+ /** An array of bindings for UAV counters. */ const struct vkd3d_shader_uav_counter_binding *uav_counters; + /** Size, in elements, of \ref uav_counters. */ unsigned int uav_counter_count; };
On Thu, 27 Aug 2020 at 07:46, Zebediah Figura z.figura12@gmail.com wrote:
+/** The type of a shader resource descriptor. */ enum vkd3d_shader_descriptor_type {
- VKD3D_SHADER_DESCRIPTOR_TYPE_SRV = 0x0, /* t# */
/** The descriptor is a shader resource view, bound to a t# register. */
VKD3D_SHADER_DESCRIPTOR_TYPE_SRV = 0x0,
/** The descriptor is an unordered access view, bound to a u# register. */ VKD3D_SHADER_DESCRIPTOR_TYPE_UAV = 0x1, /* u# */
/** The descriptor is a constant buffer view, bound to a cb# register. */ VKD3D_SHADER_DESCRIPTOR_TYPE_CBV = 0x2, /* cb# */
/** The descriptor is a sampler, bound to a s# register. */ VKD3D_SHADER_DESCRIPTOR_TYPE_SAMPLER = 0x3, /* s# */
VKD3D_FORCE_32_BIT_ENUM(VKD3D_SHADER_DESCRIPTOR_TYPE),
};
I think I'd either leave the t#/u#/cb#/s# comments as they are, or write something slightly more elaborate. They make sense in the context of D3D assembly or byte code, but wouldn't necessarily when compiling e.g. HLSL to GLSL.
+/**
- A common structure describing the mapping a DXBC descriptor or descriptor
- array to a SPIR-V descriptor or descriptor array.
- */
struct vkd3d_shader_descriptor_binding {
- /** The set of the Vulkan descriptor. */ unsigned int set;
- /** The binding index, within the set, of the Vulkan descriptor. */ unsigned int binding;
- unsigned int count; /* This must be 1 in this version of vkd3d-shader. */
- /**
* The size of this descriptor array. Descriptor arrays are not supported in* this version of vkd3d-shader, and therefore this value must be 1.*/- unsigned int count;
};
The vkd3d_shader_descriptor_binding structure doesn't describe the mapping as such; it describes the bind point in the target environment. It should also be noted that the target environment isn't necessarily Vulkan; SPIR-V for example can be used with OpenGL as well.
+/**
- Describes the mapping of a single DXBC resource or resource array to SPIR-V.
- This structure is used in struct vkd3d_shader_interface_info.
- */
struct vkd3d_shader_resource_binding {
- /** The type of this descriptor. */ enum vkd3d_shader_descriptor_type type;
- /**
* Register space of the DXBC descriptor. If the source format does not* support multiple register spaces, this parameter must be set to 0.*/- /** Register index of the DXBC descriptor. */ unsigned int register_index; enum vkd3d_shader_visibility shader_visibility;
- unsigned int flags; /* vkd3d_shader_binding_flag */
/** A combination of zero or more elements of vkd3d_shader_binding_flag. */
unsigned int flags;
struct vkd3d_shader_descriptor_binding binding;
};
Somewhat similarly, I think it makes more sense to describe this in terms of mapping between the shader and its target environment. I.e., the vkd3d_shader_interface_info structure performs a function similar to the root signature in d3d12.
+/**
- Describes the mapping of a DXBC resource-sampler pair to a SPIR-V combined
- sampler (i.e. sampled image). This structure is used in struct
- vkd3d_shader_interface_info.
- */
struct vkd3d_shader_combined_resource_sampler {
- /**
* Register space of the DXBC resource. Ifthe source format does not* support multiple register spaces, this parameter must be set to 0.*/
"If the"
+/**
- Describes the mapping of a single Direct3D push constant buffer to SPIR-V.
- This structure is used in struct vkd3d_shader_interface_info.
- */
struct vkd3d_shader_push_constant_buffer {
- /**
* Register space of the Direct3D descriptor. If the source format does not* support multiple register spaces, this parameter must be set to 0.*/- /** Register index of the DXBC descriptor. */ unsigned int register_index; enum vkd3d_shader_visibility shader_visibility;
- unsigned int offset; /* in bytes */
- unsigned int size; /* in bytes */
- /** Offset, in bytes, in the SPIR-V push constant buffer. */
- unsigned int offset;
- /** Size, in bytes. */
- unsigned int size;
};
This maps a range of push constants to a constant buffer.
+/**
- A chained structure describing the correspondence between source and target
- bindings of a compiled shader. This structure consists of several similar
- arrays of structures, each element of which describes a single mapping from
- a DXBC binding descriptor to a SPIR-V binding descriptor.
Like above, think of it as describing the interface between the shader (either source or target) and the target environment. (In some ways that's equivalent to describing a mapping between the source and target shaders of course, but the specifics depend on the target shader type.)
- This structure is optional. If omitted, vkd3d_shader_compile() will behave
- as if no descriptors had been passed.
Actually, it will use a default mapping; see the "done:" label in vkd3d_dxbc_compiler_get_descriptor_binding(). It will also do that when the binding count is 0, which we should probably fix.
- This structure extends vkd3d_shader_compile_info.
- This structure contains only input parameters.
- */
struct vkd3d_shader_interface_info {
/** Must be set to VKD3D_SHADER_STRUCTURE_TYPE_INTERFACE_INFO. */ enum vkd3d_shader_structure_type type;
/** Optional pointer to a structure containing further parameters. */ const void *next;
/** An array of bindings for shader resource descriptors. */ const struct vkd3d_shader_resource_binding *bindings;
/** Size, in elements, of \ref bindings. */ unsigned int binding_count;
/** An array of bindings for push constant buffers. */ const struct vkd3d_shader_push_constant_buffer *push_constant_buffers;
/** Size, in elements, of \ref push_constant_buffers. */ unsigned int push_constant_buffer_count;
/** An array of bindings for combined samplers. */ const struct vkd3d_shader_combined_resource_sampler *combined_samplers;
/** Size, in elements, of \ref combined_samplers. */ unsigned int combined_sampler_count;
/** An array of bindings for UAV counters. */ const struct vkd3d_shader_uav_counter_binding *uav_counters;
/** Size, in elements, of \ref uav_counters. */ unsigned int uav_counter_count;
};
"pointer to an array"
On 8/27/20 11:18 AM, Henri Verbeet wrote:
On Thu, 27 Aug 2020 at 07:46, Zebediah Figura z.figura12@gmail.com wrote:
+/** The type of a shader resource descriptor. */ enum vkd3d_shader_descriptor_type {
- VKD3D_SHADER_DESCRIPTOR_TYPE_SRV = 0x0, /* t# */
/** The descriptor is a shader resource view, bound to a t# register. */
VKD3D_SHADER_DESCRIPTOR_TYPE_SRV = 0x0,
/** The descriptor is an unordered access view, bound to a u# register. */ VKD3D_SHADER_DESCRIPTOR_TYPE_UAV = 0x1, /* u# */
/** The descriptor is a constant buffer view, bound to a cb# register. */ VKD3D_SHADER_DESCRIPTOR_TYPE_CBV = 0x2, /* cb# */
/** The descriptor is a sampler, bound to a s# register. */ VKD3D_SHADER_DESCRIPTOR_TYPE_SAMPLER = 0x3, /* s# */
VKD3D_FORCE_32_BIT_ENUM(VKD3D_SHADER_DESCRIPTOR_TYPE),
};
I think I'd either leave the t#/u#/cb#/s# comments as they are, or write something slightly more elaborate. They make sense in the context of D3D assembly or byte code, but wouldn't necessarily when compiling e.g. HLSL to GLSL.
+/**
- A common structure describing the mapping a DXBC descriptor or descriptor
- array to a SPIR-V descriptor or descriptor array.
- */
struct vkd3d_shader_descriptor_binding {
- /** The set of the Vulkan descriptor. */ unsigned int set;
- /** The binding index, within the set, of the Vulkan descriptor. */ unsigned int binding;
- unsigned int count; /* This must be 1 in this version of vkd3d-shader. */
- /**
* The size of this descriptor array. Descriptor arrays are not supported in* this version of vkd3d-shader, and therefore this value must be 1.*/- unsigned int count;
};
The vkd3d_shader_descriptor_binding structure doesn't describe the mapping as such; it describes the bind point in the target environment. It should also be noted that the target environment isn't necessarily Vulkan; SPIR-V for example can be used with OpenGL as well.
+/**
- Describes the mapping of a single DXBC resource or resource array to SPIR-V.
- This structure is used in struct vkd3d_shader_interface_info.
- */
struct vkd3d_shader_resource_binding {
- /** The type of this descriptor. */ enum vkd3d_shader_descriptor_type type;
- /**
* Register space of the DXBC descriptor. If the source format does not* support multiple register spaces, this parameter must be set to 0.*/- /** Register index of the DXBC descriptor. */ unsigned int register_index; enum vkd3d_shader_visibility shader_visibility;
- unsigned int flags; /* vkd3d_shader_binding_flag */
/** A combination of zero or more elements of vkd3d_shader_binding_flag. */
unsigned int flags;
struct vkd3d_shader_descriptor_binding binding;
};
Somewhat similarly, I think it makes more sense to describe this in terms of mapping between the shader and its target environment. I.e., the vkd3d_shader_interface_info structure performs a function similar to the root signature in d3d12.
+/**
- Describes the mapping of a DXBC resource-sampler pair to a SPIR-V combined
- sampler (i.e. sampled image). This structure is used in struct
- vkd3d_shader_interface_info.
- */
struct vkd3d_shader_combined_resource_sampler {
- /**
* Register space of the DXBC resource. Ifthe source format does not* support multiple register spaces, this parameter must be set to 0.*/"If the"
+/**
- Describes the mapping of a single Direct3D push constant buffer to SPIR-V.
- This structure is used in struct vkd3d_shader_interface_info.
- */
struct vkd3d_shader_push_constant_buffer {
- /**
* Register space of the Direct3D descriptor. If the source format does not* support multiple register spaces, this parameter must be set to 0.*/- /** Register index of the DXBC descriptor. */ unsigned int register_index; enum vkd3d_shader_visibility shader_visibility;
- unsigned int offset; /* in bytes */
- unsigned int size; /* in bytes */
- /** Offset, in bytes, in the SPIR-V push constant buffer. */
- unsigned int offset;
- /** Size, in bytes. */
- unsigned int size;
};
This maps a range of push constants to a constant buffer.
+/**
- A chained structure describing the correspondence between source and target
- bindings of a compiled shader. This structure consists of several similar
- arrays of structures, each element of which describes a single mapping from
- a DXBC binding descriptor to a SPIR-V binding descriptor.
Like above, think of it as describing the interface between the shader (either source or target) and the target environment. (In some ways that's equivalent to describing a mapping between the source and target shaders of course, but the specifics depend on the target shader type.)
I might be overthinking, but describing it in such terms seems a little too abstract, such that it's not clear what exactly should get put in this structure. I'll try to come up with a more detailed compromise...
Incidentally, the terminology used in dependent structures seems pretty closely tied to DXBC -> SPIR-V, and so I was inclined to reflect that in the documentation. I'm not sure if there's an intent for this structure to be more generic (aside from DXBC -> GLSL, it's not obvious to me what it'd be used for, unless we're for some reason interested in compiling to DXBC or between GLSL and SPIR-V), but perhaps using different field names would help (e.g. not differentiating "space" and "set", or "index" and "binding").
- This structure is optional. If omitted, vkd3d_shader_compile() will behave
- as if no descriptors had been passed.
Actually, it will use a default mapping; see the "done:" label in vkd3d_dxbc_compiler_get_descriptor_binding(). It will also do that when the binding count is 0, which we should probably fix.
- This structure extends vkd3d_shader_compile_info.
- This structure contains only input parameters.
- */
struct vkd3d_shader_interface_info {
/** Must be set to VKD3D_SHADER_STRUCTURE_TYPE_INTERFACE_INFO. */ enum vkd3d_shader_structure_type type;
/** Optional pointer to a structure containing further parameters. */ const void *next;
/** An array of bindings for shader resource descriptors. */ const struct vkd3d_shader_resource_binding *bindings;
/** Size, in elements, of \ref bindings. */ unsigned int binding_count;
/** An array of bindings for push constant buffers. */ const struct vkd3d_shader_push_constant_buffer *push_constant_buffers;
/** Size, in elements, of \ref push_constant_buffers. */ unsigned int push_constant_buffer_count;
/** An array of bindings for combined samplers. */ const struct vkd3d_shader_combined_resource_sampler *combined_samplers;
/** Size, in elements, of \ref combined_samplers. */ unsigned int combined_sampler_count;
/** An array of bindings for UAV counters. */ const struct vkd3d_shader_uav_counter_binding *uav_counters;
/** Size, in elements, of \ref uav_counters. */ unsigned int uav_counter_count;
};
"pointer to an array"
On Thu, 27 Aug 2020 at 23:38, Zebediah Figura z.figura12@gmail.com wrote:
+/**
- A chained structure describing the correspondence between source and target
- bindings of a compiled shader. This structure consists of several similar
- arrays of structures, each element of which describes a single mapping from
- a DXBC binding descriptor to a SPIR-V binding descriptor.
Like above, think of it as describing the interface between the shader (either source or target) and the target environment. (In some ways that's equivalent to describing a mapping between the source and target shaders of course, but the specifics depend on the target shader type.)
I might be overthinking, but describing it in such terms seems a little too abstract, such that it's not clear what exactly should get put in this structure. I'll try to come up with a more detailed compromise...
It's probably one of those things that would benefit from a couple of concrete examples.
Incidentally, the terminology used in dependent structures seems pretty closely tied to DXBC -> SPIR-V, and so I was inclined to reflect that in the documentation. I'm not sure if there's an intent for this structure to be more generic (aside from DXBC -> GLSL, it's not obvious to me what it'd be used for, unless we're for some reason interested in compiling to DXBC or between GLSL and SPIR-V), but perhaps using different field names would help (e.g. not differentiating "space" and "set", or "index" and "binding").
It's more D3D -> Vulkan, but yes, there's that. The terminology here could probably do with a review, but note that e.g. register spaces and descriptor sets aren't quite equivalents.
In terms of target environments, it's mostly OpenGL and Vulkan, which implies SPIR-V and GLSL. There may also be a case to be made for a Metal/MSL target. In theory it could also be used for remapping resource bindings for D3D targets (i.e., with HLSL -> dxbc-tpf, or even dxbc-tpf -> dxbc-tpf); I'm not sure whether there's a practical use for that though.
Hi,
While running your changed tests, I think I found new failures. Being a bot and all I'm not very good at pattern recognition, so I might be wrong, but could you please double-check?
Full results can be found at: https://testbot.winehq.org/JobDetails.pl?Key=77658
Your paranoid android.
=== debiant (build log) ===
error: patch failed: configure.ac:29 Task: Patch failed to apply
=== debiant (build log) ===
error: patch failed: configure.ac:29 Task: Patch failed to apply
On Thu, 27 Aug 2020 at 07:46, Zebediah Figura z.figura12@gmail.com wrote:
diff --git a/Doxyfile.in b/Doxyfile.in new file mode 100644 index 00000000..f5f88dbf --- /dev/null +++ b/Doxyfile.in @@ -0,0 +1,17 @@ +# Doxyfile 1.8.18
+DOXYFILE_ENCODING = UTF-8 +PROJECT_NAME = @PACKAGE_NAME@ +PROJECT_NUMBER = @PACKAGE_VERSION@ +PROJECT_BRIEF = "D3D12 to Vulkan translation library"
For what it's worth, in the pkg-config description we use "The vkd3d 3D Graphics Library".
+OUTPUT_DIRECTORY = @srcdir@/doc
I'm by no means a Doxygen expert, but is that correct? I would expect the output to go to @builddir@.
+DX_INIT_DOXYGEN(vkd3d, [Doxyfile], [doc])
It often happens to work without, but I think it's good practice to quote literal macro arguments.
+/** Result codes returned by some vkd3d functions. */ enum vkd3d_result {
- /** Success. */ VKD3D_OK = 0,
- VKD3D_ERROR = -1, /* unspecified failure */
- /** An unspecified failure occurred. */
- VKD3D_ERROR = -1,
- /** There are not enough resources available to complete the operation. */ VKD3D_ERROR_OUT_OF_MEMORY = -2,
- /** One or more parameters passed to a vkd3d function were invalid. */ VKD3D_ERROR_INVALID_ARGUMENT = -3,
- /** A shader passed to a vkd3d function was invalid. */ VKD3D_ERROR_INVALID_SHADER = -4,
- /** The operation is not implemented in this version of vkd3d. */ VKD3D_ERROR_NOT_IMPLEMENTED = -5,
Error codes have negative values; non-error codes never do.
On 8/27/20 11:17 AM, Henri Verbeet wrote:
On Thu, 27 Aug 2020 at 07:46, Zebediah Figura z.figura12@gmail.com wrote:
diff --git a/Doxyfile.in b/Doxyfile.in new file mode 100644 index 00000000..f5f88dbf --- /dev/null +++ b/Doxyfile.in @@ -0,0 +1,17 @@ +# Doxyfile 1.8.18
+DOXYFILE_ENCODING = UTF-8 +PROJECT_NAME = @PACKAGE_NAME@ +PROJECT_NUMBER = @PACKAGE_VERSION@ +PROJECT_BRIEF = "D3D12 to Vulkan translation library"
For what it's worth, in the pkg-config description we use "The vkd3d 3D Graphics Library".
Sure. I copied this one from the git description; I'll change it to that one.
+OUTPUT_DIRECTORY = @srcdir@/doc
I'm by no means a Doxygen expert, but is that correct? I would expect the output to go to @builddir@.
That was probably a mistake on my part.
+DX_INIT_DOXYGEN(vkd3d, [Doxyfile], [doc])
It often happens to work without, but I think it's good practice to quote literal macro arguments.
+/** Result codes returned by some vkd3d functions. */ enum vkd3d_result {
- /** Success. */ VKD3D_OK = 0,
- VKD3D_ERROR = -1, /* unspecified failure */
- /** An unspecified failure occurred. */
- VKD3D_ERROR = -1,
- /** There are not enough resources available to complete the operation. */ VKD3D_ERROR_OUT_OF_MEMORY = -2,
- /** One or more parameters passed to a vkd3d function were invalid. */ VKD3D_ERROR_INVALID_ARGUMENT = -3,
- /** A shader passed to a vkd3d function was invalid. */ VKD3D_ERROR_INVALID_SHADER = -4,
- /** The operation is not implemented in this version of vkd3d. */ VKD3D_ERROR_NOT_IMPLEMENTED = -5,
Error codes have negative values; non-error codes never do.
Good addition, thanks.
-
Henri Verbeet -
Marvin -
Zebediah Figura