Merge pull request #1086 from barfowl/doc_examples_and_links

Minor fixes and improvements to the documentation pages
This commit is contained in:
George ElKoura 2019-04-01 18:14:14 -07:00 committed by GitHub
commit 40855edf12
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
25 changed files with 123 additions and 354 deletions

View File

@ -100,9 +100,7 @@ if (DOCUTILS_FOUND AND PYTHONINTERP_FOUND)
sdc_overview.rst
subdivision_surfaces.rst
tutorials.rst
using_osd.rst
using_osd_hbr.rst
using_osd_textures.rst
vtr_overview.rst
)

View File

@ -38,12 +38,12 @@ of the software.
:widths: 50 50
* - | `glViewer <glviewer.html>`_
| `glPtexViewer <glptexviewer.html>`_
| `glEvalLimit <glevallimit.html>`_
- | `glStencilViewer <glstencilviewer.html>`_
| `glPaintTest <glpainttest.html>`_
| `glPtexViewer <glptexviewer.html>`_
- | `glFVarViewer <glfvarviewer.html>`_
| `glStencilViewer <glstencilviewer.html>`_
| `glShareTopology <glsharetopology.html>`_
| `glFVarViewer <glfvarviewer.html>`_
.. list-table:: **DirectX examples**
:class: quickref
@ -54,10 +54,34 @@ of the software.
----
Common Command Line Options
===========================
While the following command line options are common, not all examples support
all -- in some cases, certain options are not applicable.
::
-f : launches the application in full-screen mode (if supported)
-u : apply uniform subdivision to all meshes
-a : apply adaptive subdivision to create patches for the limit surface
-l depth : level of uniform or adaptive refinement to apply
-c count : number of repetitions of the animation loop when supported (default
of 0 is infinite)
-anim : interpret a given set of Obj files as an animated sequence rather
than a set of distinct meshes
-catmark : apply the Catmark scheme to all meshes in given Obj files (default)
-loop : apply the Loop scheme to all meshes in given Obj files
-bilinear : apply the Bilinear scheme to all meshes in given Obj files
objfile(s) : a set of one or more meshes in Obj format (requiring a .obj extension)
that may be distinct meshes or animated versions of a single mesh
----
Common Keyboard Controls
========================
.. code:: c++
::
Left mouse button drag : orbit camera
Middle mouse button drag : pan camera

View File

@ -83,7 +83,7 @@ simply be changed -- and so an additional mode was added to avoid such behavior.
All choices are now provided through a single "linear interpolation" enum,
described and illustrated in more detail in the overview of
`Face-Varying Interpolation <subdivision_surfaces.html#face-varying-interpolation-rules>`__.
`Face-Varying Interpolation <subdivision_surfaces.html#face-varying-interpolation>`__.
The use of "boundary" in the name of the enum was intentionally removed
as the choice also affects interior interpolation. The new use of "linear"
is now intended to reflect the fact that interpolation is constrained to be

View File

@ -35,18 +35,14 @@ SYNOPSIS
.. parsed-literal::
:class: codefhead
**dxPtexViewer**
[**-e** *environment map*]
[**-d** *HDR diffuse map*]
[**-s** *HDR specular map*]
[**-y**]
[**--disp** *displacement scale*]
[**-l** *isolation level*]
*ptex color file*
*ptex displacement file*
*ptex occlusion file*
*ptex specular file*
*objfile(s)*
**dxPtexViewer** [**-f**] [**-l** *isolation level*] [**-c** *animation loops*] [**-y**]
[**-e** *environment map*] [**-d** *HDR diffuse map*] [**-s** *HDR specular map*]
[**--disp** *displacement scale*]
*ptex color file*
*ptex displacement file*
*ptex occlusion file*
*ptex specular file*
*objfile(s)*
DESCRIPTION
===========
@ -61,6 +57,13 @@ are available to experiment with the algorithms.
OPTIONS
=======
See the description of the
`common comand line options <code_examples.html#common-command-line-options>`__
for the subset of common options supported here.
**-y**
Swap Z-up geometry to Y-UP.
**-e** *environment map*
A low dynamic range spherical environment map used as a background. Ideally,
a color-normalized version of the HDR light probe.
@ -75,13 +78,6 @@ OPTIONS
**--disp** *displacement scale*
A scalar multiplier for the shader displacement values.
**-y**
Swap Z-up geometry to Y-UP.
**-l** *isolation level*
Select the desired isolation level of adaptive feature isolation. This can be
useful when trying to load large pieces of geometry.
*ptex color file*
A ptex file containing RGB channels read as material albedo color.

