diff --git a/CMakeLists.txt b/CMakeLists.txt index 5c552dc1..6fbbac81 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -256,7 +256,7 @@ find_package(PTex 2.0) find_package(PythonInterp 2.6) find_package(SWIG 1.3.40) find_package(Doxygen) - +find_package(Docutils 0.6) if (NOT APPLE AND OPENGL_FOUND) find_package(GLEW REQUIRED) endif() diff --git a/cmake/FindDocutils.cmake b/cmake/FindDocutils.cmake new file mode 100644 index 00000000..211d591e --- /dev/null +++ b/cmake/FindDocutils.cmake @@ -0,0 +1,112 @@ +# +# Copyright (C) Pixar. All rights reserved. +# +# This license governs use of the accompanying software. If you +# use the software, you accept this license. If you do not accept +# the license, do not use the software. +# +# 1. Definitions +# The terms "reproduce," "reproduction," "derivative works," and +# "distribution" have the same meaning here as under U.S. +# copyright law. A "contribution" is the original software, or +# any additions or changes to the software. +# A "contributor" is any person or entity that distributes its +# contribution under this license. +# "Licensed patents" are a contributor's patent claims that read +# directly on its contribution. +# +# 2. Grant of Rights +# (A) Copyright Grant- Subject to the terms of this license, +# including the license conditions and limitations in section 3, +# each contributor grants you a non-exclusive, worldwide, +# royalty-free copyright license to reproduce its contribution, +# prepare derivative works of its contribution, and distribute +# its contribution or any derivative works that you create. +# (B) Patent Grant- Subject to the terms of this license, +# including the license conditions and limitations in section 3, +# each contributor grants you a non-exclusive, worldwide, +# royalty-free license under its licensed patents to make, have +# made, use, sell, offer for sale, import, and/or otherwise +# dispose of its contribution in the software or derivative works +# of the contribution in the software. +# +# 3. Conditions and Limitations +# (A) No Trademark License- This license does not grant you +# rights to use any contributor's name, logo, or trademarks. +# (B) If you bring a patent claim against any contributor over +# patents that you claim are infringed by the software, your +# patent license from such contributor to the software ends +# automatically. +# (C) If you distribute any portion of the software, you must +# retain all copyright, patent, trademark, and attribution +# notices that are present in the software. +# (D) If you distribute any portion of the software in source +# code form, you may do so only under this license by including a +# complete copy of this license with your distribution. If you +# distribute any portion of the software in compiled or object +# code form, you may only do so under a license that complies +# with this license. +# (E) The software is licensed "as-is." You bear the risk of +# using it. The contributors give no express warranties, +# guarantees or conditions. You may have additional consumer +# rights under your local laws which this license cannot change. +# To the extent permitted under your local laws, the contributors +# exclude the implied warranties of merchantability, fitness for +# a particular purpose and non-infringement. +# + +# - Try to find the restructured text to HTML converter +# +# Once done this will define +# +# DOCUTILS_FOUND - System has Docutils +# +# RST2HTML_EXECUTALE + +find_package(PackageHandleStandardArgs) + +find_program( RST2HTML_EXECUTABLE + NAMES + rst2html.py + rst2html + DOC + "The Python Docutils reStructuredText HTML converter" +) + +if (RST2HTML_EXECUTABLE) + + set(DOCUTILS_FOUND "YES") + + # find the version + execute_process( COMMAND ${RST2HTML_EXECUTABLE} --version OUTPUT_VARIABLE VERSION_STRING ) + + # ex : rst2html (Docutils 0.6 [release], Python 2.6.6, on linux2) + string(REGEX MATCHALL "([^\ ]+\ |[^\ ]+$)" VERSION_TOKENS "${VERSION_STRING}") + + # isolate the 3rd. word in the string + list (GET VERSION_TOKENS 2 VERSION_STRING) + + # remove white space + string(REGEX REPLACE "[ \t]+$" "" VERSION_STRING ${VERSION_STRING}) + string(REGEX REPLACE "^[ \t]+" "" VERSION_STRING ${VERSION_STRING}) + + set(DOCUTILS_VERSION ${VERSION_STRING}) + +else() + + set(DOCUTILS_FOUND "NO") + +endif() + +include(FindPackageHandleStandardArgs) + +find_package_handle_standard_args(Docutils + REQUIRED_VARS + RST2HTML_EXECUTABLE + VERSION_VAR + DOCUTILS_VERSION +) + +mark_as_advanced( + RST2HTML_EXECUTABLE +) diff --git a/documentation/CMakeLists.txt b/documentation/CMakeLists.txt index a8d36607..10198e2d 100644 --- a/documentation/CMakeLists.txt +++ b/documentation/CMakeLists.txt @@ -55,20 +55,156 @@ # a particular purpose and non-infringement. # -if (DOXYGEN_FOUND) +if (NOT NO_DOC) - configure_file(${CMAKE_CURRENT_SOURCE_DIR}/OpenSubdiv.doxy ${CMAKE_CURRENT_BINARY_DIR}/OpenSubdiv.doxy @ONLY) + if (DOXYGEN_FOUND) + + configure_file(${CMAKE_CURRENT_SOURCE_DIR}/OpenSubdiv.doxy ${CMAKE_CURRENT_BINARY_DIR}/OpenSubdiv.doxy @ONLY) + + add_custom_target(doc_doxy + ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/OpenSubdiv.doxy + WORKING_DIRECTORY + ${CMAKE_INSTALL_PREFIX}/include + COMMENT + "Generating API documentation with Doxygen" VERBATIM + ) + + #list(APPEND DOC_TARGETS doc_doxy) + else() + + message(WARNING + "Doxyen was not found : support for Doxygen automated API documentation is disabled.") + + endif() + + + + if (DOCUTILS_FOUND) + + set(HTML_FILES + search.html + ) + + set(RST_FILES + api_overview.rst + intro.rst + cmake_build.rst + code_examples.rst + getting_started.rst + glviewer.rst + release_notes.rst + subdivision_surfaces.rst + using_opensubdiv.rst + ) + + # process rst markup files + foreach(src ${RST_FILES}) + get_filename_component(BASENAME ${src} NAME_WE) + + set(infile ${CMAKE_CURRENT_SOURCE_DIR}/${src}) + set(outfile ${CMAKE_CURRENT_BINARY_DIR}/${BASENAME}.html) + + add_custom_command( + OUTPUT + ${outfile} + COMMAND + ${RST2HTML_EXECUTABLE} + ARGS + --date + --time + --no-xml-declaration + --initial-header-level=3 + --strip-comments + --stylesheet=css/rst.css + --link-stylesheet + ${infile} ${outfile} + DEPENDS + ${infile} + ) + + add_custom_target(${src} ALL DEPENDS ${outfile}) + + list(APPEND RST_TARGETS ${src}) + + install( + FILES + ${outfile} + DESTINATION + ${CMAKE_INSTALL_PREFIX}/documentation + PERMISSIONS + OWNER_READ GROUP_READ WORLD_READ + ) + + endforeach() + + # copy html files to the build area + foreach(src ${HTML_FILES}) + set(infile ${CMAKE_CURRENT_SOURCE_DIR}/${src}) + set(outfile ${CMAKE_CURRENT_BINARY_DIR}/${src}) + + add_custom_command( + OUTPUT + ${outfile} + COMMAND + ${CMAKE_COMMAND} + ARGS + -E copy ${infile} ${outfile} + ) + + add_custom_target( ${src} ALL DEPENDS ${outfile}) + + list(APPEND HTML_TARGETS ${src}) + + install( + FILES + ${outfile} + DESTINATION + ${CMAKE_INSTALL_PREFIX}/documentation + ) + endforeach() + + # build search index and insert navigation tab + if (PYTHONINTERP_FOUND) + + add_custom_target(search_index ALL + COMMAND + ${PYTHON_EXECUTABLE} + ${CMAKE_CURRENT_SOURCE_DIR}/processHtml.py + ${CMAKE_CURRENT_BINARY_DIR} + ${CMAKE_INSTALL_PREFIX}/documentation + ${CMAKE_CURRENT_SOURCE_DIR}/nav_template.txt + DEPENDS + ${HTML_TARGETS} ${RST_TARGETS} + ) + + install( + DIRECTORY + tipuesearch + DESTINATION + ${CMAKE_INSTALL_PREFIX}/documentation + ) + endif() + + + add_custom_target(doc_html DEPENDS ${HTML_TARGETS} ${RST_TARGETS} ) + + install( + DIRECTORY + images + DESTINATION + ${CMAKE_INSTALL_PREFIX}/documentation + ) + + install( + DIRECTORY + css + DESTINATION + ${CMAKE_INSTALL_PREFIX}/documentation + ) + + list(APPEND DOC_TARGETS doc_html) + endif() + + add_custom_target(doc DEPENDS ${DOC_TARGETS}) - add_custom_target(doc - ${DOXYGEN_EXECUTABLE} - ${CMAKE_CURRENT_BINARY_DIR}/OpenSubdiv.doxy - WORKING_DIRECTORY - ${CMAKE_INSTALL_PREFIX}/include - COMMENT "Generating API documentation with Doxygen" VERBATIM - ) -else() - - message(WARNING - "Doxyen was not found : support for Doxygen automated API documentation is disabled.") - endif() diff --git a/documentation/api_overview.rst b/documentation/api_overview.rst new file mode 100644 index 00000000..4ac7a829 --- /dev/null +++ b/documentation/api_overview.rst @@ -0,0 +1,174 @@ +.. + Copyright (C) Pixar. All rights reserved. + + This license governs use of the accompanying software. If you + use the software, you accept this license. If you do not accept + the license, do not use the software. + + 1. Definitions + The terms "reproduce," "reproduction," "derivative works," and + "distribution" have the same meaning here as under U.S. + copyright law. A "contribution" is the original software, or + any additions or changes to the software. + A "contributor" is any person or entity that distributes its + contribution under this license. + "Licensed patents" are a contributor's patent claims that read + directly on its contribution. + + 2. Grant of Rights + (A) Copyright Grant- Subject to the terms of this license, + including the license conditions and limitations in section 3, + each contributor grants you a non-exclusive, worldwide, + royalty-free copyright license to reproduce its contribution, + prepare derivative works of its contribution, and distribute + its contribution or any derivative works that you create. + (B) Patent Grant- Subject to the terms of this license, + including the license conditions and limitations in section 3, + each contributor grants you a non-exclusive, worldwide, + royalty-free license under its licensed patents to make, have + made, use, sell, offer for sale, import, and/or otherwise + dispose of its contribution in the software or derivative works + of the contribution in the software. + + 3. Conditions and Limitations + (A) No Trademark License- This license does not grant you + rights to use any contributor's name, logo, or trademarks. + (B) If you bring a patent claim against any contributor over + patents that you claim are infringed by the software, your + patent license from such contributor to the software ends + automatically. + (C) If you distribute any portion of the software, you must + retain all copyright, patent, trademark, and attribution + notices that are present in the software. + (D) If you distribute any portion of the software in source + code form, you may do so only under this license by including a + complete copy of this license with your distribution. If you + distribute any portion of the software in compiled or object + code form, you may only do so under a license that complies + with this license. + (E) The software is licensed "as-is." You bear the risk of + using it. The contributors give no express warranties, + guarantees or conditions. You may have additional consumer + rights under your local laws which this license cannot change. + To the extent permitted under your local laws, the contributors + exclude the implied warranties of merchantability, fitness for + a particular purpose and non-infringement. + + +API Overview +------------ + +.. contents:: + :local: + :backlinks: none + + +The OpenSubdiv API is structured in 3 global layers: Hbr, Far and Osd. + +---- + +Hierarchical Boundary Representation (Hbr) +========================================== + +Hbr is an interconnected topological data representation. The high level of vertex +connectivity information makes this representation well suited for creation and +editing purposes. It is however inefficient for interactive refinement operations: +Separate objects are allocated for each vertex and edge with pointers to neighboring +vertices and edges. + +Hbr is also the lowest-level subdivision library in Pixar's Photorealistic RenderMan. + +Half-edge Data Structure +************************ + +The current implementation is based on a half-edge data structure. + +.. image:: images/half_edge.png + :align: center + +Half-edge cycles and Manifold Topology +************************************** + +Because half-edges only carry a reference to their opposite half-edge, a given +edge can only access a single neighboring edge cycle. + +.. image:: images/half_edge_cycle.png + :align: center + +This is a fundamental limitation of the half-edge data structure, in that it +cannot represent non-manifold geometry, in particular fan-type topologies. + +Templated Vertex Class +********************** + +The vertex class has been abstracted into a set of templated function accesses. +Providing Hbr with a template vertex class that does not implement these functions +allows client-code to use Hbr as a pure topological analysis tool without having +to pay any costs for data interpolation. It also allows client-code to remain in +complete control of the layout of the vertex data : interleaved or non-interleaved. + +---- + +Feature Adaptive Representation (Far) +===================================== + +Far is a serialized topoloigcal data representation.Far uses hbr to create and +cache fast run time data structures for table driven subdivision of vertices and +cubic patches for limit surface evaluation. `Feature-adaptive `__ +refinement logic is used to adaptively refine coarse topology near features like +extraordinary vertices and creases in order to make the topology amenable to +cubic patch evaluation. Far is also a generic, templated algorithmic base API +that clients in higher levels instantiate and use by providing an implementation +of a vertex class. It supports these subdivision schemes: + +---- + +OpenSubdiv (Osd) +================ + +Osd contains client-level code that uses Far to create concrete instances of +meshes. These meshes use precomputed tables from hbr to perform table-driven +subdivision steps with a variety of massively parallel computational backend +technologies. Osd supports both `uniform subdivision ` +and adaptive refinement with cubic patches. With uniform subdivision the +computational backend code performs Catmull/Clark splitting and averaging on +each face. With adaptive subdivision the Catmull/Clark steps are used to compute +the CVs of cubic patches, then the cubic patches are tessellated on with GLSL or DirectX. + +OpenSubdiv enforces the same results for the different computation backends with +a series of regression tests that compare the methods to each other. + +The OpenSubdiv layer is comprised of 3 modules : Refine, Draw and Eval. + +.. container:: impnotip + + * **Important** + + Face-varying smooth data interpolation is currently not supported in Osd. + "Smooth UV" modes of various DCC applications are not supported (yet). + +---- + +OsdRefine +********* + +The Refine module contains the code paths that manage the application of the +subdivision rules to the vertex data. + +---- + +OsdDraw +******* + +The Draw module manages interactions with discrete display devices and provide +support for interactive drawing of the subdivision surfaces. + +---- + +OsdEval +******* + +The Eval module provides computational APIs for the evaluation of vertex data at +the limit, ray intersection and point projection. + + diff --git a/documentation/cmake_build.rst b/documentation/cmake_build.rst new file mode 100644 index 00000000..b12cf023 --- /dev/null +++ b/documentation/cmake_build.rst @@ -0,0 +1,203 @@ +.. + Copyright (C) Pixar. All rights reserved. + + This license governs use of the accompanying software. If you + use the software, you accept this license. If you do not accept + the license, do not use the software. + + 1. Definitions + The terms "reproduce," "reproduction," "derivative works," and + "distribution" have the same meaning here as under U.S. + copyright law. A "contribution" is the original software, or + any additions or changes to the software. + A "contributor" is any person or entity that distributes its + contribution under this license. + "Licensed patents" are a contributor's patent claims that read + directly on its contribution. + + 2. Grant of Rights + (A) Copyright Grant- Subject to the terms of this license, + including the license conditions and limitations in section 3, + each contributor grants you a non-exclusive, worldwide, + royalty-free copyright license to reproduce its contribution, + prepare derivative works of its contribution, and distribute + its contribution or any derivative works that you create. + (B) Patent Grant- Subject to the terms of this license, + including the license conditions and limitations in section 3, + each contributor grants you a non-exclusive, worldwide, + royalty-free license under its licensed patents to make, have + made, use, sell, offer for sale, import, and/or otherwise + dispose of its contribution in the software or derivative works + of the contribution in the software. + + 3. Conditions and Limitations + (A) No Trademark License- This license does not grant you + rights to use any contributor's name, logo, or trademarks. + (B) If you bring a patent claim against any contributor over + patents that you claim are infringed by the software, your + patent license from such contributor to the software ends + automatically. + (C) If you distribute any portion of the software, you must + retain all copyright, patent, trademark, and attribution + notices that are present in the software. + (D) If you distribute any portion of the software in source + code form, you may do so only under this license by including a + complete copy of this license with your distribution. If you + distribute any portion of the software in compiled or object + code form, you may only do so under a license that complies + with this license. + (E) The software is licensed "as-is." You bear the risk of + using it. The contributors give no express warranties, + guarantees or conditions. You may have additional consumer + rights under your local laws which this license cannot change. + To the extent permitted under your local laws, the contributors + exclude the implied warranties of merchantability, fitness for + a particular purpose and non-infringement. + + +Building with Cmake +------------------- + +.. contents:: + :local: + :backlinks: none + + +Information on how to build OpenSubdiv + +---- + +Overview +======== + +Assuming that you have `cloned `__ the source repository +and selected an appropriate release branch, the following instructions will +walk you through the Cmake and configuration and build process. + +Cmake is a cross-platform, open-source build system. Cmake controls the compilation +process using platform independent configuration files in order to generate +makefiles and workspaces that are native to the platform of choice. + +The process involves the following steps: + 1. Locate & build the requisite dependencies + 2. Configure & run CMake to generate Makefiles / MSVC solution / XCode project + 3. Run the build from make / MSVC / XCode + +---- + +Step 1: Dependencies +==================== + +Cmake will adapt the build based on which dependencies have been successfully +discovered and will disable certain features and code examples accordingly. + +Please refer to the documentation of each of the dependency packages for specific +build and installation instructions. + +Required +________ + - `cmake `__ version 2.8 + +Optional +________ + + - `GLEW `__ (Windows/Linux only) + - `CUDA `__ + - `OpenCL `__ + - `GLFW `__ (required for standalone examples + and some regression tests) + - `Ptex `__ (support features for ptex textures and the + ptexViewer example) + - `Zlib `__ (required for Ptex under Windows) + - `DX11 SDK `__ + - `Docutils `__ + +---- + +Step 2: Configuring CMake +========================= + +One way to configure CMake is to use the `CMake GUI `__. +In many cases CMake can fall back on default standard paths in order to find the +packages that OpenSubdiv depends on. For non-standard installations however, a +complete set of override variables is available. The following sub-section lists +some of these variables. For more specific details, please consult the source of +the custom CMake modules in the OpenSubdiv/cmake/ folder. + +Useful Build Options +____________________ + +The following configuration arguments can be passed to the cmake command line. + +.. code:: c++ + + -DCMAKE_BUILD_TYPE=[Debug|Release] + + -DCMAKE_INSTALL_PREFIX=[base path to install OpenSubdiv (default: Current directory)] + -DCMAKE_LIBDIR_BASE=[library directory basename (default: lib)] + + -DCUDA_TOOLKIT_ROOT_DIR=[path to CUDA] + -DPTEX_LOCATION=[path to Ptex] + -DGLEW_LOCATION=[path to GLEW] + -DGLFW_LOCATION=[path to GLFW] + -DMAYA_LOCATION=[path to Maya] + + -DNO_OMP=1 // disable OpenMP + -DNO_GCD=1 // disable GrandCentralDispatch on OSX + -DNO_DOC=1 // disable documentation build + +Environment Variables +_____________________ + +The paths to Maya, Ptex, GLFW, and GLEW can also be specified through the +following environment variables: + +.. code:: c++ + + MAYA_LOCATION + PTEX_LOCATION + GLFW_LOCATION + GLEW_LOCATION. + +Automated Script +________________ + +The GUI solution will probably become a burden for active developpers who tend to +re-run the configuration step fairly often.Here is an example CMake configuration +script for a full typical windows-based build that can be run in GitShell : + +.. code:: c++ + + #/bin/tcsh + + # Replace the ".." with a full path to the root of the OpenSubdiv source tree if necessary + "c:/Program Files (x86)/CMake 2.8/bin/cmake.exe" \ + -G "Visual Studio 10 Win64" \ + -D "GLEW_LOCATION:string=c:/Program Files/glew-1.9.0" \ + -D "GLFW_LOCATION:string=c:/Program Files/glfw-2.7.7.bin.WIN64" \ + -D "OPENCL_INCLUDE_DIRS:string=c:/ProgramData/NVIDIA Corporation/NVIDIA GPU Computing SDK 4.2/OpenCL/common/inc" \ + -D "_OPENCL_CPP_INCLUDE_DIRS:string=c:/ProgramData/NVIDIA Corporation/NVIDIA GPU Computing SDK 4.2/OpenCL/common/inc" \ + -D "OPENCL_LIBRARIES:string=c:/ProgramData/NVIDIA Corporation/NVIDIA GPU Computing SDK 4.2/OpenCL/common/lib/x64/OpenCL.lib" \ + -D "MAYA_LOCATION:string=c:/Program Files/Autodesk/Maya2013.5" \ + -D "PTEX_LOCATION:string=c:/Users/opensubdiv/demo/src/ptex/x64" \ + .. + + # copy Ptex dependencies (Windows only) + mkdir -p bin/{Debug,Release} + \cp -f c:/Users/opensubdiv/demo/src/zlib-1.2.7/contrib/vstudio/vc10/x64/ZlibDllRelease/zlibwapi.dll bin/Debug/ + \cp -f c:/Users/opensubdiv/demo/src/zlib-1.2.7/contrib/vstudio/vc10/x64/ZlibDllRelease/zlibwapi.dll bin/Release/ + \cp -f c:/Users/opensubdiv/demo/src/ptex/x64/lib/Ptex.dll bin/Debug/ + \cp -f c:/Users/opensubdiv/demo/src/ptex/x64/lib/Ptex.dll bin/Release/ + +---- + +Step 3: Building +================ + +The steps differ for different OS'es: + + Windows : launch VC++ with the solution generated by cmake in your build directory. + + OSX : run xcodebuild in your build directory + + \*Nix : run make in your build directory diff --git a/documentation/code_examples.rst b/documentation/code_examples.rst new file mode 100644 index 00000000..8da09685 --- /dev/null +++ b/documentation/code_examples.rst @@ -0,0 +1,82 @@ +.. + Copyright (C) Pixar. All rights reserved. + + This license governs use of the accompanying software. If you + use the software, you accept this license. If you do not accept + the license, do not use the software. + + 1. Definitions + The terms "reproduce," "reproduction," "derivative works," and + "distribution" have the same meaning here as under U.S. + copyright law. A "contribution" is the original software, or + any additions or changes to the software. + A "contributor" is any person or entity that distributes its + contribution under this license. + "Licensed patents" are a contributor's patent claims that read + directly on its contribution. + + 2. Grant of Rights + (A) Copyright Grant- Subject to the terms of this license, + including the license conditions and limitations in section 3, + each contributor grants you a non-exclusive, worldwide, + royalty-free copyright license to reproduce its contribution, + prepare derivative works of its contribution, and distribute + its contribution or any derivative works that you create. + (B) Patent Grant- Subject to the terms of this license, + including the license conditions and limitations in section 3, + each contributor grants you a non-exclusive, worldwide, + royalty-free license under its licensed patents to make, have + made, use, sell, offer for sale, import, and/or otherwise + dispose of its contribution in the software or derivative works + of the contribution in the software. + + 3. Conditions and Limitations + (A) No Trademark License- This license does not grant you + rights to use any contributor's name, logo, or trademarks. + (B) If you bring a patent claim against any contributor over + patents that you claim are infringed by the software, your + patent license from such contributor to the software ends + automatically. + (C) If you distribute any portion of the software, you must + retain all copyright, patent, trademark, and attribution + notices that are present in the software. + (D) If you distribute any portion of the software in source + code form, you may do so only under this license by including a + complete copy of this license with your distribution. If you + distribute any portion of the software in compiled or object + code form, you may only do so under a license that complies + with this license. + (E) The software is licensed "as-is." You bear the risk of + using it. The contributors give no express warranties, + guarantees or conditions. You may have additional consumer + rights under your local laws which this license cannot change. + To the extent permitted under your local laws, the contributors + exclude the implied warranties of merchantability, fitness for + a particular purpose and non-infringement. + + +Code Examples +------------- + +.. list-table:: **OpenGL examples** + :class: quickref + :widths: 50 50 + + * - | `glViewer `_ + | `ptexViewer `_ + - | `paintTest `_ + | `evalLimit `_ + +.. list-table:: **DirectX examples** + :class: quickref + :widths: 50 50 + + * - | `dxViewer `_ + - | + +.. list-table:: **Plugin examples** + :class: quickref + :widths: 50 50 + + * - | `mayaViewer `_ + - | `mayaPtexViewer `_ diff --git a/documentation/css/rst.css b/documentation/css/rst.css new file mode 100644 index 00000000..2c50be19 --- /dev/null +++ b/documentation/css/rst.css @@ -0,0 +1,584 @@ + /* + Copyright (C) Pixar. All rights reserved. + + This license governs use of the accompanying software. If you + use the software, you accept this license. If you do not accept + the license, do not use the software. + + 1. Definitions + The terms "reproduce," "reproduction," "derivative works," and + "distribution" have the same meaning here as under U.S. + copyright law. A "contribution" is the original software, or + any additions or changes to the software. + A "contributor" is any person or entity that distributes its + contribution under this license. + "Licensed patents" are a contributor's patent claims that read + directly on its contribution. + + 2. Grant of Rights + (A) Copyright Grant- Subject to the terms of this license, + including the license conditions and limitations in section 3, + each contributor grants you a non-exclusive, worldwide, + royalty-free copyright license to reproduce its contribution, + prepare derivative works of its contribution, and distribute + its contribution or any derivative works that you create. + (B) Patent Grant- Subject to the terms of this license, + including the license conditions and limitations in section 3, + each contributor grants you a non-exclusive, worldwide, + royalty-free license under its licensed patents to make, have + made, use, sell, offer for sale, import, and/or otherwise + dispose of its contribution in the software or derivative works + of the contribution in the software. + + 3. Conditions and Limitations + (A) No Trademark License- This license does not grant you + rights to use any contributor's name, logo, or trademarks. + (B) If you bring a patent claim against any contributor over + patents that you claim are infringed by the software, your + patent license from such contributor to the software ends + automatically. + (C) If you distribute any portion of the software, you must + retain all copyright, patent, trademark, and attribution + notices that are present in the software. + (D) If you distribute any portion of the software in source + code form, you may do so only under this license by including a + complete copy of this license with your distribution. If you + distribute any portion of the software in compiled or object + code form, you may only do so under a license that complies + with this license. + (E) The software is licensed "as-is." You bear the risk of + using it. The contributors give no express warranties, + guarantees or conditions. You may have additional consumer + rights under your local laws which this license cannot change. + To the extent permitted under your local laws, the contributors + exclude the implied warranties of merchantability, fitness for + a particular purpose and non-infringement. +*/ + + +/*Pixar Code Styles +________________________*/ + + +pre, code { + border: 1px dashed #555555; + background:#222; + padding: 5px 10px; + line-height: 21px; + word-wrap:break-word; + text-align: left; + width: 96%; + -moz-border-radius: 5px; + -webkit-border-radius: 5px; +} +.code-keyword { + color:#036eff; +} +.code-quote { + color:#13db03; +} +.code-object { + color:#e403ff; +} + + +/************************************************** + * + * Browser style sheet - loaded by all CSS aware browsers + * + **************************************************/ + + +.subtitle { + color: #000000; + font-size: 12pt; +} + +/* neutralize the "docutils" class imposed by rst */ + +table.docutils { + border-style: hidden; + border-spacing: 15px; + outline-style: none; } + +.widetablecontainer { + overflow: auto; +} + +/* container for a table with centered entries */ + +table.data { + background-color: #f9f9f9; + border: 1px solid #2f6fab; + border-width: 1px; + border-collapse: collapse; + padding-left: 10px; + margin-top: 10px; + margin-left: 30px; + margin-right: 60px; + text-align: center; } + +table.data tt { + max-width: 400px; + display: inline-block; + word-wrap: break-word; +} + +/* container for a table with left-aligned entries */ + +table.data-list { + border: 1px solid #2f6fab; + border-width: 1px; + border-collapse: collapse; + padding-left: 10px; + margin-top: 10px; + margin-left: 30px; + margin-right: 60px; + margin-bottom: 20px; + text-align: left; +} + +table.data-list caption { + margin: 5px; +} + +table.data-list td{ + max-width: 600px; + overflow: hidden; + padding: 6px; +} + +/* layout hack to override default left margin in a table */ + +table.fullpage { + margin-top: 4px; + margin-left: -20px; + border-style: hidden; + outline-style: none; +} + +/* specialized container for quick reference indices */ + +table.quickref caption { + padding: 12px 6px 6px 6px; +} + +table.quickref .line { + padding: 2px 15px 2px 15px; +} + +table.quickref { + width: 600px; + margin-top: 0px; + margin-left: 30px; + border-style: hidden; + border-collapse: collapse; + outline-style: none; + text-align: left; +} + +hr.docutils { + background-color: transparent; + border: 1px solid rgb(204, 204, 204); + clear: none; + color: #333; + display: block; + float: none; + height: 0px; + margin-bottom: 6.5px; + margin-left: 0px; + margin-right: 0px; + margin-top: 6.5px; + width: 794px; +} + +/************************************************** + * CLASSES + **************************************************/ + +/* Only for use in the copyright in the footer */ +.size { + line-height: 100%; +} + +.no_Indent { + margin-left: inherit; + margin-top: 0; + margin-bottom: 0; +} + +.indentedMenu { + margin-left: 18; + margin-top: 0; + margin-bottom: 0; +} + +.indentedMenu2 { + margin-left: 36; + margin-top: 0; + margin-bottom: 0; +} + +.indentedMenu3 { + margin-left: 54; + margin-top: 0; + margin-bottom: 0; +} + +.literal-block { + padding: 1em; + background-color: #f9f9f9; + border: 1px dashed #2f6fab; + clear: both; + margin-left: 25px; + margin-right: 60px; + white-space: pre; + overflow: auto; + width: auto; + font-weight: normal; +} + +.no_Indent, .no_Indent_Bold, .indentedMenu, .indentedMenu2, .indentedMenu3 { + line-height: normal; +} + +.no_Indent a:link, .no_Indent_Bold a:link, .no_Indent a:visited, .no_Indent a:active, +.indentedMenu a:link, .indentedMenu a:visited, .indentedMenu a:active, +.indentedMenu2 a:link, .indentedMenu2 a:visited, .indentedMenu2 a:active, +.indentedMenu3 a:link, .indentedMenu3 a:visited, .indentedMenu3 a:active + { + text-decoration: none; +} + +.no_Indent_Bold +{ + font-weight : bold; +} + +.menu A:link { + text-decoration: none; + color: "#777777";} + +.menu A:visited { + text-decoration: none; + color: "#777777";} + +.menu A:hover { + background-color: "#CCCCCC"; + color: white; } + +.menu { + color: "#CCCCCC"; +} + +h1.title { + display: none; +} + + +/**************************************************** + * + * Special rst "containers" + * + ***************************************************/ + +.notebox { + padding: 0.2em 1em 1em 1em; + background-color: #f9f9f9; + border: 1px solid rgb(120,30,40); + clear: both; + margin-left: 60px; + margin-right: 60px; + /*float:right;*/ +} + +/* assume the first paragraph is a title */ + +.notebox p:first-child { + font-weight : bold; + color: rgb(120,30,40); + margin-bottom: 20px; + margin-top: 20px; +} + +/* code that only requires markup/emphasis */ + +.codefhead { + font-family: Monaco, Courier, "Courier New", monospace; + font-size: 13px!important; + clear: both; + margin-left: 0px; + background-color: #ddd; + border: none; + overflow: auto; + font-weight: normal; +} + +/* code that requires markup/emphasis and a pretty container */ + +.stylized-rib { + font-family: Monaco, Courier, "Courier New", monospace; + clear: both; + padding: 1em; + background-color: #f9f9f9; + border: 1px dashed #2f6fab; + font-weight: normal; +} + +/* for side-by-side code examples */ + +.shader-rib { + font-family: Monaco, Courier, "Courier New", monospace; + clear: both; + margin-left: 0px; + padding: 1em; + background-color: #f9f9f9; + border: 1px dashed #2f6fab; +} + +/* matches spacing of "codefhead", but restores default fonts */ + +.codefbody { + font-family : "Verdana", Helvetica, sans-serif; + clear: both; + margin-bottom: 13px; + margin-top: 5px; + margin-left: 30px; + margin-right: 60px; + font-weight: normal; +} + +/* special container for Important/Note/Tip pullouts */ + +.impnotip { + margin-top: 23px; + margin-bottom: 23px; + padding: 0.2em 1em 1em 1em; + border: 3px inset; + border-color: #CCCCCC; + clear: both; + margin-left: 60px; + margin-right: 60px; +} + +ul.auto-toc li { + list-style-type: none; +} + +ol li { + list-style-type: decimal; +} + +.imgboxtop { + border-top: 1px solid #ddd; + border-right: 1px solid #bbb; + border-left: 1px solid #ddd; + margin: 0; + padding-top: 10px; + padding-right: 10px; + padding-bottom: 10px; + padding-left: 10px; +} + +.imgboxbottom { + border-right: 1px solid #bbb; + border-bottom: 1px solid #bbb; + border-left: 1px solid #ddd; + margin: 0; + padding-top: 10px; + padding-right: 10px; + padding-bottom: 10px; + padding-left: 10px; +} + +.caption { + font-size: small; +} + +.code { + padding: 1em; + background-color: #f9f9f9; + border: 1px dashed #2f6fab; + clear: both; + font-weight: normal; + margin-right: 20px; +} + +pre { + border: 1px dashed #2f6fab; + background: #222; + padding: 5px 10px; + line-height: 21px; + word-wrap: normal; + text-align: left; + -moz-border-radius: 5px; + -webkit-border-radius: 5px; + white-space: pre; + overflow: auto; + width: auto; + font-weight: normal; +} + +code { + font-family: Monaco, Courier, "Courier New", monospace; + overflow: auto; + width: auto; + border: 0px; + background: transparent; + padding: 0px; +} + +.copyright { + text-align: center; + line-height: 80%; +} + +.highlight { + color: #880000; + font-weight: bold; +} + +div.navigation { + position:fixed; + width:245px; + border: 1px solid rgb(204, 204, 204); + border-radius:15px; + -moz-border-radius: 15px; + -webkit-border-radius: 15px; + text-decoration: none; + color: #9A9A9A; + font-size: 12px; + font-weight: 400; + font-family: futura-pt, sans-serif; +} + +div.navigation ul { + list-style-image: url('../images/toggler0.gif'); +} + +div.navigation a:link, +div.navigation a:visited, +div.navigation a:hover { + color: #9A9A9A; + text-decoration: none; +} + +div.document { + background: #FFF; + margin-top: 5px; + margin-left: 255px; + + padding-top: 15px; + padding-left: 15px; + padding-right: 15px; + padding-bottom: 15px; + + border-top-left-radius: 15px; + -moz-border-top-left-radius: 15px; + -webkit-border-top-left-radius: 15px; + border-top-right-radius: 15px; + -moz-border-top-right-radius: 15px; + -webkit-border-top-right-radius: 15px; +} + +div.document a, +div.document a:visited { + color: #333; +} + +div.document a:hover { + color: #FFCC03; +} + +div.footer { + background: #FFF; + margin-left: 255px; + padding-top: 15px; + padding-left: 5px; + padding-right: 5px; + padding-bottom: 15px; + + border-bottom-left-radius: 15px; + -moz-border-bottom-left-radius: 15px; + -webkit-border-bottom-left-radius: 15px; + border-bottom-right-radius: 15px; + -moz-border-bottom-right-radius: 15px; + -webkit-border-bottom-right-radius: 15px; +} + +div.contents.local.topic { + background-color: transparent; + border: 1px solid #DEDBE7; + border-collapse: collapse; + margin-left: 60px; + margin-right: 60px; + margin-bottom: 15px; +} + +img.align-center, .align-center img { + display: block; + margin-left: auto; + margin-right: auto +} + + +/**************************************************** +****************************************************/ + +body { + background-image: url('../images/background.jpg'); + background-repeat:repeat; +} + +.page{ + position:relative; + width: 946px; + margin:0 auto 0px auto; +} + +.hidden { + display: none; +} + +/**************************************************** +****************************************************/ + +#searchInput{ + /*background: #474747;*/ + background: #9A9A9A; + -moz-border-radius: 5px; + -webkit-border-radius: 5px; + -khtml-border-radius: 5px; + border-radius: 5px; + border: 1px solid black; + -moz-box-shadow: 0 1px 0 #444444; + -webkit-box-shadow: 0 1px 0 #444; + color: white; + font-size: 11px; + padding: 5px 5px; + width: 145px; + height: 17px; + margin-left: 10px; +} + +#searchButton{ + -moz-border-radius: 5px; + -webkit-border-radius: 5px; + -khtml-border-radius: 5px; + border-radius: 5px; + background: black; + filter: progid:DXImageTransform.Microsoft.gradient(startColorstr='#333333', endColorstr='#111111'); + background: -webkit-gradient(linear, left top, left bottom, from(#333), to(#111)); + background: -moz-linear-gradient(bottom, #111, #333); + box-shadow: inset 0px 1px 0px #555; + -webkit-box-shadow: inset 0px 1px 0px #555; + -moz-box-shadow: inset 0px 1px 0px #555; + /*color: #DDD;*/ + color: #9A9A9A; + text-transform: uppercase; + font-size: 11px; + padding: 6px 10px; + border: 1px solid black; + height: 28px; +} + diff --git a/documentation/diagrams.odg b/documentation/diagrams.odg new file mode 100644 index 00000000..a0b26803 Binary files /dev/null and b/documentation/diagrams.odg differ diff --git a/documentation/getting_started.rst b/documentation/getting_started.rst new file mode 100644 index 00000000..743b75cc --- /dev/null +++ b/documentation/getting_started.rst @@ -0,0 +1,207 @@ +.. + Copyright (C) Pixar. All rights reserved. + + This license governs use of the accompanying software. If you + use the software, you accept this license. If you do not accept + the license, do not use the software. + + 1. Definitions + The terms "reproduce," "reproduction," "derivative works," and + "distribution" have the same meaning here as under U.S. + copyright law. A "contribution" is the original software, or + any additions or changes to the software. + A "contributor" is any person or entity that distributes its + contribution under this license. + "Licensed patents" are a contributor's patent claims that read + directly on its contribution. + + 2. Grant of Rights + (A) Copyright Grant- Subject to the terms of this license, + including the license conditions and limitations in section 3, + each contributor grants you a non-exclusive, worldwide, + royalty-free copyright license to reproduce its contribution, + prepare derivative works of its contribution, and distribute + its contribution or any derivative works that you create. + (B) Patent Grant- Subject to the terms of this license, + including the license conditions and limitations in section 3, + each contributor grants you a non-exclusive, worldwide, + royalty-free license under its licensed patents to make, have + made, use, sell, offer for sale, import, and/or otherwise + dispose of its contribution in the software or derivative works + of the contribution in the software. + + 3. Conditions and Limitations + (A) No Trademark License- This license does not grant you + rights to use any contributor's name, logo, or trademarks. + (B) If you bring a patent claim against any contributor over + patents that you claim are infringed by the software, your + patent license from such contributor to the software ends + automatically. + (C) If you distribute any portion of the software, you must + retain all copyright, patent, trademark, and attribution + notices that are present in the software. + (D) If you distribute any portion of the software in source + code form, you may do so only under this license by including a + complete copy of this license with your distribution. If you + distribute any portion of the software in compiled or object + code form, you may only do so under a license that complies + with this license. + (E) The software is licensed "as-is." You bear the risk of + using it. The contributors give no express warranties, + guarantees or conditions. You may have additional consumer + rights under your local laws which this license cannot change. + To the extent permitted under your local laws, the contributors + exclude the implied warranties of merchantability, fitness for + a particular purpose and non-infringement. + + +Getting Started +--------------- + +.. contents:: + :local: + :backlinks: none + + +Getting started with Git and accessing the source code. + + +Downloading the code +==================== + +The code is hosted on a Github public repository. Download and setup information +for Git tools can be found `here `__. + +You can access the OpenSubdiv Git repository at https://github.com/PixarAnimationStudios/OpenSubdiv + +From there, there are several ways of downloading the OpenSubdiv source code. + + - Zip archive : downloaded from `here `__ + + - Using a GUI client : you can find a list `here `__ + Please refer to the documentation of your preferred application. + + - From the GitShell, Cygwin or the CLI : assuming that you have the Git tools + installed, you can clone the OpenSubdiv repository directly with the + following command: + + .. code:: c++ + + git clone https://github.com/PixarAnimationStudios/OpenSubdiv.git + + + +These methods only pull static archives, which is are not under the version +control system and therefore cannot pull updates or push changes back. If you +intend on contributing features or fixes to the main trunk of the code, you will +need to create a free Github account and clone a fork of the OpenSubdiv repository. + +Submissions to the main code trunk can be sent using Git's pull-request mechanisms. +Please note that we are using the git flow tools so all changes should be made to +our 'dev' branch. Before we can accept submissions however, we will need a signed +`Contributor's License Agreement `__. + +---- + +Branches & Git Flow +=================== + +Since version 1.1.0, OpenSubdiv has adopted the +`Git Flow branching model `__. + +Our active development branch is named 'dev' : all new features and buf fixes should +be submitted to this branch. The changes submitted to the dev branch are periodically +patched to the 'master' branch as new versions are released. + +Checking out branches +_____________________ + +The Git Flow `tools `__ are not a requisite for +working with the OpenSubdiv code base, but new work should always be performed in +the 'dev' branch, or dedicated feature-branches. By default, a cloned repository +will be pointing to the 'master' branch. You can switch to the 'dev' branch using +the following command: + +.. code:: c++ + + git branch dev + +You can check that the branch has now been switched simply with: + +.. code:: c++ + + git branch + +Which should return: + +.. code:: c++ + + * dev + master + + +API Versions +____________ + +OpenSubdiv maintains an internal API versioning system. The version number can be +read from the file `./opensubdiv/version.h `__. +Following the Git-Flow pattern, our releases are indexed using Git's tagging +system. + +List of the existing tags: + +.. code:: c++ + + git tag --list + +Checking out version 1.2.0: + +.. code:: c++ + + git checkout v1_2_0 + +Making Changes +______________ + +Direct push access to the OpenSubdiv master repository is currently limited to a +small internal development team, so external submissions should be made by sending +`pull-requests `__ from +forks of our 'dev' branch. + +---- + +Code Overview +============= + +The OpenSubdiv code base contains 4 main areas: + +./opensubdiv/ +_____________ + +The main subdivision APIs : Hbr, Far and Osd. + + +./regression/ +_____________ + +Standalone regression tests and baseline data to help maintain the integrity of +our APIs. If GPU SDKs are detected, some tests will attempt to run computations +on those GPUs. + +./examples/ +___________ + +A small collection of standalone applications that illustrate how to deploy the +various features and optimizations of the OpenSubdiv APIs. The GL-based examples +rely on the cross-platform GLFW API for interactive window management, while the +DirectX ones are OS-native. + +./documentation/ +________________ + +The reStructuredText source files along with python scripts that generate the HTML +documentation site. + +---- + +Next : `Building OpenSubdiv `__ diff --git a/documentation/glviewer.rst b/documentation/glviewer.rst new file mode 100644 index 00000000..39c696d5 --- /dev/null +++ b/documentation/glviewer.rst @@ -0,0 +1,101 @@ +.. + Copyright (C) Pixar. All rights reserved. + + This license governs use of the accompanying software. If you + use the software, you accept this license. If you do not accept + the license, do not use the software. + + 1. Definitions + The terms "reproduce," "reproduction," "derivative works," and + "distribution" have the same meaning here as under U.S. + copyright law. A "contribution" is the original software, or + any additions or changes to the software. + A "contributor" is any person or entity that distributes its + contribution under this license. + "Licensed patents" are a contributor's patent claims that read + directly on its contribution. + + 2. Grant of Rights + (A) Copyright Grant- Subject to the terms of this license, + including the license conditions and limitations in section 3, + each contributor grants you a non-exclusive, worldwide, + royalty-free copyright license to reproduce its contribution, + prepare derivative works of its contribution, and distribute + its contribution or any derivative works that you create. + (B) Patent Grant- Subject to the terms of this license, + including the license conditions and limitations in section 3, + each contributor grants you a non-exclusive, worldwide, + royalty-free license under its licensed patents to make, have + made, use, sell, offer for sale, import, and/or otherwise + dispose of its contribution in the software or derivative works + of the contribution in the software. + + 3. Conditions and Limitations + (A) No Trademark License- This license does not grant you + rights to use any contributor's name, logo, or trademarks. + (B) If you bring a patent claim against any contributor over + patents that you claim are infringed by the software, your + patent license from such contributor to the software ends + automatically. + (C) If you distribute any portion of the software, you must + retain all copyright, patent, trademark, and attribution + notices that are present in the software. + (D) If you distribute any portion of the software in source + code form, you may do so only under this license by including a + complete copy of this license with your distribution. If you + distribute any portion of the software in compiled or object + code form, you may only do so under a license that complies + with this license. + (E) The software is licensed "as-is." You bear the risk of + using it. The contributors give no express warranties, + guarantees or conditions. You may have additional consumer + rights under your local laws which this license cannot change. + To the extent permitted under your local laws, the contributors + exclude the implied warranties of merchantability, fitness for + a particular purpose and non-infringement. + + +glViewer +-------- + +.. contents:: + :local: + :backlinks: none + +SYNOPSIS +======== + +.. parsed-literal:: + :class: codefhead + + **glViewer** [**-d** *isolation level*] [**-c** *animation loops*] [**-f**] *objfile(s)* + +DESCRIPTION +=========== + +``glViewer`` is a stand-alone application that showcases the application of +uniform and feature adaptive subdivision schemes to a collection of geometric +shapes. Multiple controls are available to experiment with the algorithms. + +.. image:: images/glviewer.png + :width: 400px + :align: center + :target: images/glviewer.png + +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 animtion loop (default=0 is infinite) + +**-f** + Launches the application in full-screen mode (if is supported by GLFW on the + OS). + +SEE ALSO +======== + diff --git a/documentation/images/adaptive.gif b/documentation/images/adaptive.gif new file mode 100644 index 00000000..81ddd507 Binary files /dev/null and b/documentation/images/adaptive.gif differ diff --git a/documentation/images/background.jpg b/documentation/images/background.jpg new file mode 100644 index 00000000..352a18a3 Binary files /dev/null and b/documentation/images/background.jpg differ diff --git a/documentation/images/evalLimit_hedit0.jpg b/documentation/images/evalLimit_hedit0.jpg new file mode 100644 index 00000000..32f7955e Binary files /dev/null and b/documentation/images/evalLimit_hedit0.jpg differ diff --git a/documentation/images/geri.jpg b/documentation/images/geri.jpg new file mode 100644 index 00000000..5033dbd7 Binary files /dev/null and b/documentation/images/geri.jpg differ diff --git a/documentation/images/glviewer.png b/documentation/images/glviewer.png new file mode 100644 index 00000000..03a0d057 Binary files /dev/null and b/documentation/images/glviewer.png differ diff --git a/documentation/images/half_edge.png b/documentation/images/half_edge.png new file mode 100644 index 00000000..a08edcc3 Binary files /dev/null and b/documentation/images/half_edge.png differ diff --git a/documentation/images/half_edge_cycle.png b/documentation/images/half_edge_cycle.png new file mode 100644 index 00000000..321e52ed Binary files /dev/null and b/documentation/images/half_edge_cycle.png differ diff --git a/documentation/images/nonmanifold_fan.png b/documentation/images/nonmanifold_fan.png new file mode 100644 index 00000000..99bf40c2 Binary files /dev/null and b/documentation/images/nonmanifold_fan.png differ diff --git a/documentation/images/nonmanifold_vert.png b/documentation/images/nonmanifold_vert.png new file mode 100644 index 00000000..e9036eaf Binary files /dev/null and b/documentation/images/nonmanifold_vert.png differ diff --git a/documentation/images/opensubdiv_logo_color_shadow.png b/documentation/images/opensubdiv_logo_color_shadow.png new file mode 100644 index 00000000..9f672db9 Binary files /dev/null and b/documentation/images/opensubdiv_logo_color_shadow.png differ diff --git a/documentation/images/opensubdiv_logo_header.png b/documentation/images/opensubdiv_logo_header.png new file mode 100644 index 00000000..170ad337 Binary files /dev/null and b/documentation/images/opensubdiv_logo_header.png differ diff --git a/documentation/images/subdiv_faceindex.png b/documentation/images/subdiv_faceindex.png new file mode 100644 index 00000000..7e4ba0d6 Binary files /dev/null and b/documentation/images/subdiv_faceindex.png differ diff --git a/documentation/images/toggler0.gif b/documentation/images/toggler0.gif new file mode 100644 index 00000000..c39c5f3b Binary files /dev/null and b/documentation/images/toggler0.gif differ diff --git a/documentation/images/toggler1.gif b/documentation/images/toggler1.gif new file mode 100644 index 00000000..31f11323 Binary files /dev/null and b/documentation/images/toggler1.gif differ diff --git a/documentation/images/torus.png b/documentation/images/torus.png new file mode 100644 index 00000000..949fda7a Binary files /dev/null and b/documentation/images/torus.png differ diff --git a/documentation/images/uniform.gif b/documentation/images/uniform.gif new file mode 100644 index 00000000..3d1db29f Binary files /dev/null and b/documentation/images/uniform.gif differ diff --git a/documentation/intro.rst b/documentation/intro.rst new file mode 100644 index 00000000..a0885dee --- /dev/null +++ b/documentation/intro.rst @@ -0,0 +1,188 @@ +.. + Copyright (C) Pixar. All rights reserved. + + This license governs use of the accompanying software. If you + use the software, you accept this license. If you do not accept + the license, do not use the software. + + 1. Definitions + The terms "reproduce," "reproduction," "derivative works," and + "distribution" have the same meaning here as under U.S. + copyright law. A "contribution" is the original software, or + any additions or changes to the software. + A "contributor" is any person or entity that distributes its + contribution under this license. + "Licensed patents" are a contributor's patent claims that read + directly on its contribution. + + 2. Grant of Rights + (A) Copyright Grant- Subject to the terms of this license, + including the license conditions and limitations in section 3, + each contributor grants you a non-exclusive, worldwide, + royalty-free copyright license to reproduce its contribution, + prepare derivative works of its contribution, and distribute + its contribution or any derivative works that you create. + (B) Patent Grant- Subject to the terms of this license, + including the license conditions and limitations in section 3, + each contributor grants you a non-exclusive, worldwide, + royalty-free license under its licensed patents to make, have + made, use, sell, offer for sale, import, and/or otherwise + dispose of its contribution in the software or derivative works + of the contribution in the software. + + 3. Conditions and Limitations + (A) No Trademark License- This license does not grant you + rights to use any contributor's name, logo, or trademarks. + (B) If you bring a patent claim against any contributor over + patents that you claim are infringed by the software, your + patent license from such contributor to the software ends + automatically. + (C) If you distribute any portion of the software, you must + retain all copyright, patent, trademark, and attribution + notices that are present in the software. + (D) If you distribute any portion of the software in source + code form, you may do so only under this license by including a + complete copy of this license with your distribution. If you + distribute any portion of the software in compiled or object + code form, you may only do so under a license that complies + with this license. + (E) The software is licensed "as-is." You bear the risk of + using it. The contributors give no express warranties, + guarantees or conditions. You may have additional consumer + rights under your local laws which this license cannot change. + To the extent permitted under your local laws, the contributors + exclude the implied warranties of merchantability, fitness for + a particular purpose and non-infringement. + + +Introduction +------------ + +.. contents:: + :local: + :backlinks: none + +.. image:: images/geri.jpg + :width: 600px + :align: center + +---- + +Introduction +============ + +OpenSubdiv is a set of open source libraries that implement high performance +subdivision surface (subdiv) evaluation on massively parallel CPU and GPU +architectures. This codepath is optimized for drawing deforming surfaces with +static topology at interactive framerates. The resulting limit surface are a match +for Pixar's Renderman specification within numerical precision limits. + +OpenSubdiv is a code API which we hope to integrate into 3rd. party digital +content creation tools. It is **not** an application nor a tool that can be used +directly to create digital assets. + +---- + +Why Fast Subdivision ? +====================== + +Subdivision surfaces are commonly used for final rendering of character shapes +for a smooth and controllable limit surfaces. However, subdivision surfaces in +interactive apps are typically drawn as their polygonal control hulls because of +performance. The polygonal control hull is an approximation that is offset from +the true limit surface. Looking at an approximation in the interactive app makes +it difficult to see exact contact, like fingers touching a potion bottle or hands +touching a cheek. It also makes it difficult to see poke-throughs in cloth simulation +if the skin and cloth are both approximations. This problem is particularly bad when +one character is much larger than another and unequal subdiv face sizes cause +approximation errors to be magnified. + +Maya and Pixar's proprietary Presto animation system can take 100ms to subdivide +a character of 30,000 polygons to the second level of subdivision (500,000 polygons). +By doing the same thing in 3ms, OpenSubdiv allows the user to see the smooth, +accurate limit surface at all times. + +---- + +Research +======== + +The new GPU technology behind OpenSubdiv is the result of a joint research effort +between Pixar and Microsoft. + + | *Feature Adaptive GPU Rendering of Catmull-Clark Subdivision Surfaces* + | Matthias Niessner, Charles Loop, Mark Meyer, and Tony DeRose + | ACM Transactions on Graphics, Vol. 31 No. 1 Article 6 January 2012 + | ``_ + | + | *Efficient Evaluation of Semi-Smooth Creases in Catmull-Clark Subdivision Surfaces* + | Matthias Niessner, Charles Loop, and Guenter Greiner. + | Eurographics Proceedings, Cagliari, 2012 + | ``_ + | + | *Analytic Displacement Mapping using Hardware Tessellation* + | Matthias Niessner, Charles Loop + | ACM Transactions on Graphics, To appear 2013 + | ``_ + +---- + +Heritage +======== + +This is the fifth-generation subdiv library in use by Pixar's proprietary animation +system in a lineage that started with code written by Tony DeRose and Tien Truong +for Geri\u2019s Game in 1996. Each generation has been a from-scratch rewrite that +has built upon our experience using subdivision surfaces to make animated films. +This code is live, so Pixar's changes to OpenSubdiv for current and future films +will be released as open source at the same time they are rolled out to Pixar +animation production. + + | *Subdivision Surfaces in Character Animation* + | Tony DeRose, Michael Kass, Tien Truong + | Proceedings of SIGGRAPH 1998 + | ``_ + | + | *Recursively generated B-spline surfaces on arbitrary topological meshes* + | Catmull, E.; Clark, J. Computer-Aided Design 10 (6) (1978) + +---- + +Licensing +========= + +OpenSubdiv is covered by the `Microsoft Public License +`__, and is free to use +for commercial or non-commercial use. This is the same code that Pixar uses +internally for animated film production. Our intent is to encourage high +performance accurate subdiv drawing by giving away the "good stuff". + +Feel free to use it and let us know what you think. + +---- + +Contributing +============ + +In order for us to accept code submissions (merge git pull-requests), contributors +need to sign the "Contributor License Agreement" (found in the code repository or +`here `__) +and you can either email or fax it to Pixar. + +For more details about OpenSubdiv, see `Pixar Graphics Technologies `__. + +---- + +External Resources +================== + +Microsoft Research: + `Charles Loop `__ + `Matthias Niessner `__ + +Pixar Research: + `Pixar R&D Portal `__ + + + + diff --git a/documentation/nav_template.txt b/documentation/nav_template.txt new file mode 100644 index 00000000..8a9e516c --- /dev/null +++ b/documentation/nav_template.txt @@ -0,0 +1,112 @@ + + +
+
+
+ +
+
+
+
+
+ + +
+
+
+ +
+
+
+
diff --git a/documentation/processHtml.py b/documentation/processHtml.py new file mode 100755 index 00000000..e095e62d --- /dev/null +++ b/documentation/processHtml.py @@ -0,0 +1,195 @@ +#!/usr/bin/env python + +# +# Copyright (C) Pixar. All rights reserved. +# +# This license governs use of the accompanying software. If you +# use the software, you accept this license. If you do not accept +# the license, do not use the software. +# +# 1. Definitions +# The terms "reproduce," "reproduction," "derivative works," and +# "distribution" have the same meaning here as under U.S. +# copyright law. A "contribution" is the original software, or +# any additions or changes to the software. +# A "contributor" is any person or entity that distributes its +# contribution under this license. +# "Licensed patents" are a contributor's patent claims that read +# directly on its contribution. +# +# 2. Grant of Rights +# (A) Copyright Grant- Subject to the terms of this license, +# including the license conditions and limitations in section 3, +# each contributor grants you a non-exclusive, worldwide, +# royalty-free copyright license to reproduce its contribution, +# prepare derivative works of its contribution, and distribute +# its contribution or any derivative works that you create. +# (B) Patent Grant- Subject to the terms of this license, +# including the license conditions and limitations in section 3, +# each contributor grants you a non-exclusive, worldwide, +# royalty-free license under its licensed patents to make, have +# made, use, sell, offer for sale, import, and/or otherwise +# dispose of its contribution in the software or derivative works +# of the contribution in the software. +# +# 3. Conditions and Limitations +# (A) No Trademark License- This license does not grant you +# rights to use any contributor's name, logo, or trademarks. +# (B) If you bring a patent claim against any contributor over +# patents that you claim are infringed by the software, your +# patent license from such contributor to the software ends +# automatically. +# (C) If you distribute any portion of the software, you must +# retain all copyright, patent, trademark, and attribution +# notices that are present in the software. +# (D) If you distribute any portion of the software in source +# code form, you may do so only under this license by including a +# complete copy of this license with your distribution. If you +# distribute any portion of the software in compiled or object +# code form, you may only do so under a license that complies +# with this license. +# (E) The software is licensed "as-is." You bear the risk of +# using it. The contributors give no express warranties, +# guarantees or conditions. You may have additional consumer +# rights under your local laws which this license cannot change. +# To the extent permitted under your local laws, the contributors +# exclude the implied warranties of merchantability, fitness for +# a particular purpose and non-infringement. +# + +import os +import sys +import string +import re +import HTMLParser + +class HtmlToTextParser(HTMLParser.HTMLParser): + def __init__(self): + HTMLParser.HTMLParser.__init__(self) + self.m_text = [] + self.m_inTitle = False + self.m_inScript = False + self.m_inStyle = False + self.m_title = "" + self.m_navigation = False + + def handle_data(self, data): + if self.m_inScript or self.m_inStyle: + return + text = data.strip() + if len(text) > 0: + text = re.sub('[\s]+', ' ', text) + text = re.sub('[^\.,\- a-zA-Z0-9_]+', '', text) + self.m_text.append(text + ' ') + if self.m_inTitle: + self.m_title = str(text) + + def handle_endtag(self, tag): + if tag.lower() == "title": self.m_inTitle = False + if tag.lower() == "script": self.m_inScript = False + if tag.lower() == "style": self.m_inStyle = False + + def handle_starttag(self, tag, attrs): + if tag.lower() == "title": self.m_inTitle = True + if tag.lower() == "script": self.m_inScript = True + if tag.lower() == "style": self.m_inStyle = True + if tag.lower() == "div": + for attr in attrs: + if (len(attr)>=2 and \ + attr[0].lower()=="class" and \ + attr[1].lower()=="navigation"): + self.m_navigation = True + + def HasNavigationSection(self): + return self.m_navigation + + def GetText(self): + return ''.join(self.m_text).strip() + + def GetTitle(self): + return self.m_title + +#------------------------------------------------------------------------------- +def WriteIndexFile( outputFile, content ): + outputPath = os.path.dirname( outputFile ) + + try: + os.makedirs( outputPath ); + except: + pass + + print "Creating Search-Index File : \""+outputFile+"\"" + + f = open(outputFile, "w") + f.write(content) + f.close() + +#------------------------------------------------------------------------------- +def Usage(): + print str(sys.argv[0])+" " + exit(1); + + +#------------------------------------------------------------------------------- +# Main + +if (len(sys.argv)<3): + Usage() + +rootDir = str(sys.argv[1]) + +outputDir = str(sys.argv[2]) + +f = open( str(sys.argv[3]), "r") +navHtml = f.read() +f.close() + +print "rootDir="+rootDir+" outputDir="+outputDir + +searchIndex = 'var tipuesearch = { "pages": [ ' + +for root, dirs, files in os.walk(rootDir): + for f in files: + + inputFile = os.path.join(root, f) + if inputFile.endswith(".html") or inputFile.endswith(".htm") : + + f = open(inputFile, "r+") + html = f.read() + + # parse search index data + parser = HtmlToTextParser() + try: + parser.feed(html) + title = parser.GetTitle() + text = parser.GetText() + except HTMLParser.HTMLParseError: + continue + + msg = " \""+inputFile+"\" - " + + # index the contents of the page for search + if (not inputFile.lower().endswith("search.html")): + if title == "": + title = "untitled" + loc = os.path.relpath(inputFile, rootDir) + searchIndex += '{"title":"'+title+'", "text":"'+text+'", "tags": "", "loc":"'+loc+'"}, \n' + msg += "indexed - " + + # insert navigation html + if (not parser.HasNavigationSection()): + loc = string.find(html,"") + html = html[:loc+6] + navHtml + html[loc+6:] + + msg += "added navigation" + + f.seek(0) + f.write(html) + f.close() + + print msg + +searchIndex = searchIndex + "]};" + +WriteIndexFile( os.path.join(outputDir, "tipuesearch", "tipuesearch_content.js"), searchIndex ) + diff --git a/documentation/release_notes.rst b/documentation/release_notes.rst new file mode 100644 index 00000000..499fce81 --- /dev/null +++ b/documentation/release_notes.rst @@ -0,0 +1,139 @@ +.. + Copyright (C) Pixar. All rights reserved. + + This license governs use of the accompanying software. If you + use the software, you accept this license. If you do not accept + the license, do not use the software. + + 1. Definitions + The terms "reproduce," "reproduction," "derivative works," and + "distribution" have the same meaning here as under U.S. + copyright law. A "contribution" is the original software, or + any additions or changes to the software. + A "contributor" is any person or entity that distributes its + contribution under this license. + "Licensed patents" are a contributor's patent claims that read + directly on its contribution. + + 2. Grant of Rights + (A) Copyright Grant- Subject to the terms of this license, + including the license conditions and limitations in section 3, + each contributor grants you a non-exclusive, worldwide, + royalty-free copyright license to reproduce its contribution, + prepare derivative works of its contribution, and distribute + its contribution or any derivative works that you create. + (B) Patent Grant- Subject to the terms of this license, + including the license conditions and limitations in section 3, + each contributor grants you a non-exclusive, worldwide, + royalty-free license under its licensed patents to make, have + made, use, sell, offer for sale, import, and/or otherwise + dispose of its contribution in the software or derivative works + of the contribution in the software. + + 3. Conditions and Limitations + (A) No Trademark License- This license does not grant you + rights to use any contributor's name, logo, or trademarks. + (B) If you bring a patent claim against any contributor over + patents that you claim are infringed by the software, your + patent license from such contributor to the software ends + automatically. + (C) If you distribute any portion of the software, you must + retain all copyright, patent, trademark, and attribution + notices that are present in the software. + (D) If you distribute any portion of the software in source + code form, you may do so only under this license by including a + complete copy of this license with your distribution. If you + distribute any portion of the software in compiled or object + code form, you may only do so under a license that complies + with this license. + (E) The software is licensed "as-is." You bear the risk of + using it. The contributors give no express warranties, + guarantees or conditions. You may have additional consumer + rights under your local laws which this license cannot change. + To the extent permitted under your local laws, the contributors + exclude the implied warranties of merchantability, fitness for + a particular purpose and non-infringement. + + +Release Notes +------------- + +.. contents:: + :local: + :backlinks: none + + +Release 1.2.4 +============= + +- Adding a much needed API documention system based on Docutils RST markup. + +Release 1.2.3 +============= + +- EvalLimit API refactor : the EvalContext now has dedicated structs to track all + the vertex, varying and face-varying data streams. Also renamed some "buffers" + into "tables" to maintain code consistency +- EvalLimit optimization : switch serial indexing to a quad-tree based search +- Adding Varying and Face-Varying data interpolation to EvalLimit +- Face-varying data bug fixes : making sure the data is carried around appropriately + Fixes for OpenCL use with the new batching APIs +- GLSL general shader code cleanup & fixes for better portability +- GLSL Tranform Feedback initialization fix +- Critical fix for FarMultiMesh batching (indexing was incorrect) +- Fix osdutil CL implementation (protect #includes on systems with no OpenCL SDK + installed) +- Fix face-varying interpolation on adaptive patches +- FarPatchTables : fix IsFeatureAdaptive() to return the correct answer +- Fix Far factories to handle the absence of face-varying data correctly. +- Many GLSL shader code style fixes which should help with ATI / OSX shader compiling + +Release 1.2.2 +============= + +- Introducing the EvalLimit API : the Eval module aims at providing support for + computational tasks that are not related to drawing the surfaces. The EvalLimit + sub-module provides an API that enables client code to evaluate primitive variables + on the limit surface. +- OsdComputeController : minor optimization. Added early exit to Refine method + to avoid unnecessary interop. +- OsdGLDawContext : minor API change. Protecting some member variables and adding + const accessors +- OsdError : minor API refactor, added Warning functions. +- Fix Ptex bug : prevent corner texel guttering code to from going into infinite + loops +- Adding the ability for a FarMeshFactory to construct patchTables starting from + 'firstLevel' in uniform subdivision mode +- Consolidating the color coding of bicubic patch types through all our our code + examples (this is used mostly as a debugging tool) +- Fixing some MSVC++ build warnings +- Update to the outdated README.md + +.. image:: images/evalLimit_hedit0.jpg + :height: 300px + :align: center + :target: images/evalLimit_hedit0.jpg + +Release 1.2.1 +============= + +- Added CUDA runtime error checking + +Release 1.2.0 +============= + +- Major Far refactor around patchTables to introduce the draw batching API +- Renaming osd_util to osdutil +- Fix GLSL transform feedback initialization bug in ptexViewer +- Minor bug & typo fixes + +Release 1.1.0 +============= + +- release initiated because of the switch to Git Flow + +Release 1.0.0 +============= + +Oringal release: + diff --git a/documentation/search.html b/documentation/search.html new file mode 100644 index 00000000..aa79686a --- /dev/null +++ b/documentation/search.html @@ -0,0 +1,93 @@ + + + + + + + Search Results + + + + + + + + + + + +
+
+
+
+
+
+
+ +
+ + + + diff --git a/documentation/subdivision_surfaces.rst b/documentation/subdivision_surfaces.rst new file mode 100644 index 00000000..de086cf9 --- /dev/null +++ b/documentation/subdivision_surfaces.rst @@ -0,0 +1,145 @@ +.. + Copyright (C) Pixar. All rights reserved. + + This license governs use of the accompanying software. If you + use the software, you accept this license. If you do not accept + the license, do not use the software. + + 1. Definitions + The terms "reproduce," "reproduction," "derivative works," and + "distribution" have the same meaning here as under U.S. + copyright law. A "contribution" is the original software, or + any additions or changes to the software. + A "contributor" is any person or entity that distributes its + contribution under this license. + "Licensed patents" are a contributor's patent claims that read + directly on its contribution. + + 2. Grant of Rights + (A) Copyright Grant- Subject to the terms of this license, + including the license conditions and limitations in section 3, + each contributor grants you a non-exclusive, worldwide, + royalty-free copyright license to reproduce its contribution, + prepare derivative works of its contribution, and distribute + its contribution or any derivative works that you create. + (B) Patent Grant- Subject to the terms of this license, + including the license conditions and limitations in section 3, + each contributor grants you a non-exclusive, worldwide, + royalty-free license under its licensed patents to make, have + made, use, sell, offer for sale, import, and/or otherwise + dispose of its contribution in the software or derivative works + of the contribution in the software. + + 3. Conditions and Limitations + (A) No Trademark License- This license does not grant you + rights to use any contributor's name, logo, or trademarks. + (B) If you bring a patent claim against any contributor over + patents that you claim are infringed by the software, your + patent license from such contributor to the software ends + automatically. + (C) If you distribute any portion of the software, you must + retain all copyright, patent, trademark, and attribution + notices that are present in the software. + (D) If you distribute any portion of the software in source + code form, you may do so only under this license by including a + complete copy of this license with your distribution. If you + distribute any portion of the software in compiled or object + code form, you may only do so under a license that complies + with this license. + (E) The software is licensed "as-is." You bear the risk of + using it. The contributors give no express warranties, + guarantees or conditions. You may have additional consumer + rights under your local laws which this license cannot change. + To the extent permitted under your local laws, the contributors + exclude the implied warranties of merchantability, fitness for + a particular purpose and non-infringement. + + +Subdivision Surfaces +-------------------- + +.. contents:: + :local: + :backlinks: none + +Ordinary cubic B-spline surfaces are rectangular grids of tensor-product patches. +Subdivision surfaces generalize these to control grids with arbitrary connectivity. + +---- + +Topology +======== + +Topology is a major area of mathematics concerned with the most basic properties +of space, such as connectedness, continuity and boundary. + +.. image:: images/torus.png + :align: center + :height: 200 + +---- + +Manifold Geometry +***************** + +Continuous limit surfaces require that the topology be a two-dimensional +manifold. It is therefore possible to model non-manifold geometry that cannot +be subdivided to a smooth limit. + +---- + +Fan ++++ + +This "fan" configuration shows an edge shared by 3 distinct faces. + +.. image:: images/nonmanifold_fan.png + :align: center + :target: images/nonmanifold_fan.png + +---- + +Disconnected Vertex ++++++++++++++++++++ + +A vertex is disconnected from any edge and face. + +.. image:: images/nonmanifold_vert.png + :align: center + :target: images/nonmanifold_vert.png + +---- + +Hierarchical Edits +================== + +.. image:: images/subdiv_faceindex.png + :align: center + :target: images/subdiv_faceindex.png + + +---- + +Uniform Subdivision +=================== + +Applies a uniform refinement scheme to the coarse faces of a mesh. + +.. image:: images/uniform.gif + :align: center + :width: 300 + :target: images/uniform.gif + +---- + +Feature Adaptive Subdivision +============================ + +Isolates extraordinary features by applying progressive refinement. + +.. image:: images/adaptive.gif + :align: center + :width: 300 + :target: images/adaptive.gif + + diff --git a/documentation/tipuesearch/img/loader.gif b/documentation/tipuesearch/img/loader.gif new file mode 100644 index 00000000..9c97738a Binary files /dev/null and b/documentation/tipuesearch/img/loader.gif differ diff --git a/documentation/tipuesearch/img/search.png b/documentation/tipuesearch/img/search.png new file mode 100755 index 00000000..9ab0f2c1 Binary files /dev/null and b/documentation/tipuesearch/img/search.png differ diff --git a/documentation/tipuesearch/tipuesearch.css b/documentation/tipuesearch/tipuesearch.css new file mode 100644 index 00000000..4bc9b90e --- /dev/null +++ b/documentation/tipuesearch/tipuesearch.css @@ -0,0 +1,231 @@ + +/* +Tipue Search 3.0 +Copyright (c) 2013 Tipue +Tipue Search is released under the MIT License +http://www.tipue.com/search +*/ + + +#tipue_search_input +{ +/* + font: 12px/1.7 'open sans', sans-serif; + color: #333; + padding: 7px; + width: 150px; + border: 1px solid #e2e2e2; + border-radius: 0; + -moz-appearance: none; + -webkit-appearance: none; + box-shadow: none; + outline: 0; + margin: 0; +*/ + color: #333; + border: 1px solid #d3d3d3; + -moz-border-radius: 3px; + -webkit-border-radius: 3px; + -khtml-border-radius: 3px; + border-radius: 3px; + font-size: 13px; + padding-top: 5px; + padding-bottom: 5px; + padding-left: 5px; + padding-right: 5px; + width: 300px; +} +#tipue_search_input:focus +{ + border: 1px solid #ccc; +} +#tipue_search_button +{ +/* + width: 70px; + height: 36px; + border: 0; + border-radius: 1px; + background: #5193fb url('img/search.png') no-repeat center; + outline: none; +*/ + border: 1px solid #dcdcdc; + background: #444 url('img/search.png') no-repeat center; + -moz-border-radius: 3px; + -webkit-border-radius: 3px; + -khtml-border-radius: 3px; + border-radius: 3px; + color: #DDD; + text-transform: uppercase; + padding-top: 5px; + padding-bottom: 5px; + padding-left: 5px; + padding-right: 5px; + width: 40px; +} +#tipue_search_button:hover +{ +/* + background-color: #4589fb; +*/ + border: 1px solid #c3c3c3; + -moz-box-shadow: 1px 1px 2px #e3e3e3; + -webkit-box-shadow: 1px 1px 2px #e3e3e3; + box-shadow: 1px 1px 2px #e3e3e3; +} + +#tipue_search_content +{ + clear: left; + max-width: 650px; + padding: 25px 0 13px 0; + margin: 0; +} +#tipue_search_loading +{ + padding-top: 60px; + background: #fff url('img/loader.gif') no-repeat left; +} + +#tipue_search_warning_head +{ + font: 300 16px/1.6 'open sans', sans-serif; + color: #333; +} +#tipue_search_warning +{ + font: 12px/1.6 'open sans', sans-serif; + color: #333; + margin: 7px 0; +} +#tipue_search_warning a +{ + color: #3f72d8; + text-decoration: none; +} +#tipue_search_warning a:hover +{ + padding-bottom: 1px; + border-bottom: 1px solid #ccc; +} +#tipue_search_results_count +{ + font: 13px/1.6 'open sans', sans-serif; + color: #333; +} + +div.search_result { + background: #FFF; + margin-top: 5px; + margin-left: 255px; + + padding-top: 15px; + padding-left: 15px; + padding-right: 15px; + padding-bottom: 15px; + + border-radius: 15px; +} + + +.tipue_search_content_title +{ + font: 300 23px/1.6 'open sans', sans-serif; + margin-top: 31px; +/* + font-size: 16px; + color: #333; + margin-top: 27px; +*/ +} +.tipue_search_content_title a +{ +/* + color: #3f72d8; + text-decoration: none; +*/ + color: rgb(160, 70, 70); + text-decoration: none; +} +.tipue_search_content_title a:hover +{ + padding-bottom: 1px; + border-bottom: 1px solid #ccc; +/* + padding-bottom: 1px; + border-bottom: 1px solid #ccc; +*/ +} +.tipue_search_content_text +{ +/* + font: 12px/1.7 'open sans', sans-serif; + color: #333; + padding: 0px 10px; +*/ + font-size: 12px; + color: #555; + line-height: 21px; + padding: 0px 10px; + +} +.tipue_search_content_loc +{ + font: 300 13px/1.7 'open sans', sans-serif; + overflow: auto; + padding: 0px 10px; +} +.tipue_search_content_loc a +{ + text-decoration: none; + /* color: #555; */ + color: rgb(160,80,80); +} +.tipue_search_content_loc a:hover +{ + padding-bottom: 1px; + border-bottom: 1px solid #ccc; +} +#tipue_search_foot +{ + margin: 51px 0 21px 0; +} +#tipue_search_foot_boxes +{ + padding: 0; + margin: 0; + font: 12px/1 'open sans', sans-serif; +} +#tipue_search_foot_boxes li +{ + list-style: none; + margin: 0; + padding: 0; + display: inline; +} +#tipue_search_foot_boxes li a +{ + padding: 7px 13px 8px 13px; + background-color: #f1f1f1; + border: 1px solid #dcdcdc; + border-radius: 1px; + color: #333; + margin-right: 7px; + text-decoration: none; + text-align: center; +} +#tipue_search_foot_boxes li.current +{ + padding: 7px 13px 8px 13px; + background: #fff; + border: 1px solid #dcdcdc; + border-radius: 1px; + color: #333; + margin-right: 7px; + text-align: center; +} +#tipue_search_foot_boxes li a:hover +{ + border: 1px solid #ccc; + background-color: #f3f3f3; +} diff --git a/documentation/tipuesearch/tipuesearch.js b/documentation/tipuesearch/tipuesearch.js new file mode 100644 index 00000000..26e2edae --- /dev/null +++ b/documentation/tipuesearch/tipuesearch.js @@ -0,0 +1,388 @@ + +/* +Tipue Search 3.0 +Copyright (c) 2013 Tipue +Tipue Search is released under the MIT License +http://www.tipue.com/search +*/ + + +(function($) { + + $.fn.tipuesearch = function(options) { + + var set = $.extend( { + + 'show' : 7, + 'newWindow' : false, + 'showURL' : true, + 'minimumLength' : 3, + 'descriptiveWords' : 25, + 'highlightTerms' : true, + 'highlightEveryTerm' : false, + 'mode' : 'static', + 'liveDescription' : '*', + 'liveContent' : '*', + 'contentLocation' : 'tipuesearch/tipuesearch_content.json' + + }, options); + + return this.each(function() { + + var tipuesearch_in = { + pages: [] + }; + $.ajaxSetup({ + async: false + }); + + if (set.mode == 'live') + { + for (var i = 0; i < tipuesearch_pages.length; i++) + { + $.get(tipuesearch_pages[i], '', + function (html) + { + var cont = $(set.liveContent, html).text(); + cont = cont.replace(/\s+/g, ' '); + var desc = $(set.liveDescription, html).text(); + desc = desc.replace(/\s+/g, ' '); + + var t_1 = html.toLowerCase().indexOf(''); + var t_2 = html.toLowerCase().indexOf('', t_1 + 7); + if (t_1 != -1 && t_2 != -1) + { + var tit = html.slice(t_1 + 7, t_2); + } + else + { + var tit = 'No title'; + } + + tipuesearch_in.pages.push({ + "title": tit, + "text": desc, + "tags": cont, + "loc": tipuesearch_pages[i] + }); + } + ); + } + } + + if (set.mode == 'json') + { + $.getJSON(set.contentLocation, + function(json) + { + tipuesearch_in = $.extend({}, json); + } + ); + } + + if (set.mode == 'static') + { + tipuesearch_in = $.extend({}, tipuesearch); + } + + var tipue_search_w = ''; + if (set.newWindow) + { + tipue_search_w = ' target="_blank"'; + } + + function getURLP(name) + { + return decodeURIComponent((new RegExp('[?|&]' + name + '=' + '([^&;]+?)(&|#|;|$)').exec(location.search)||[,""])[1].replace(/\+/g, '%20')) || null; + } + if (getURLP('q')) + { + $('#tipue_search_input').val(getURLP('q')); + getTipueSearch(0, true); + } + + $('#tipue_search_button').click(function() + { + getTipueSearch(0, true); + }); + $(this).keyup(function(event) + { + if(event.keyCode == '13') + { + getTipueSearch(0, true); + } + }); + + function getTipueSearch(start, replace) + { + $('#tipue_search_content').hide(); + var out = ''; + var results = ''; + var show_replace = false; + var show_stop = false; + + var d = $('#tipue_search_input').val().toLowerCase(); + d = $.trim(d); + var d_w = d.split(' '); + d = ''; + for (var i = 0; i < d_w.length; i++) + { + var a_w = true; + for (var f = 0; f < tipuesearch_stop_words.length; f++) + { + if (d_w[i] == tipuesearch_stop_words[f]) + { + a_w = false; + show_stop = true; + } + } + if (a_w) + { + d = d + ' ' + d_w[i]; + } + } + d = $.trim(d); + d_w = d.split(' '); + + if (d.length >= set.minimumLength) + { + if (replace) + { + var d_r = d; + for (var i = 0; i < d_w.length; i++) + { + for (var f = 0; f < tipuesearch_replace.words.length; f++) + { + if (d_w[i] == tipuesearch_replace.words[f].word) + { + d = d.replace(d_w[i], tipuesearch_replace.words[f].replace_with); + show_replace = true; + } + } + } + d_w = d.split(' '); + } + + var d_t = d; + for (var i = 0; i < d_w.length; i++) + { + for (var f = 0; f < tipuesearch_stem.words.length; f++) + { + if (d_w[i] == tipuesearch_stem.words[f].word) + { + d_t = d_t + ' ' + tipuesearch_stem.words[f].stem; + } + } + } + d_w = d_t.split(' '); + + var c = 0; + found = new Array(); + for (var i = 0; i < tipuesearch_in.pages.length; i++) + { + var score = 1000000000; + var s_t = tipuesearch_in.pages[i].text; + for (var f = 0; f < d_w.length; f++) + { + var pat = new RegExp(d_w[f], 'i'); + if (tipuesearch_in.pages[i].title.search(pat) != -1) + { + score -= (200000 - i); + } + if (tipuesearch_in.pages[i].text.search(pat) != -1) + { + score -= (150000 - i); + } + + if (set.highlightTerms) + { + if (set.highlightEveryTerm) + { + var patr = new RegExp('(' + d_w[f] + ')', 'gi'); + } + else + { + var patr = new RegExp('(' + d_w[f] + ')', 'i'); + } + s_t = s_t.replace(patr, "$1"); + } + if (tipuesearch_in.pages[i].tags.search(pat) != -1) + { + score -= (100000 - i); + } + + } + if (score < 1000000000) + { + found[c++] = score + '^' + tipuesearch_in.pages[i].title + '^' + s_t + '^' + tipuesearch_in.pages[i].loc; + } + } + + if (c != 0) + { + if (show_replace == 1) + { + out += '
Showing results for ' + d + '
'; + out += '
Search for ' + d_r + '
'; + } + if (c == 1) + { + out += '
1 result
'; + } + else + { + c_c = c.toString().replace(/\B(?=(\d{3})+(?!\d))/g, ","); + out += '
' + c_c + ' results
'; + } + + found.sort(); + var l_o = 0; + for (var i = 0; i < found.length; i++) + { + var fo = found[i].split('^'); + if (l_o >= start && l_o < set.show + start) + { + out += '
' + fo[1] + '
'; + + var t = fo[2]; + var t_d = ''; + var t_w = t.split(' '); + if (t_w.length < set.descriptiveWords) + { + t_d = t; + } + else + { + for (var f = 0; f < set.descriptiveWords; f++) + { + t_d += t_w[f] + ' '; + } + } + t_d = $.trim(t_d); + if (t_d.charAt(t_d.length - 1) != '.') + { + t_d += ' ...'; + } + out += '
' + t_d + '
'; + + if (set.showURL) + { + t_url = fo[3]; + if (t_url.length > 45) + { + t_url = fo[3].substr(0, 45) + ' ...'; + } + out += '
' + t_url + '
'; + } + } + l_o++; + } + + if (c > set.show) + { + var pages = Math.ceil(c / set.show); + var page = (start / set.show); + out += '
    '; + + if (start > 0) + { + out += '
  • Prev
    • '; + } + + if (page <= 2) + { + var p_b = pages; + if (pages > 3) + { + p_b = 3; + } + for (var f = 0; f < p_b; f++) + { + if (f == page) + { + out += '
  • ' + (f + 1) + '
    • '; + } + else + { + out += '
  • ' + (f + 1) + '
    • '; + } + } + } + else + { + var p_b = pages + 2; + if (p_b > pages) + { + p_b = pages; + } + for (var f = page; f < p_b; f++) + { + if (f == page) + { + out += '
  • ' + (f + 1) + '
    • '; + } + else + { + out += '
  • ' + (f + 1) + '
    • '; + } + } + } + + if (page + 1 != pages) + { + out += '
  • Next
    • '; + } + + out += '
