.. Copyright 2013 Pixar Licensed under the Apache License, Version 2.0 (the "Apache License") with the following modification; you may not use this file except in compliance with the Apache License and the following modification to it: Section 6. Trademarks. is deleted and replaced with: 6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor and its affiliates, except as required to comply with Section 4(c) of the License and to reproduce the content of the NOTICE file. You may obtain a copy of the Apache License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the Apache License with the above modification is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the Apache License for the specific language governing permissions and limitations under the Apache License. Getting Started --------------- .. contents:: :local: :backlinks: none 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 bug 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. .. image:: images/git_flow.png :align: center :target: images/git_flow.png 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 checkout 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. External code should be submitted by sending Git `pull-requests `__ from forks of our *dev* branch. ---- Code Overview ============= The OpenSubdiv code base contains the following main areas: +----------------------+---------------------------------------------------------------------------------------+ | Directory | Contents | +======================+=======================================================================================+ | **./opensubdiv/** | The main subdivision APIs : Sdc, Vtr, Far and Osd. | +----------------------+---------------------------------------------------------------------------------------+ | **./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. | +----------------------+---------------------------------------------------------------------------------------+ | **./tutorials/** | Tutorials showing how to manipulate the APIs of OpenSubdiv. | +----------------------+---------------------------------------------------------------------------------------+ | **./documentation/** | The reStructuredText source files along with python scripts that generate the HTML | | | documentation site. | +----------------------+---------------------------------------------------------------------------------------+ | **./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. | +----------------------+---------------------------------------------------------------------------------------+