1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
|
..
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 <https://help.github.com/articles/set-up-git>`__.
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 <https://github.com/PixarAnimationStudios/OpenSubdiv/archive/release.zip>`__
- Using a GUI client : you can find a list `here <http://git-scm.com/downloads/guis>`__
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 <intro.html#contributing>`__.
----
Branches & Git Flow
===================
Since version 1.1.0, OpenSubdiv has adopted the `Git Flow
<http://nvie.com/posts/a-successful-git-branching-model/>`__ 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 'release' 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 <https://github.com/nvie/gitflow>`__ 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 'release' 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
release
API Versions
____________
OpenSubdiv maintains an internal API versioning system. The version number can be
read from the file `./opensubdiv/version.h <https://github.com/PixarAnimationStudios/OpenSubdiv/blob/release/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 repository is currently limited to a
small internal development team. External code should be submitted by sending Git
`pull-requests <https://help.github.com/articles/using-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. |
+----------------------+---------------------------------------------------------------------------------------+
|