'; + } + } + else + { + out += '
Nothing found
'; + } + } + else + { + if (show_stop) + { + out += '
Nothing found
Common words are largely ignored
'; + } + else + { + out += '
Search too short
'; + if (set.minimumLength == 1) + { + out += '
Should be one character or more
'; + } + else + { + out += '
Should be ' + set.minimumLength + ' characters or more
'; + } + } + } + + $('#tipue_search_content').html(out); + $('#tipue_search_content').slideDown(200); + + $('#tipue_search_replaced').click(function() + { + getTipueSearch(0, false); + }); + + $('.tipue_search_foot_box').click(function() + { + var id_v = $(this).attr('id'); + var id_a = id_v.split('_'); + + getTipueSearch(parseInt(id_a[0]), id_a[1]); + }); + } + + }); + }; + +})(jQuery); + + + + diff --git a/documentation/tipuesearch/tipuesearch.min.js b/documentation/tipuesearch/tipuesearch.min.js new file mode 100644 index 00000000..582912ba --- /dev/null +++ b/documentation/tipuesearch/tipuesearch.min.js @@ -0,0 +1,12 @@ +(function($){$.fn.tipuesearch=function(options){var set=$.extend({"show":7,"newWindow":false,"showURL":true,"minimumLength":3,"descriptiveWords":25,"highlightTerms":true,"highlightEveryTerm":false,"mode":"static","liveDescription":"*","liveContent":"*","contentLocation":"tipuesearch/tipuesearch_content.json"},options);return this.each(function(){var tipuesearch_in={pages:[]};$.ajaxSetup({async:false});if(set.mode=="live")for(var i=0;i");var t_2=html.toLowerCase().indexOf("",t_1+7);if(t_1!=-1&&t_2!=-1)var tit=html.slice(t_1+7,t_2);else var tit="No title";tipuesearch_in.pages.push({"title":tit,"text":desc,"tags":cont,"loc":tipuesearch_pages[i]})});if(set.mode=="json")$.getJSON(set.contentLocation,function(json){tipuesearch_in=$.extend({},json)}); +if(set.mode=="static")tipuesearch_in=$.extend({},tipuesearch);var tipue_search_w="";if(set.newWindow)tipue_search_w=' target="_blank"';function getURLP(name){return decodeURIComponent(((new RegExp("[?|&]"+name+"="+"([^&;]+?)(&|#|;|$)")).exec(location.search)||[,""])[1].replace(/\+/g,"%20"))||null}if(getURLP("q")){$("#tipue_search_input").val(getURLP("q"));getTipueSearch(0,true)}$("#tipue_search_button").click(function(){getTipueSearch(0,true)});$(this).keyup(function(event){if(event.keyCode=="13")getTipueSearch(0, +true)});function getTipueSearch(start,replace){$("#tipue_search_content").hide();var out="";var results="";var show_replace=false;var show_stop=false;var d=$("#tipue_search_input").val().toLowerCase();d=$.trim(d);var d_w=d.split(" ");d="";for(var i=0;i=set.minimumLength){if(replace){var d_r=d;for(var i= +0;i$1")}if(tipuesearch_in.pages[i].tags.search(pat)!=-1)score-=1E5-i}if(score<1E9)found[c++]=score+"^"+tipuesearch_in.pages[i].title+"^"+s_t+"^"+tipuesearch_in.pages[i].loc}if(c!= +0){if(show_replace==1){out+='
Showing results for '+d+"
";out+='
Search for '+d_r+"
"}if(c==1)out+='
1 result
';else{c_c=c.toString().replace(/\B(?=(\d{3})+(?!\d))/g,",");out+='
'+c_c+" results
"}found.sort();var l_o=0;for(var i=0;i= +start&&l_o"+fo[1]+"";var t=fo[2];var t_d="";var t_w=t.split(" ");if(t_w.length";if(set.showURL){t_url=fo[3];if(t_url.length>45)t_url=fo[3].substr(0,45)+" ...";out+='
"+t_url+"
"}}l_o++}if(c>set.show){var pages=Math.ceil(c/set.show);var page=start/set.show;out+='
    ';if(start>0)out+='
  • Prev
    • ';if(page<=2){var p_b=pages;if(pages>3)p_b=3;for(var f=0;f'+(f+1)+"";else out+='
  • '+(f+1)+"
    • "}else{var p_b=pages+2;if(p_b>pages)p_b=pages;for(var f=page;f'+(f+1)+"";else out+='
  • '+(f+1)+"
    • "}if(page+1!=pages)out+='
  • Next
    • ';out+="
"}}else out+='
Nothing found
'}else if(show_stop)out+= +'
Nothing found
Common words are largely ignored
';else{out+='
Search too short
';if(set.minimumLength==1)out+='
Should be one character or more
';else out+='
Should be '+set.minimumLength+" characters or more
"}$("#tipue_search_content").html(out);$("#tipue_search_content").slideDown(200);$("#tipue_search_replaced").click(function(){getTipueSearch(0, +false)});$(".tipue_search_foot_box").click(function(){var id_v=$(this).attr("id");var id_a=id_v.split("_");getTipueSearch(parseInt(id_a[0]),id_a[1])})}})}})(jQuery); diff --git a/documentation/tipuesearch/tipuesearch_set.js b/documentation/tipuesearch/tipuesearch_set.js new file mode 100644 index 00000000..332dc171 --- /dev/null +++ b/documentation/tipuesearch/tipuesearch_set.js @@ -0,0 +1,23 @@ + +/* +Tipue Search 3.0 +Copyright (c) 2013 Tipue +Tipue Search is released under the MIT License +http://www.tipue.com/search +*/ + + +var tipuesearch_stop_words = ["and", "be", "by", "do", "for", "he", "how", "if", "is", "it", "my", "not", "of", "or", "the", "to", "up", "what", "when"]; + +var tipuesearch_replace = {"words": [ + {"word": "tipua", replace_with: "tipue"}, + {"word": "javscript", replace_with: "javascript"} +]}; + +var tipuesearch_stem = {"words": [ + {"word": "e-mail", stem: "email"}, + {"word": "javascript", stem: "script"}, + {"word": "javascript", stem: "js"} +]}; + + diff --git a/documentation/using_opensubdiv.rst b/documentation/using_opensubdiv.rst new file mode 100644 index 00000000..661d930a --- /dev/null +++ b/documentation/using_opensubdiv.rst @@ -0,0 +1,92 @@ +.. + Copyright (C) Pixar. All rights reserved. + + This license governs use of the accompanying software. If you + use the software, you accept this license. If you do not accept + the license, do not use the software. + + 1. Definitions + The terms "reproduce," "reproduction," "derivative works," and + "distribution" have the same meaning here as under U.S. + copyright law. A "contribution" is the original software, or + any additions or changes to the software. + A "contributor" is any person or entity that distributes its + contribution under this license. + "Licensed patents" are a contributor's patent claims that read + directly on its contribution. + + 2. Grant of Rights + (A) Copyright Grant- Subject to the terms of this license, + including the license conditions and limitations in section 3, + each contributor grants you a non-exclusive, worldwide, + royalty-free copyright license to reproduce its contribution, + prepare derivative works of its contribution, and distribute + its contribution or any derivative works that you create. + (B) Patent Grant- Subject to the terms of this license, + including the license conditions and limitations in section 3, + each contributor grants you a non-exclusive, worldwide, + royalty-free license under its licensed patents to make, have + made, use, sell, offer for sale, import, and/or otherwise + dispose of its contribution in the software or derivative works + of the contribution in the software. + + 3. Conditions and Limitations + (A) No Trademark License- This license does not grant you + rights to use any contributor's name, logo, or trademarks. + (B) If you bring a patent claim against any contributor over + patents that you claim are infringed by the software, your + patent license from such contributor to the software ends + automatically. + (C) If you distribute any portion of the software, you must + retain all copyright, patent, trademark, and attribution + notices that are present in the software. + (D) If you distribute any portion of the software in source + code form, you may do so only under this license by including a + complete copy of this license with your distribution. If you + distribute any portion of the software in compiled or object + code form, you may only do so under a license that complies + with this license. + (E) The software is licensed "as-is." You bear the risk of + using it. The contributors give no express warranties, + guarantees or conditions. You may have additional consumer + rights under your local laws which this license cannot change. + To the extent permitted under your local laws, the contributors + exclude the implied warranties of merchantability, fitness for + a particular purpose and non-infringement. + + +Using OpenSubdiv +---------------- + +.. contents:: + :local: + :backlinks: none + + +Compiling & Linking +=================== + +Here are example commands for building an OpenSubdiv application on several architectures: + +**Linux** +:: + + g++ -I$OPENSUBDIV/include -c myapp.cpp + g++ myapp.o -L$OPENSUBDIV/lib -losdCPU -losdGPU -o myapp + +**Mac OS-X** +:: + + g++ -I$OPENSUBDIV/include -c myapp.cpp + g++ myapp.o -L$OPENSUBDIV/lib -losdCPU -losdGPU -o myapp + install_name_tool -add_rpath $OPENSUBDIV/lib myapp + +(On 64-bit OS-X: add ``-m64`` after each ``g++``.) + +**Windows** +:: + + cl /nologo /MT /TP /DWIN32 /I"%OPENSUBDIV%\include" -c myapp.cpp + link /nologo /out:myapp.exe /LIBPATH:"%OPENSUBDIV%\lib" libosdCPU.lib libosdGPU.lib myapp.obj + +