mirror of
https://github.com/status-im/Vulkan-Docs.git
synced 2025-01-20 19:29:58 +00:00
f4c4113d07
* Bump API patch number and header version number to 21 for this update.
Github Issues:
* Clarify how <<features-supported-sample-counts,sample count queries>>
relate to the limits in slink:VkPhysicalDeviceLimits. (public issue
185).
* Clarify in the <<interfaces-iointerfaces,Shader Input and Output
Interfaces>> section that shader output variables have undefined values
until the shader writes to them (public issue 240).
* Specify the implicit value of image parameters that cannot be set in
slink:VkSwapchainCreateInfo::pname:flags, pname:imageType,
pname:mipLevels, pname:samples, pname:tiling, and pname:initialLayout
(public issue 243).
* Make use of code:NULL and code:VK_NULL_HANDLE consistent in the
VK_KHR_swapchain extension (public issue 276).
Internal Issues:
* Clarify that presenting an image to a display surface swapchain applies
the display surface's mode, and that destroying a display surface
swapchain may reset the display's mode, in the VK_KHR_display_swapchain
extension (internal issue 247).
* Better describe what a slink:VkSurfaceKHR is, and that creating one does
not set a mode, in the VK_KHR_display extension. This is a round-about
way of pointing out that mode setting is not covered by the extension,
but rather is performed as a side effect of presentation (internal issue
247).
* Add more valid usage statements to flink:vkQueuePresentKHR command when
the VK_KHR_display_swapchain extension is present (internal issue
247).
* Add more includes to the VK_KHR_swapchain extension to better document
interactions with VK_KHR_display_swapchain (internal issue 247).
* Clarify restrictions on location aliasing in the
<<fxvertex,Fixed-Function Vertex Processing>> section (internal issue
370).
* Add mathematical description of blitting to flink:vkCmdBlitImage, and
link it to the <<textures,Image Operations>> chapter. Use mathematical
notation for ranges of texel coordinates in the <<textures,Image
Operations>> chapter. Fixed miscellaneous validity statements for
flink:vkCmdBlit and slink:VkImageBlit (internal issue 382).
Other Commits:
* Added a valid usage rule to flink:VkGraphicsPipelineCreateInfo that the
ename:VK_PRIMITIVE_TOPOLOGY_PATCH_LIST topology must only be used when
tessellation shaders are used.
* Expand the style guide into a formal "Procedures and Conventions"
document. Add a API Naming Conventions section, move most of the API
Specification Appendix C (Layers and Extensions) content into the new
document, and define the resulting procedures as mandatory (where
relevant). This more clearly separates use vs. specification of Vulkan
APIs.
* Update vk_platform.h to handle 32-bit ARMv8 binaries.
* Various minor cleanups to the Makefile and build process.
There's apparently some sort of parsing issue with comments in vkspec.conf,
so they are pulled out here for now.
// The [efs]link macros insert named xrefs to the specified target
// enumerated type, function, or structure name, and are also used
// for validation.
// Could also use <xref linkend="{target}"/>
// The [efsp]text macros insert the specified target enumerant, function,
// structure or parameter name, and are NOT used for validation. They are
// otherwise identical to the [efsp]name macros above, and are intended
// to get the proper formatting for terms that are *not* actually API
// features, e.g. wildcards or partial names.
// The [efsp]name macros insert the specified target enumerant, function,
// structure or parameter name, and are also used for validation.
// The basetype macro inserts text for the specified base (scalar) type. It
// is not currently used for validation, but will be eventually
// The code macro inserts text for the specified shader code function or
// variable.
// I have no idea what the old 'vkkeyword' macro does, but it appears
// to be unused, so removed it and archived here for the moment.
//
// (?u)^(?P<name>):(?P<subslist>\S*?)(\[(?P<passtext>.*?)\])$=vkkeyword
//
// [vkkeyword-inlinemacro]
// {passtext}
--------------- PDF Generation ----------------
vkspec-dblatex.xsl is XSL specific to a2x->dblatex->PDF spec generation.
It is a very slightly modified version of
/etc/asciidoc/dblatex/asciidoc-dblatex.xsl, as follows:
> <xsl:param name="latex.hyperparam">colorlinks,linkcolor=black,pdfstartview=FitH</xsl:param>
> <xsl:param name="doc.publisher.show">0</xsl:param>
> <xsl:param name="latex.output.revhistory">0</xsl:param>
and has been simplified to just those parameters. Additional templates
replacing those under
/usr/share/xml/docbook/stylesheet/dblatex/xsl/* can be added here.
--------------- XHTML Generation ----------------
vkspec-xhtml.css is CSS for the xhtml and chunked targets. It is pulled
in from docbook-xsl/common.xsl. This gives us direct control over the
CSS for the document, including support for markup styles.
--------------- Asciibook Stylesheets ----------------
docbook-xsl/chunked.xsl
docbook-xsl/common.xsl
docbook-xsl/xhtml.xsl
replace parts of the asciibook stylesheets normally found under
/etc/asciidoc/docbook-xsl
in order to generate consistent IDs on sections and to insert
MathJax <script> tags into HTML headers. More will be required for other
HTML output types.
--------------- Support for Math ----------------
mathjax-asciidoc.conf
mathjax-docbook.conf
mathjax.js
customize asciidoc macros for HTML and Docbook output to insert
MathJax <script> tags from mathjax.js, and properly pass through
math which has \begin{}\/end{} delimiters instead of $$\[\]\(\),
using the <?texmath delimiters="user"?> processing instruction.
Note that mathjax-docbook.conf is heavily conditionalized depending
on whether the final output format (which should be described in the
a2x-format variable) is 'pdf' or not, since Docbook passes through
math differently to dblatex vs. the HTML stylesheets.