[PATCH vkd3d v3 1/5] include: Add basic documentation for vkd3d_types.h.
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. Signed-off-by: Zebediah Figura <z.figura12(a)gmail.com> --- v3: Default PostScript to off; add "all" and "clean" rules. .gitignore | 2 + Doxyfile.in | 17 ++ Makefile.am | 4 + configure.ac | 4 + include/vkd3d_types.h | 18 +- m4/ax_prog_doxygen.m4 | 586 ++++++++++++++++++++++++++++++++++++++++++ 6 files changed, 630 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..a20e6f02 --- /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 = "The vkd3d 3D Graphics Library" +OUTPUT_DIRECTORY = 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..460818c4 100644 --- a/Makefile.am +++ b/Makefile.am @@ -167,6 +167,10 @@ demos_triangle_CFLAGS = $(DEMOS_CFLAGS) demos_triangle_LDADD = $(DEMOS_LDADD) endif +(a)DX_RULES@ +all: doxygen-doc +CLEANFILES += DX_CLEANFILES + EXTRA_DIST += $(vkd3d_test_headers) $(vkd3d_demos_headers) VKD3D_V_WIDL = $(vkd3d_v_widl_(a)AM_V@) diff --git a/configure.ac b/configure.ac index ca9d7600..e665c5cf 100644 --- a/configure.ac +++ b/configure.ac @@ -29,6 +29,10 @@ 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_PS_FEATURE([OFF]) +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..020eb240 100644 --- a/include/vkd3d_types.h +++ b/include/vkd3d_types.h @@ -23,15 +23,31 @@ 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. Error codes always have + * negative values; non-error codes never do. + */ 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(a)ben-kiki.org> +# Copyright (c) 2015 Olaf Mandel <olaf(a)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 +]) -- 2.28.0
Signed-off-by: Zebediah Figura <z.figura12(a)gmail.com> --- 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), -- 2.28.0
Signed-off-by: Henri Verbeet <hverbeet(a)codeweavers.com>
Signed-off-by: Zebediah Figura <z.figura12(a)gmail.com> --- include/vkd3d_shader.h | 91 +++++++++++++++++++++++++++++++++++++++--- 1 file changed, 86 insertions(+), 5 deletions(-) diff --git a/include/vkd3d_shader.h b/include/vkd3d_shader.h index da05f2c3..9150f142 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. + * + * 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 value. */ 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_shader_compile(). 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 option. */ enum vkd3d_shader_compile_option_name name; + /** + * A value associated with the option. The type and interpretation of the + * value depends on the option 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 a GPU shader, in text or byte-code format. */ struct vkd3d_shader_code { + /** Pointer to the code. */ const void *code; + /** Size of \a code, in bytes. */ size_t size; }; @@ -264,46 +289,102 @@ 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; + /** + * Pointer to an array of compilation options. This field is ignored if + * \ref option_count is zero, but must be valid otherwise. + * + * If the same option is specified multiple times, only 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, which may be used in error messages or + * debug information. This parameter is optional and may be NULL. + */ const char *source_name; }; -- 2.28.0
Signed-off-by: Henri Verbeet <hverbeet(a)codeweavers.com>
Signed-off-by: Zebediah Figura <z.figura12(a)gmail.com> --- include/vkd3d_shader.h | 110 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 110 insertions(+) diff --git a/include/vkd3d_shader.h b/include/vkd3d_shader.h index 9150f142..7e011e32 100644 --- a/include/vkd3d_shader.h +++ b/include/vkd3d_shader.h @@ -864,13 +864,99 @@ 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 Pointer to 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 Pointer to 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. + * + * This version of vkd3d-shader 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(). + * + * Depending on the source and target types, 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 + * This string is null-terminated and UTF-8 encoded. + * \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, @@ -883,6 +969,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); -- 2.28.0
Signed-off-by: Henri Verbeet <hverbeet(a)codeweavers.com>
Signed-off-by: Zebediah Figura <z.figura12(a)gmail.com> --- v3: Correct documentation for struct vkd3d_shader_push_constant_buffer. include/vkd3d_shader.h | 154 ++++++++++++++++++++++++++++++++++++++--- 1 file changed, 143 insertions(+), 11 deletions(-) diff --git a/include/vkd3d_shader.h b/include/vkd3d_shader.h index 7e011e32..cc5615c9 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,51 @@ 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# */ - VKD3D_SHADER_DESCRIPTOR_TYPE_UAV = 0x1, /* u# */ - VKD3D_SHADER_DESCRIPTOR_TYPE_CBV = 0x2, /* cb# */ - VKD3D_SHADER_DESCRIPTOR_TYPE_SAMPLER = 0x3, /* s# */ + /** + * The descriptor is a shader resource view. In Direct3D assembly, this is + * bound to a t# register. + */ + VKD3D_SHADER_DESCRIPTOR_TYPE_SRV = 0x0, + /** + * The descriptor is an unordered access view. In Direct3D assembly, this is + * bound to a u# register. + */ + VKD3D_SHADER_DESCRIPTOR_TYPE_UAV = 0x1, + /** + * The descriptor is a constant buffer view. In Direct3D assembly, this is + * bound to a cb# register. + */ + VKD3D_SHADER_DESCRIPTOR_TYPE_CBV = 0x2, + /** + * The descriptor is a sampler. In Direct3D assembly, this is bound to an s# + * register. + */ + VKD3D_SHADER_DESCRIPTOR_TYPE_SAMPLER = 0x3, VKD3D_FORCE_32_BIT_ENUM(VKD3D_SHADER_DESCRIPTOR_TYPE), }; +/** + * A common structure describing the bind point of a descriptor or descriptor + * array in the target environment. + */ struct vkd3d_shader_descriptor_binding { + /** + * The set of the descriptor. If the target environment does not support + * descriptor sets, this value must be set to 0. + */ unsigned int set; + /** The binding index of the 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 +241,161 @@ struct vkd3d_shader_parameter } u; }; +/** + * Describes the mapping of a single resource or resource array to its binding + * point in the target environment. + * + * For example, to map a Direct3D SRV with register space 2, register "t3" to + * a Vulkan descriptor in set 4 and with binding 5, set the following members: + * - \a type = VKD3D_SHADER_DESCRIPTOR_TYPE_SRV + * - \a register_space = 2 + * - \a register_index = 3 + * - \a binding.set = 4 + * - \a binding.binding = 5 + * - \a binding.count = 1 + * + * 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 Direct3D resource. 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 resource. */ unsigned int register_index; + /** Shader stage(s) to which the resource is visible. */ 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; + /** The binding in the target environment. */ struct vkd3d_shader_descriptor_binding binding; }; #define VKD3D_SHADER_DUMMY_SAMPLER_INDEX ~0u +/** + * Describes the mapping of a Direct3D resource-sampler pair to a 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 Direct3D resource. If the source format does not + * support multiple register spaces, this parameter must be set to 0. + */ unsigned int resource_space; + /** Register index of the Direct3D resource. */ unsigned int resource_index; + /** + * Register space of the Direct3D sampler. If the source format does not + * support multiple register spaces, this parameter must be set to 0. + */ unsigned int sampler_space; + /** Register index of the Direct3D sampler. */ unsigned int sampler_index; + /** Shader stage(s) to which the resource is visible. */ 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; + /** The binding in the target environment. */ struct vkd3d_shader_descriptor_binding binding; }; +/** + * Describes the mapping of a single Direct3D UAV counter. + * + * This structure is used in struct vkd3d_shader_interface_info. + */ struct vkd3d_shader_uav_counter_binding { + /** + * Register space of the Direct3D 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 Direct3D UAV descriptor. */ + unsigned int register_index; + /** Shader stage(s) to which the UAV counter is visible. */ enum vkd3d_shader_visibility shader_visibility; + /** The binding in the target environment. */ struct vkd3d_shader_descriptor_binding binding; unsigned int offset; }; +/** + * Describes the mapping of a Direct3D constant buffer to a range of push + * constants in the target environment. + * + * This structure is used in struct vkd3d_shader_interface_info. + */ struct vkd3d_shader_push_constant_buffer { + /** + * Register space of the Direct3D resource. 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 Direct3D resource. */ unsigned int register_index; + /** Shader stage(s) to which the resource is visible. */ enum vkd3d_shader_visibility shader_visibility; - unsigned int offset; /* in bytes */ - unsigned int size; /* in bytes */ + /** Offset, in bytes, of the target push constants. */ + unsigned int offset; + /** Size, in bytes, of the target push constants. */ + unsigned int size; }; -/* Extends vkd3d_shader_compile_info. */ +/** + * A chained structure describing the interface between a compiled shader and + * the target environment. + * + * For example, when compiling Direct3D shader byte code to SPIR-V, this + * structure contains mappings from Direct3D descriptor registers to SPIR-V + * descriptor bindings. + * + * This structure is optional. If omitted, vkd3d_shader_compile() will use a + * default mapping, in which resources are mapped to sequential bindings in + * register set 0. + * + * 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; + /** Pointer to 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; + /** Pointer to 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; + /** Pointer to 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; + /** Pointer to 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; }; -- 2.28.0
Signed-off-by: Henri Verbeet <hverbeet(a)codeweavers.com>
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=77822 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 Tue, 1 Sep 2020 at 06:04, Zebediah Figura <z.figura12(a)gmail.com> wrote:
diff --git a/Makefile.am b/Makefile.am index 58b3174c..460818c4 100644 --- a/Makefile.am +++ b/Makefile.am @@ -167,6 +167,10 @@ demos_triangle_CFLAGS = $(DEMOS_CFLAGS) demos_triangle_LDADD = $(DEMOS_LDADD) endif
+(a)DX_RULES@ +all: doxygen-doc When configured with --disable-doxygen-doc (or, when doxygen is not installed) there is no doxygen-doc target, and this fails.
+CLEANFILES += DX_CLEANFILES This doesn't work. (Did you mean $(DX_CLEANFILES)?)
participants (4)
-
Henri Verbeet -
Henri Verbeet -
Marvin -
Zebediah Figura