mirror of
https://github.com/PixarAnimationStudios/OpenSubdiv
synced 2024-11-22 11:40:08 +00:00
update README.md
remove old info and add links to documents. add travis badges cleanup lib dependency info
This commit is contained in:
Takahito Tejima
parent
1a88662a58
commit
33902260fd
211
README.md
211
README.md
@ -8,107 +8,136 @@ Feel free to use it and let us know what you think.
|
||||
|
||||
For more details about OpenSubdiv, see [Pixar Graphics Technologies](http://graphics.pixar.com).
|
||||
|
||||
## Git Flow
|
||||
* master : [](https://travis-ci.org/PixarAnimationStudios/OpenSubdiv)
|
||||
|
||||
We have adopted the git flow branching model. It is not necessary to use the git-flow extensions, though you may find them useful! But it will be helpful to read about the git flow branching model in order to understand the organization of branches and tags that you will find in the repository.
|
||||
* dev : [](https://travis-ci.org/PixarAnimationStudios/OpenSubdiv)
|
||||
|
||||
* [Getting Started](http://graphics.pixar.com/opensubdiv/docs/getting_started.html)
|
||||
* [git-flow extensions](https://github.com/nvie/gitflow)
|
||||
## Documents
|
||||
* [User Documents] (http://graphics.pixar.com/opensubdiv/docs/intro.html)
|
||||
* [Doxygen API Documents] (http://graphics.pixar.com/opensubdiv/docs/doxy_html/index.html)
|
||||
* [Release Notes] (http://graphics.pixar.com/opensubdiv/docs/release_notes.html)
|
||||
|
||||
## Quickstart
|
||||
## Forum
|
||||
* [OpenSubdiv Google Groups] (https://groups.google.com/forum/embed/?place=forum/opensubdiv)
|
||||
|
||||
* Clone
|
||||
* Make a subdirectory "build" and cd into it
|
||||
* Run cmake .. followed up with your build tool of choice (make or an IDE).
|
||||
## Prerequisite
|
||||
For complete information, please refer OpenSubdiv documents:
|
||||
[Building with CMake] (http://graphics.pixar.com/opensubdiv/docs/cmake_build.html)
|
||||
|
||||
Additional detailed instructions can be found in the documentation:
|
||||
* General requirements:
|
||||
|
||||
* [Getting Started](http://graphics.pixar.com/opensubdiv/docs/getting_started.html)
|
||||
* [Building OpenSubdiv](http://graphics.pixar.com/opensubdiv/docs/cmake_build.html)
|
||||
| Lib (URL) | Min Version | Note |
|
||||
| ------------------------------------- | ----------- | ---------- |
|
||||
| CMake <br> http://www.cmake.org | 2.8.6 | *Required* |
|
||||
|
||||
## Standalone viewers
|
||||
* Osd optional requirements:
|
||||
|
||||
OpenSubdiv builds a number of standalone viewers that demonstrate various aspects of the software.
|
||||
| Lib (URL) | Min Version | Note |
|
||||
| ---------------------------------------------------- | -------------- | -------------- |
|
||||
| GLEW <br> http://glew.sourceforge.net | 1.9.0 | GL backend (Win/Linux only) |
|
||||
| CUDA <br> http://developer.nvidia.com/cuda-toolkit | 4.0 | cuda backend |
|
||||
| TBB <br> https://www.threadingbuildingblocks.org | 4.0 | TBB backend |
|
||||
| OpenCL <br> http://www.khronos.org/opencl | 1.1 | CL backend |
|
||||
| DX11 SDK <br> http://www.microsoft.com/download/details.aspx?id=6812| | DX backend |
|
||||
|
||||
__Common Keyboard Shortcuts:__
|
||||
* Examples/Documents optional requirements:
|
||||
|
||||
| Lib (URL) | Min Version | Note |
|
||||
| --------------------------------------------- | ----------- | ------------------- |
|
||||
| GLFW <br> http://www.glfw.org | 3.0.0 | GL examples |
|
||||
| Maya SDK <br> http://www.autodesk.com/maya | 2013 | maya plugin example |
|
||||
| Ptex <br> https://github.com/wdas/ptex | 2.0 | ptex viewers |
|
||||
| Zlib <br> http://www.zlib.net | | (required for Ptex under windows)|
|
||||
| Docutils <br> http://docutils.sourceforge.net | | documents |
|
||||
| Doxygen <br>http://www.doxygen.org | | documents |
|
||||
|
||||
|
||||
## Build example to run glViewer and other example programs with minimal dependency
|
||||
|
||||
### All platforms:
|
||||
|
||||
* Install cmake, GLFW and GLEW (GLEW is not required on OSX)
|
||||
|
||||
make sure GLEW and GLFW install directories configured as follows:
|
||||
|
||||
```
|
||||
${GLEW_LOCATION}/include/GL/glew.h
|
||||
${GLEW_LOCATION}/lib/libGLEW.a (linux)
|
||||
${GLEW_LOCATION}/lib/glew32.lib (windows)
|
||||
|
||||
${GLFW_LOCATION}/include/glfw3.h
|
||||
${GLFW_LOCATION}/lib/libglfw3.a (linux)
|
||||
${GLFW_LOCATION}/lib/glfw3.lib (windows)
|
||||
```
|
||||
|
||||
* Clone OpenSubdiv repository, and create a build directory.
|
||||
```
|
||||
git clone https://github.com/PixarAnimationStudios/OpenSubdiv
|
||||
mkdir build
|
||||
cd build
|
||||
```
|
||||
|
||||
### Windows (Visual Studio)
|
||||
|
||||
* run cmake:
|
||||
```
|
||||
"c:/Program Files (x86)/CMake/bin/cmake.exe" ^
|
||||
-G "Visual Studio 12 Win64" ^
|
||||
-D NO_MAYA=1 -D NO_PTEX=1 -D NO_DOC=1 ^
|
||||
-D NO_OMP=1 -D NO_TBB=1 -D NO_CUDA=1 -D NO_OPENCL=1 -D NO_CLEW=1 ^
|
||||
-D "GLEW_LOCATION=*YOUR GLEW INSTALL LOCATION*" ^
|
||||
-D "GLFW_LOCATION=*YOUR GLFW INSTALL LOCATION*" ^
|
||||
..
|
||||
```
|
||||
* Open OpenSubdiv.sln in VisualStudio and build.
|
||||
|
||||
### Linux
|
||||
|
||||
```
|
||||
cmake -D NO_MAYA=1 -D NO_PTEX=1 -D NO_DOC=1 \
|
||||
-D NO_OMP=1 -D NO_TBB=1 -D NO_CUDA=1 -D NO_OPENCL=1 -D NO_CLEW=1 \
|
||||
-D GLEW_LOCATION="*YOUR GLEW INSTALL LOCATION*" \
|
||||
-D GLFW_LOCATION="*YOUR GLFW INSTALL LOCATION*" \
|
||||
..
|
||||
make
|
||||
```
|
||||
|
||||
### OSX
|
||||
|
||||
```
|
||||
cmake -D NO_MAYA=1 -D NO_PTEX=1 -D NO_DOC=1 \
|
||||
-D NO_OMP=1 -D NO_TBB=1 -D NO_CUDA=1 -D NO_OPENCL=1 -D NO_CLEW=1 \
|
||||
-D GLFW_LOCATION="*YOUR GLFW INSTALL LOCATION*" \
|
||||
..
|
||||
make
|
||||
```
|
||||
|
||||
### Useful cmake options and environment variables
|
||||
|
||||
````
|
||||
Left mouse button drag : orbit camera
|
||||
Middle mouse button drag : pan camera
|
||||
Right mouse button : dolly camera
|
||||
n, p : next/prev model
|
||||
1, 2, 3, 4, 5, 6, 7 : specify adaptive isolation or uniform refinment level
|
||||
+, - : increase / decrease tessellation
|
||||
w : switch display mode
|
||||
q : quit
|
||||
-DCMAKE_BUILD_TYPE=[Debug|Release]
|
||||
|
||||
-DCMAKE_INSTALL_PREFIX=[base path to install OpenSubdiv]
|
||||
-DCMAKE_LIBDIR_BASE=[library directory basename (default: lib)]
|
||||
|
||||
-DCUDA_TOOLKIT_ROOT_DIR=[path to CUDA Toolkit]
|
||||
-DPTEX_LOCATION=[path to Ptex]
|
||||
-DGLEW_LOCATION=[path to GLEW]
|
||||
-DGLFW_LOCATION=[path to GLFW]
|
||||
-DMAYA_LOCATION=[path to Maya]
|
||||
|
||||
-DNO_LIB=1 // disable the opensubdiv libs build (caveat emptor)
|
||||
-DNO_EXAMPLES=1 // disable examples build
|
||||
-DNO_TUTORIALS=1 // disable tutorials build
|
||||
-DNO_REGRESSION=1 // disable regression tests build
|
||||
-DNO_MAYA=1 // disable Maya plugin build
|
||||
-DNO_PTEX=1 // disable PTex support
|
||||
-DNO_DOC=1 // disable documentation build
|
||||
-DNO_OMP=1 // disable OpenMP
|
||||
-DNO_TBB=1 // disable TBB
|
||||
-DNO_CUDA=1 // disable CUDA
|
||||
-DNO_OPENCL=1 // disable OpenCL
|
||||
-DNO_OPENGL=1 // disable OpenGL
|
||||
-DNO_CLEW=1 // disable CLEW wrapper library
|
||||
````
|
||||
|
||||
## Build instructions (iOS/Android)
|
||||
|
||||
OpenSubdiv may also be used for mobile app development.
|
||||
|
||||
Support for the CPU and GPU APIs used by OpenSubdiv is more limited on today's mobile operating systems. For example, the most widely support graphics API is OpenGL ES 2.0 which doesn't yet provide the support for tessellation shaders needed to fully implement GPU accellerated Feature Adaptive Subdivision.
|
||||
|
||||
OpenSubdiv can still be used to compute uniform refinement of subdivision surfaces for display on these platforms, realizing all of the benefits of a consistent interpretation of subdivision schemes and tags.
|
||||
|
||||
The easiest way to get started using OpenSubdiv for mobile is to use CMake's support for cross-compiling:
|
||||
|
||||
* [CMake Cross Compiling](http://www.cmake.org/Wiki/CMake_Cross_Compiling)
|
||||
|
||||
### iOS
|
||||
|
||||
You will need a current version of Apple's Xcode and iOS SDK (tested with iOS 6.0.1 and Xcode 4.5.2):
|
||||
|
||||
* [Xcode](https://developer.apple.com/xcode/)
|
||||
|
||||
and a CMake toolchain for iOS:
|
||||
|
||||
* [iOS CMake](https://code.google.com/p/ios-cmake/)
|
||||
|
||||
You can then use CMake to configure and generate an Xcode project:
|
||||
|
||||
````
|
||||
mkdir build-ios
|
||||
cd build-ios
|
||||
cmake -DNO_CUDA=1 -DCMAKE_TOOLCHAIN_FILE=[path to iOS.cmake] -GXcode ..
|
||||
|
||||
xcodebuild -target install -configuration Debug
|
||||
````
|
||||
|
||||
You can open the resulting Xcode project directly, or include as a sub-project in the Xcode project for your app.
|
||||
|
||||
### Android NDK
|
||||
|
||||
You will need a current version of the Android NDK (tested with Android 4.2.1 and android-ndk-r8b):
|
||||
|
||||
* [Android NDK](http://developer.android.com/tools/sdk/ndk/index.html)
|
||||
|
||||
and a CMake toolchain for Android:
|
||||
|
||||
* [Android CMake](https://code.google.com/p/android-cmake/)
|
||||
|
||||
You can then use CMake to configure and build OpenSubdiv:
|
||||
|
||||
````
|
||||
mkdir build-ndk
|
||||
cd build-ndk
|
||||
cmake -DCMAKE_TOOLCHAIN_FILE=[path to android.cmake] -DLIBRARY_OUTPUT_PATH_ROOT=`pwd`/modules/OpenSubdiv ..
|
||||
|
||||
make install
|
||||
````
|
||||
|
||||
The resulting NDK module can be imported by other NDK modules by including it in your module search path:
|
||||
|
||||
````
|
||||
export NDK_MODULE_PATH=[path to build-ndk/modules]
|
||||
````
|
||||
|
||||
|
||||
## Regression tests
|
||||
|
||||
OpenSubdiv builds a number of regression test executables for testing:
|
||||
|
||||
* hbr_regression: Regression testing matching HBR (low-level hierarchical boundary rep) to a pre-generated data set.
|
||||
* far_regression: Matching FAR (feature-adaptive rep using tables) against HBR results.
|
||||
* osd_regression: Matching full OSD subdivision against HBR results. Currently checks single threaded CPU kernel only.
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user