View File

@ -35,7 +35,8 @@ SYNOPSIS
.. parsed-literal::
:class: codefhead
**dxViewer** [**-d** *isolation level*] [**-c** *animation loops*] *objfile(s)*
**dxViewer** [**-u**] [**-a**] [**-l** *refinement level*] [**-c** *animation loops*]
*objfile(s)* [**-anim**] [**-catmark**] [**-loop**] [**-bilinear**]
DESCRIPTION
===========
@ -58,13 +59,8 @@ shapes. Multiple controls are available to experiment with the algorithms.
OPTIONS
=======
**-d** *isolation level*
Select the desired isolation level of adaptive feature isolation. This can be
useful when trying to load large pieces of geometry.
**-c** *animation frequency*
Number of repetitions of the animation loop (default=0 is infinite)
See the description of the
`common comand line options <code_examples.html#common-command-line-options>`__
for the subset of common options supported here.
.. include:: examples_see_also.rst

View File

@ -3,11 +3,12 @@ SEE ALSO
Other `examples <code_examples.html>`__ \ :
`glViewer <glviewer.html>`__, \
`glShareTopology <glsharetopology.html>`__, \
`glFVarViewer <glfvarviewer.html>`__, \
`glEvalLimit <glevallimit.html>`__, \
`glStencilViewer <glstencilviewer.html>`__, \
`glPtexViewer <glptexviewer.html>`__, \
`glEvalLimit <glevallimit.html>`__, \
`glFVarViewer <glfvarviewer.html>`__, \
`glPaintTest <glpainttest.html>`__, \
`glShareTopology <glsharetopology.html>`__, \
`dxViewer <dxviewer.html>`__, \
`dxPtexViewer <dxptexviewer.html>`__, \

View File

@ -50,7 +50,8 @@ vertices, edges, and faces. This process is purely topological and does
not depend on the speciific values of any primvar data (point positions, etc).
Topology refinement can be either uniform or adaptive, where extraordinary
features are automatically isolated (see `feature adaptive subdivision <subdivision_surfaces.html#feature-adaptive-subdivision>`__).
features are automatically isolated (see
`feature adaptive subdivision <subdivision_surfaces.html#feature-adaptive>`__).
The *Far* topology classes present a public interface for the refinement
functionality provided in `Vtr <vtr_overview.html#Vtr>`__,
@ -541,9 +542,9 @@ reduced only to contributions from vertices from the previous level of
refinement.
The latter mode allows client-code to access and insert modifications to the
vertex data at set refinement levels (see `hierarchical vertex edits
<subdivision_surfaces.html#hierarchical-edits>`_). Once the edits have been
applied by the client-code, another set of stencils can be used to smoothe the
vertex data at set refinement levels -- creating what are often referred
to as *hierarchical edits*. Once the edits have been
applied by the client-code, another set of stencils can be used to smooth the
vertex data to a higher level of refinement.
.. image:: images/far_stencil8.png
@ -580,7 +581,7 @@ Also: just as discrete stencils, limit stencils that are factorized from coarse
control vertices do not have inter-dependencies and can be evaluated in
parallel.
For implementation details, see the `glStencilViewer <glStencilViewer.html>`_
For implementation details, see the `glStencilViewer <glstencilviewer.html>`_
code example.
Sample Location On Extraordinary Faces

View File

