From fbdde310fc6fddf4e9201171136241444bfa022d Mon Sep 17 00:00:00 2001 From: Jon Leech Date: Fri, 27 Nov 2020 22:22:43 -0800 Subject: [PATCH 1/2] This modifies the Asciidoctor HTML & PDF specs to compare asciidoctor latexmath rendering vs. the image approaches previously used. See the generated HTML / PDF in the Actions artifacts download and search for "Latexmath" (followed by "Old") versions of each equation. Relevant points: * The HTML output is not self-contained. It introduces an external dependency on the MathJax package on a CDN outside our control. * MathJax runs after the HTML page is loaded and takes noticeable time - initially you will see the raw latex markup, replaced and re-laid-out with the formatted math. * The PDF output introduces a new dependency on the asciidoctor-mathematical gem (the Khronos Docker image already has this). * The PDF math rendering quality is noticeably lower than the HTML rendering quality. --- specification/2.0/Makefile | 10 ++- specification/2.0/Specification.adoc | 114 +++++++++++++++++++++++++++ 2 files changed, 122 insertions(+), 2 deletions(-) diff --git a/specification/2.0/Makefile b/specification/2.0/Makefile index f9db1e5882..2e4bf009a2 100644 --- a/specification/2.0/Makefile +++ b/specification/2.0/Makefile @@ -31,7 +31,8 @@ $(GENERATED): $(wildcard schema/*.json) schema/glTF.schema.json > $(PROPREF).adoc # Spec targets for offline generation -# Requires an up-to-date asciidoctor and asciidoctor-pdf be installed +# Requires an up-to-date asciidoctor, asciidoctor-pdf, and +# asciidoctor-mathematical be installed # We recommend using the khronosgroup/vulkan-docs-base image on dockerhub ASCIIDOCTOR = asciidoctor SPECDEPS = $(SPEC).adoc $(GENERATED) @@ -42,8 +43,13 @@ $(SPEC).html: $(SPECDEPS) # :allow-url-read: is necessary for the embedded render.githubusers.com # math images to be processed for the PDF target. See # https://github.com/asciidoctor/asciidoctor-pdf/issues/369 +# asciidoctor-mathematical leaves intermediate images of equations behing. +# These are removed after creating the PDF. +STEMIMAGES = stem-*.png $(SPEC).pdf: $(SPECDEPS) - $(ASCIIDOCTOR) -b pdf -a allow-uri-read -r asciidoctor-pdf $(SPEC).adoc -o $@ + $(ASCIIDOCTOR) -b pdf -a allow-uri-read -r asciidoctor-pdf \ + -r asciidoctor-mathematical $(SPEC).adoc -o $@ + rm -f $(STEMIMAGES) clean: -rm -f $(GENERATED) $(TARGETS) diff --git a/specification/2.0/Specification.adoc b/specification/2.0/Specification.adoc index cfe98df82f..d73befb430 100644 --- a/specification/2.0/Specification.adoc +++ b/specification/2.0/Specification.adoc @@ -1584,6 +1584,20 @@ Runtimes are expected to use the following projection matrices. [[infinite-perspective-projection]] ==== Infinite perspective projection +*Latexmath* + +[latexmath] +++++ +\begin{bmatrix} +1 \over { a \times \tan(0.5 \times y) } & 0 & 0 & 0 \\ +0 & 1 \over { \tan(0.5 \times y) } & 0 & 0 \\ +0 & 0 & -1 & -2n \\ +0 & 0 & -1 & 0 +\end{bmatrix} +++++ + +*Old* + image:figures/infinite-perspective.png[pdfwidth=4in,align=left] where @@ -1596,6 +1610,20 @@ where [[finite-perspective-projection]] ==== Finite perspective projection +*Latexmath* + +[latexmath] +++++ +\begin{bmatrix} +1 \over { a \times \tan(0.5 \times y) } & 0 & 0 & 0 \\ +0 & 1 \over { \tan(0.5 \times y) } & 0 & 0 \\ +0 & 0 & { f + n } \over { n - f } & { 2 f n } \over { n - f } \\ +0 & 0 & -1 & 0 +\end{bmatrix} +++++ + +*Old* + image:figures/finite-perspective.png[pdfwidth=4in,align=left] where @@ -1609,6 +1637,20 @@ where [[orthographic-projection]] ==== Orthographic projection +*Latexmath* + +[latexmath] +++++ +\begin{bmatrix} +1 \over r & 0 & 0 & 0 \\ +0 & 1 \over t & 0 & 0 \\ +0 & 0 & 2 \over { n - f } & { f + n } \over { n - f } \\ +0 & 0 & 0 & 1 +\end{bmatrix} +++++ + +*Old* + image:figures/ortho.png[pdfwidth=4in,align=left] where @@ -2159,28 +2201,82 @@ We use the following notation: The specular reflection `specular_brdf(α)` is a microfacet BRDF +*Latexmath* + +[latexmath] +++++ +\text{MicrofacetBRDF} = \frac{G D}{4 \, \left|N \cdot L \right| \, \left| N \cdot V \right|} +++++ + +*Old* + image:https://render.githubusercontent.com/render/math?math=\displaystyle \text{MicrofacetBRDF} = \frac{G D}{4 \, \left|N \cdot L \right| \, \left| N \cdot V \right|}[format=svg] with the Trowbridge-Reitz/GGX microfacet distribution +*Latexmath* + +[latexmath] +++++ +D = \frac{\alpha^2 \, \chi^{+}(N \cdot H)}{\pi ((N \cdot H)^2 (\alpha^2 - 1) + 1)^2} +++++ + +*Old* + image:https://render.githubusercontent.com/render/math?math=\displaystyle D = \frac{\alpha^2 \, \chi^%2B(N \cdot H)}{\pi ((N \cdot H)^2 (\alpha^2 - 1) %2B 1)^2}[format=svg] and the separable form of the Smith joint masking-shadowing function +*Latexmath* + +[latexmath] +++++ +G = \frac{2 \, \left| N \cdot L \right| \, \chi^{+}(H \cdot L)}{\left| N \cdot L \right| + \sqrt{\alpha^2 + (1 - \alpha^2) (N \cdot L)^2}} \frac{2 \, \left| N \cdot V \right| \, \chi^{+}(H \cdot V)}{\left| N \cdot V \right| + \sqrt{\alpha^2 + (1 - \alpha^2) (N \cdot V)^2}} +++++ + +*Old* + image:https://render.githubusercontent.com/render/math?math=\displaystyle G = \frac{2 \, \left| N \cdot L \right| \, \chi^%2B(H \cdot L)}{\left| N \cdot L \right| %2B \sqrt{\alpha^2 %2B (1 - \alpha^2) (N \cdot L)^2}} \frac{2 \, \left| N \cdot V \right| \, \chi^%2B(H \cdot V)}{\left| N \cdot V \right| %2B \sqrt{\alpha^2 %2B (1 - \alpha^2) (N \cdot V)^2}}[format=svg] where χ^+^(*x*) denotes the Heaviside function: 1 if *x* > 0 and 0 if *x* <= 0. See <> for a derivation of the formulas. Introducing the visibility function +*Latexmath* + +[latexmath] +++++ +V = \frac{G}{4 \, \left| N \cdot L \right| \, \left| N \cdot V \right|} +++++ + +*Old* + image:https://render.githubusercontent.com/render/math?math=\displaystyle V = \frac{G}{4 \, \left| N \cdot L \right| \, \left| N \cdot V \right|}[format=svg] simplifies the original microfacet BRDF to +*Latexmath* + +[latexmath] +++++ +\text{MicrofacetBRDF} = V D +++++ + +*Old* + image:https://render.githubusercontent.com/render/math?math=\displaystyle \text{MicrofacetBRDF} = V D[format=svg] with +*Latexmath* + +[latexmath] +++++ +V = \frac{\, \chi^{+}(H \cdot L)}{\left| N \cdot L\right| + \sqrt{\alpha^2 + (1 - \alpha^2) (N \cdot L)^2}} \frac{\, \chi^{+}(H \cdot V)}{\left| N \cdot V \right| + \sqrt{\alpha^2 + (1 - \alpha^2) (N \cdot V)^2}} +++++ + +*Old* + image:https://render.githubusercontent.com/render/math?math=\displaystyle V = \frac{\, \chi^%2B(H \cdot L)}{\left| N \cdot L\right| %2B \sqrt{\alpha^2 %2B (1 - \alpha^2) (N \cdot L)^2}} \frac{\, \chi^%2B(H \cdot V)}{\left| N \cdot V \right| %2B \sqrt{\alpha^2 %2B (1 - \alpha^2) (N \cdot V)^2}}[format=svg] Thus we have the function @@ -2198,6 +2294,15 @@ function specular_brdf(α) { The diffuse reflection `diffuse_brdf(color)` is a Lambertian BRDF +*Latexmath* + +[latexmath] +++++ +\text{LambertianBRDF} = \frac{1}{\pi} +++++ + +*Old* + image:https://render.githubusercontent.com/render/math?math=\displaystyle \text{LambertianBRDF} = \frac{1}{\pi}[format=svg] multiplied with the `color`. @@ -2215,6 +2320,15 @@ function diffuse_brdf(color) { An inexpensive approximation for the Fresnel term that can be used for conductors and dielectrics was developed by <>: +*Latexmath* + +[latexmath] +++++ +F = f_0 + (1 - f_0) (1 - \left| V \cdot H \right| )^5 +++++ + +*Old* + image:https://render.githubusercontent.com/render/math?math=\displaystyle F = f_0 %2B (1 - f_0) (1 - \left| V \cdot H \right| )^5[format=svg] The conductor Fresnel `conductor_fresnel(f0, bsdf)` applies a view-dependent tint to a BSDF: From 370260584a0f10856359a5497079fa567d8f019a Mon Sep 17 00:00:00 2001 From: Jon Leech Date: Tue, 1 Dec 2020 20:53:16 -0800 Subject: [PATCH 2/2] Remove old math formatting leaving just latexmath --- specification/2.0/Specification.adoc | 66 ---------------------------- 1 file changed, 66 deletions(-) diff --git a/specification/2.0/Specification.adoc b/specification/2.0/Specification.adoc index d73befb430..b27345fc96 100644 --- a/specification/2.0/Specification.adoc +++ b/specification/2.0/Specification.adoc @@ -1584,8 +1584,6 @@ Runtimes are expected to use the following projection matrices. [[infinite-perspective-projection]] ==== Infinite perspective projection -*Latexmath* - [latexmath] ++++ \begin{bmatrix} @@ -1596,10 +1594,6 @@ Runtimes are expected to use the following projection matrices. \end{bmatrix} ++++ -*Old* - -image:figures/infinite-perspective.png[pdfwidth=4in,align=left] - where - `a` equals `camera.perspective.aspectRatio`; @@ -1610,8 +1604,6 @@ where [[finite-perspective-projection]] ==== Finite perspective projection -*Latexmath* - [latexmath] ++++ \begin{bmatrix} @@ -1622,10 +1614,6 @@ where \end{bmatrix} ++++ -*Old* - -image:figures/finite-perspective.png[pdfwidth=4in,align=left] - where - `a` equals `camera.perspective.aspectRatio`; @@ -1637,8 +1625,6 @@ where [[orthographic-projection]] ==== Orthographic projection -*Latexmath* - [latexmath] ++++ \begin{bmatrix} @@ -1649,10 +1635,6 @@ where \end{bmatrix} ++++ -*Old* - -image:figures/ortho.png[pdfwidth=4in,align=left] - where - `r` equals `camera.orthographic.xmag`; @@ -2201,84 +2183,48 @@ We use the following notation: The specular reflection `specular_brdf(α)` is a microfacet BRDF -*Latexmath* - [latexmath] ++++ \text{MicrofacetBRDF} = \frac{G D}{4 \, \left|N \cdot L \right| \, \left| N \cdot V \right|} ++++ -*Old* - -image:https://render.githubusercontent.com/render/math?math=\displaystyle \text{MicrofacetBRDF} = \frac{G D}{4 \, \left|N \cdot L \right| \, \left| N \cdot V \right|}[format=svg] - with the Trowbridge-Reitz/GGX microfacet distribution -*Latexmath* - [latexmath] ++++ D = \frac{\alpha^2 \, \chi^{+}(N \cdot H)}{\pi ((N \cdot H)^2 (\alpha^2 - 1) + 1)^2} ++++ -*Old* - -image:https://render.githubusercontent.com/render/math?math=\displaystyle D = \frac{\alpha^2 \, \chi^%2B(N \cdot H)}{\pi ((N \cdot H)^2 (\alpha^2 - 1) %2B 1)^2}[format=svg] - and the separable form of the Smith joint masking-shadowing function -*Latexmath* - [latexmath] ++++ G = \frac{2 \, \left| N \cdot L \right| \, \chi^{+}(H \cdot L)}{\left| N \cdot L \right| + \sqrt{\alpha^2 + (1 - \alpha^2) (N \cdot L)^2}} \frac{2 \, \left| N \cdot V \right| \, \chi^{+}(H \cdot V)}{\left| N \cdot V \right| + \sqrt{\alpha^2 + (1 - \alpha^2) (N \cdot V)^2}} ++++ -*Old* - -image:https://render.githubusercontent.com/render/math?math=\displaystyle G = \frac{2 \, \left| N \cdot L \right| \, \chi^%2B(H \cdot L)}{\left| N \cdot L \right| %2B \sqrt{\alpha^2 %2B (1 - \alpha^2) (N \cdot L)^2}} \frac{2 \, \left| N \cdot V \right| \, \chi^%2B(H \cdot V)}{\left| N \cdot V \right| %2B \sqrt{\alpha^2 %2B (1 - \alpha^2) (N \cdot V)^2}}[format=svg] - where χ^+^(*x*) denotes the Heaviside function: 1 if *x* > 0 and 0 if *x* <= 0. See <> for a derivation of the formulas. Introducing the visibility function -*Latexmath* - [latexmath] ++++ V = \frac{G}{4 \, \left| N \cdot L \right| \, \left| N \cdot V \right|} ++++ -*Old* - -image:https://render.githubusercontent.com/render/math?math=\displaystyle V = \frac{G}{4 \, \left| N \cdot L \right| \, \left| N \cdot V \right|}[format=svg] - simplifies the original microfacet BRDF to -*Latexmath* - [latexmath] ++++ \text{MicrofacetBRDF} = V D ++++ -*Old* - -image:https://render.githubusercontent.com/render/math?math=\displaystyle \text{MicrofacetBRDF} = V D[format=svg] - with -*Latexmath* - [latexmath] ++++ V = \frac{\, \chi^{+}(H \cdot L)}{\left| N \cdot L\right| + \sqrt{\alpha^2 + (1 - \alpha^2) (N \cdot L)^2}} \frac{\, \chi^{+}(H \cdot V)}{\left| N \cdot V \right| + \sqrt{\alpha^2 + (1 - \alpha^2) (N \cdot V)^2}} ++++ -*Old* - -image:https://render.githubusercontent.com/render/math?math=\displaystyle V = \frac{\, \chi^%2B(H \cdot L)}{\left| N \cdot L\right| %2B \sqrt{\alpha^2 %2B (1 - \alpha^2) (N \cdot L)^2}} \frac{\, \chi^%2B(H \cdot V)}{\left| N \cdot V \right| %2B \sqrt{\alpha^2 %2B (1 - \alpha^2) (N \cdot V)^2}}[format=svg] - Thus we have the function [source,c] @@ -2294,17 +2240,11 @@ function specular_brdf(α) { The diffuse reflection `diffuse_brdf(color)` is a Lambertian BRDF -*Latexmath* - [latexmath] ++++ \text{LambertianBRDF} = \frac{1}{\pi} ++++ -*Old* - -image:https://render.githubusercontent.com/render/math?math=\displaystyle \text{LambertianBRDF} = \frac{1}{\pi}[format=svg] - multiplied with the `color`. [source,c] @@ -2320,17 +2260,11 @@ function diffuse_brdf(color) { An inexpensive approximation for the Fresnel term that can be used for conductors and dielectrics was developed by <>: -*Latexmath* - [latexmath] ++++ F = f_0 + (1 - f_0) (1 - \left| V \cdot H \right| )^5 ++++ -*Old* - -image:https://render.githubusercontent.com/render/math?math=\displaystyle F = f_0 %2B (1 - f_0) (1 - \left| V \cdot H \right| )^5[format=svg] - The conductor Fresnel `conductor_fresnel(f0, bsdf)` applies a view-dependent tint to a BSDF: [source,c]