@ -1,89 +0,0 @@
..
Copyright 2013 Pixar
Licensed under the Apache License, Version 2.0 (the "Apache License")
with the following modification; you may not use this file except in
compliance with the Apache License and the following modification to it:
Section 6. Trademarks. is deleted and replaced with:
6. Trademarks. This License does not grant permission to use the trade
names, trademarks, service marks, or product names of the Licensor
and its affiliates, except as required to comply with Section 4(c) of
the License and to reproduce the content of the NOTICE file.
You may obtain a copy of the Apache License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the Apache License with the above modification is
distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied. See the Apache License for the specific
language governing permissions and limitations under the Apache License.
glBatchViewer
-------------
.. contents::
:local:
:backlinks: none
SYNOPSIS
========
.. parsed-literal::
:class: codefhead
**glBatchViewer** [**-d** *isolation level*] [**-c** *animation loops*] [**-f**] *objfile(s)*
DESCRIPTION
===========
``glBatchViewer`` is a stand-alone application that showcases the primitive
batching capabilities of the OpenSubdiv API. Batching is an optimization that
enables the merging together of the data tables of many primitives in order to
reduce the number of GPU calls.
Multiple controls are available to experiment with the algorithms.
.. image:: images/glbatchviewer.jpg
:width: 400px
:align: center
:target: images/glbatchviewer.jpg
OPTIONS
=======
**-d** *isolation level*
Select the desired isolation level of adaptive feature isolation. This can be
useful when trying to load large pieces of geometry.
**-c** *animation frequency*
Number of repetitions of the animation loop (default=0 is infinite)
**-f**
Launches the application in full-screen mode (if is supported by GLFW on the
OS)
Keyboard Controls
=================
.. code:: c++
. , : increase / decrease the number of animated primitives
i, o : add / remove primitives
SEE ALSO
========
`Code Examples <code_examples.html>`__, \
`glViewer <glviewer.html>`__, \
`glStencilViewer <glstencilviewer.html>`__, \
`ptexViewer <ptexviewer.html>`__, \
`paintTest <painttest.html>`__, \
`limitEval <limiteval.html>`__, \
`dxViewer <dxviewer.html>`__, \
`uvViewer <uvviewer.html>`__, \

View File

@ -35,7 +35,8 @@ SYNOPSIS
.. parsed-literal::
:class: codefhead
**limitEval** [**-f**] *objfile(s)*
**glEvalLimit** [**-f**] [**-u**] [**-a**] [**-l** *refinement level*]
*objfile(s)* [**-catmark**] [**-loop**] [**-bilinear**]
DESCRIPTION
===========
@ -75,8 +76,8 @@ Multiple controls are available to experiment with the algorithms.
OPTIONS
=======
**-f**
Launches the application in full-screen mode (if is supported by GLFW on the
OS)
See the description of the
`common comand line options <code_examples.html#common-command-line-options>`__
for the subset of common options supported here.
.. include:: examples_see_also.rst

View File

@ -32,7 +32,12 @@ glFVarViewer
SYNOPSIS
========
**glFVarViewer** [**-d** *isolation level*] [**-c** *animation loops*] [**-f**] *objfile(s)*
.. parsed-literal::
:class: codefhead
**glFVarViewer** [**-f**] [**-u**] [**-a**] [**-l** *refinement level*] [**-c** *animation loops*]
*objfile(s)* [**-catmark**] [**-loop**] [**-bilinear**]
DESCRIPTION
===========
@ -54,16 +59,8 @@ interpolation rules and tags.
OPTIONS
=======
**-d** *isolation level*
Select the desired isolation level of adaptive feature isolation. This can be
useful when trying to load large pieces of geometry.
**-c** *animation frequency*
Number of repetitions of the animation loop (default=0 is infinite)
**-f**
Launches the application in full-screen mode (if is supported by GLFW on the
OS)
See the description of the
`common comand line options <code_examples.html#common-command-line-options>`__
for the subset of common options supported here.
.. include:: examples_see_also.rst

View File

@ -35,9 +35,9 @@ SYNOPSIS
.. parsed-literal::
:class: codefhead
**glPaintTest**
[**-f**]
*objfile(s)*
**glPaintTest** [**-f**] [**-l** *adaptive refinement level*]
*objfile(s)* [**-catmark**] [**-loop**]
DESCRIPTION
===========
@ -53,16 +53,11 @@ using GPU limit tessellation for painting and sculpting applications.
OPTIONS
=======
**-f**
Launches the application in full-screen mode (if is supported by GLFW on the
OS)
See the description of the
`common comand line options <code_examples.html#common-command-line-options>`__
for the subset of common options supported here.
*objfile(s)*
A sequence of obj files used as an animation loop (the topology has to match
the data contained in all the ptex files !)
Keyboard Controls
KEYBOARD CONTROLS
=================
.. code:: c++

View File

@ -35,21 +35,14 @@ SYNOPSIS
.. parsed-literal::
:class: codefhead
**glPtexViewer**
[**-e** *environment map*]
[**-d** *HDR diffuse map*]
[**-s** *HDR specular map*]
[**-y**]
[**--disp** *displacement scale*]
[**--bump** *bump scale*]
[**-l** *isolation level*]
[**-c** *animation loops*]
[**-f**]
*ptex color file*
*ptex displacement file*
*ptex occlusion file*
*ptex specular file*
*objfile(s)*
**glPtexViewer** [**-f**] [**-u**] [**-a**] [**-l** *isolation level*] [**-c** *animation loops*] [**-y**]
[**-e** *environment map*] [**-d** *HDR diffuse map*] [**-s** *HDR specular map*]
[**--disp** *displacement scale*] [**--bump** *bump scale*]
*ptex color file*
*ptex displacement file*
*ptex occlusion file*
*ptex specular file*
*objfile(s)*
DESCRIPTION
===========
@ -66,6 +59,13 @@ are available to experiment with the algorithms.
OPTIONS
=======
See the description of the
`common comand line options <code_examples.html#common-command-line-options>`__
for the subset of common options supported here.
**-y**
Swap Z-up geometry to Y-UP.
**-e** *environment map*
A low dynamic range spherical environment map used as a background. Ideally,
a color-normalized version of the HDR light probe.
@ -83,20 +83,6 @@ OPTIONS
**--bump** *displacement scale*
A scalar multiplier for the shader bump values.
**-y**
Swap Z-up geometry to Y-UP.
**-l** *isolation level*
Select the desired isolation level of adaptive feature isolation. This can be
useful when trying to load large pieces of geometry.
**-c** *animation frequency*
Number of repetitions of the animation loop (default=0 is infinite)
**-f**
Launches the application in full-screen mode (if is supported by GLFW on the
OS)
*ptex color file*
A ptex file containing RGB channels read as material albedo color.
@ -112,12 +98,7 @@ OPTIONS
A single-channel ptex file (preferably 8 bits precision) applied to modulate
the specular reflectance of the material
*objfile(s)*
A sequence of obj files used as an animation loop (the topology has to match
the data contained in all the ptex files !)
Keyboard Controls
KEYBOARD CONTROLS
=================
.. code:: c++
@ -131,5 +112,4 @@ Keyboard Controls
e : draw normals
.. include:: examples_see_also.rst

View File

@ -35,7 +35,7 @@ SYNOPSIS
.. parsed-literal::
:class: codefhead
**glShareTopology** [**-d** *isolation level*] *objfile(s)*
**glShareTopology** [**-u**] [**-a**] [**-l** *refinement level*]
DESCRIPTION
===========
@ -51,8 +51,8 @@ instancing across Compute contexts. Multiple controls are available to experimen
OPTIONS
=======
**-d** *isolation level*
Select the desired isolation level of adaptive feature isolation. This can be
useful when trying to load large pieces of geometry.
See the description of the
`common comand line options <code_examples.html#common-command-line-options>`__
for the subset of common options supported here.
.. include:: examples_see_also.rst

View File

@ -35,7 +35,8 @@ SYNOPSIS
.. parsed-literal::
:class: codefhead
**glStencilViewer** [**-d** *isolation level*] [**-f**] *objfile(s)*
**glStencilViewer** [**-f**] [**-u**] [**-a**] [**-l** *refinement level*]
*objfile(s)* [**-catmark**] [**-loop**] [**-bilinear**]
DESCRIPTION
===========
@ -52,12 +53,8 @@ controls are available to experiment with the algorithms.
OPTIONS
=======
**-d** *isolation level*
Select the desired isolation level of adaptive feature isolation. This can be
useful when trying to load large pieces of geometry.
**-f**
Launches the application in full-screen mode (if is supported by GLFW on the
OS)
See the description of the
`common comand line options <code_examples.html#common-command-line-options>`__
for the subset of common options supported here.
.. include:: examples_see_also.rst

View File

@ -35,12 +35,8 @@ SYNOPSIS
.. parsed-literal::
:class: codefhead
**glViewer**
[**-d** *isolation level*]
[**-c** *animation loops*]
[**-f**]
[**-axis**]
*objfile(s)*
**glViewer** [**-f**] [**-u**] [**-a**] [**-l** *refinement level*] [**-axis**] [**-c** *animation loops*]
*objfile(s)* [**-anim**] [**-catmark**] [**-loop**] [**-bilinear**]
DESCRIPTION
===========
@ -57,22 +53,11 @@ shapes. Multiple controls are available to experiment with the algorithms.
OPTIONS
=======
**-d** *isolation level*
Select the desired isolation level of adaptive feature isolation. This can be
useful when trying to load large pieces of geometry.
**-c** *animation frequency*
Number of repetitions of the animation loop (default=0 is infinite)
**-f**
Launches the application in full-screen mode (if is supported by GLFW on the
OS)
See the description of the
`common comand line options <code_examples.html#common-command-line-options>`__
for the subset of common options supported here.
**-axis**
Swap Y-up / Z-up axis when loading obj files
*objfile(s)*
A sequence of obj files used as an animation loop (the topology has to match
the data contained in all the ptex files !)
Swap Y-up / Z-up axis when loading Obj files
.. include:: examples_see_also.rst

View File

@ -111,7 +111,7 @@ Boundary Interpolation Rules
+------------------------------------+
This enum is shared for both `vertex and face-varying interpolation
<subdivision_surfaces.html#boundary-interpolation-rules>`__, with the following
<subdivision_surfaces.html#boundary-interpolation>`__, with the following
distinctions:
- vertex boundaries:

Binary file not shown.

Before

Width:  |  Height:  |  Size: 298 KiB

View File

@ -48,10 +48,10 @@ Topology
Well-constructed subdivision meshes have several important properties:
* They consist primarily of quad faces
* They consist primarily of regular faces (quads for Catmull-Clark, tris for Loop)
* They contain few extraordinary vertices
* They efficiently describe the intended shape
* They are topologically `manifold <subdivision_surfaces.html#manifold-geometry>`__
* They are topologically `manifold <subdivision_surfaces.html#non-manifold-topology>`__
----

View File

@ -65,8 +65,8 @@ identical results across different computational devices.
Refinement
==========
**Osd** supports both `uniform subdivision <subdivision_surfaces.html#uniform-subdivision>`__
and `adaptive subdivision <subdivision_surfaces.html#feature-adaptive-subdivision>`__.
**Osd** supports both uniform and
`feature adaptive <subdivision_surfaces.html#feature-adaptive>`__ subdivision.
.. image:: images/osd_refinement.png

View File

@ -130,7 +130,7 @@ options used to control its interpolation have changed. The documentation on
`Compatibility with OpenSubdiv 2.x <compatibility.html#compatibility-with-opensubdiv-2.x>`__
details the equivalence of interpolation options between Hbr and the new
*Sdc::Options::FVarLinearInterpolation* enum, while the section on
`Face Varying Interpolation <subdivision_surfaces.html#face-varying-interpolation-rules>`__
`Face Varying Interpolation <subdivision_surfaces.html#face-varying-interpolation>`__
illustrates their effects.
Face varying data is now specified by index rather than by value, or as often

View File

@ -37,7 +37,7 @@ Bicubic Face-Varying Patches
The motivation for this feature is to improve drawing and evaluation of face-varying
primvar values for all
`face-varying interpolation options <subdivision_surfaces.html#face-varying-interpolation-rules>`__.
`face-varying interpolation options <subdivision_surfaces.html#face-varying-interpolation>`__.
A common use of non-linear face-varying data is to capture a UV projection on
the surface. The following example shows a simple shape with the face-varying

View File

@ -264,6 +264,8 @@ help deal with that complexity:
| Two valence-5 vertices nearby | Isolation subdivided once | Isolation subdivided twice |
+--------------------------------------+--------------------------------------+--------------------------------------+
.. _feature-adaptive:
It's generally necessary to perform some kind of local subdivision in these areas
to break these pieces of surface into smaller, more manageable pieces, and the
term "feature adaptive subdivision" has become popular in recent years to describe

View File

@ -1,62 +0,0 @@
..
Copyright 2013 Pixar
Licensed under the Apache License, Version 2.0 (the "Apache License")
with the following modification; you may not use this file except in
compliance with the Apache License and the following modification to it:
Section 6. Trademarks. is deleted and replaced with:
6. Trademarks. This License does not grant permission to use the trade
names, trademarks, service marks, or product names of the Licensor
and its affiliates, except as required to comply with Section 4(c) of
the License and to reproduce the content of the NOTICE file.
You may obtain a copy of the Apache License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the Apache License with the above modification is
distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied. See the Apache License for the specific
language governing permissions and limitations under the Apache License.
Using OpenSubdiv
----------------
.. contents::
:local:
:backlinks: none
.. image:: images/osd_splash.png
:align: center
:target: images/osd_splash.png
OpenSubdiv APIs
===============
.. list-table:: **APIs Overview**
:class: quickref
:widths: 50 50
* - | `Overview <api_overview.html>`_
- | `Sdc API <sdc_overview.html>`_
| `Vtr API <vtr_overview.html>`_
| `Far API <far_overview.html>`_
| `Osd API <osd_overview.html>`_
Coding With OpenSubdiv
======================
.. list-table:: **General Topics**
:class: quickref
:widths: 50 50
* - | `Compiling & Linking <using_osd_compile.html>`_
| `Tutorials <tutorials.html>`_
- | Writing Shaders
| `Textures (UV & Ptex) <using_osd_textures.html>`_

View File

@ -213,7 +213,7 @@ to know the number of vertices in the face and the indices of these vertices.
mesh->NewFace(nv, fv, 0);
}
However, currently **Hbr** is not able to handle `non-manifold <subdivision_surfaces.html#manifold-geometry>`__
However, **Hbr** is not able to handle `non-manifold <subdivision_surfaces.html#non-manifold-topology>`__
geometry. In order to avoid tripping asserts or causing memory violations, let's
rewrite the previous loop with some some prototype code to check the validity of
the topology.
@ -312,7 +312,7 @@ The rule-set can be selected using the following accessors:
Additional information on boundary interpolation rules can be found
`here <subdivision_surfaces.html#boundary-interpolation-rules>`__ and
`here <subdivision_surfaces.html#boundary-interpolation>`__ and
`here <hbr_overview.html#boundary-interpolation-rules>`__
.. container:: impnotip
@ -442,8 +442,7 @@ Modifications are one of the following 3 operations:
| Subtract |
+-----------+
Here is a simple example that creates a hierarchical vertex edit that corresponds
to `this example <subdivision_surfaces.html#hierarchical-edits-paths>`__.
Here is a simple example that creates a hierarchical vertex edit.
.. code:: c++

View File

@ -1,52 +0,0 @@
..
Copyright 2013 Pixar
Licensed under the Apache License, Version 2.0 (the "Apache License")
with the following modification; you may not use this file except in
compliance with the Apache License and the following modification to it:
Section 6. Trademarks. is deleted and replaced with:
6. Trademarks. This License does not grant permission to use the trade
names, trademarks, service marks, or product names of the Licensor
and its affiliates, except as required to comply with Section 4(c) of
the License and to reproduce the content of the NOTICE file.
You may obtain a copy of the Apache License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the Apache License with the above modification is
distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied. See the Apache License for the specific
language governing permissions and limitations under the Apache License.
Using Textures
--------------
.. contents::
:local:
:backlinks: none
Ptex Face Indices
=================
.. image:: images/ptex_coarse.png
:align: center
:target: images/ptex_coarse.png
Non-quad topology
_________________
.. image:: images/ptex_quadrangulated.png
:align: center
:target: images/ptex_quadrangulated.png
Filtering
_________
.. include:: under_development.rst