HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
stitchClips.h
Go to the documentation of this file.
1 //
2 // Copyright 2016 Pixar
3 //
4 // Licensed under the Apache License, Version 2.0 (the "Apache License")
5 // with the following modification; you may not use this file except in
6 // compliance with the Apache License and the following modification to it:
7 // Section 6. Trademarks. is deleted and replaced with:
8 //
9 // 6. Trademarks. This License does not grant permission to use the trade
10 // names, trademarks, service marks, or product names of the Licensor
11 // and its affiliates, except as required to comply with Section 4(c) of
12 // the License and to reproduce the content of the NOTICE file.
13 //
14 // You may obtain a copy of the Apache License at
15 //
16 // http://www.apache.org/licenses/LICENSE-2.0
17 //
18 // Unless required by applicable law or agreed to in writing, software
19 // distributed under the Apache License with the above modification is
20 // distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
21 // KIND, either express or implied. See the Apache License for the specific
22 // language governing permissions and limitations under the Apache License.
23 //
24 #ifndef PXR_USD_USD_UTILS_STITCH_CLIPS_H
25 #define PXR_USD_USD_UTILS_STITCH_CLIPS_H
26 
27 /// \file usdUtils/stitchClips.h
28 ///
29 /// Collection of utilities for sequencing multiple layers each holding
30 /// sequential time-varying data into
31 /// \ref Usd_Page_ValueClips "USD Value Clips".
32 
33 #include "pxr/pxr.h"
34 #include "pxr/usd/usdUtils/api.h"
35 #include "pxr/usd/usd/clipsAPI.h"
37 #include "pxr/usd/sdf/path.h"
38 
39 #include <limits>
40 
42 
44 
45 /// A function that creates layers that use
46 /// \ref Usd_Page_ValueClips "USD Value Clips"
47 /// to effectively merge the time samples in the given \p clipLayers under \p
48 /// clipPath without copying the samples into a separate layer.
49 ///
50 /// \p resultLayer The layer to which clip metadata and frame data
51 /// will be written. The layer representing the static
52 /// scene topology will be authored as a sublayer on
53 /// this layer as well; it will be authored as the
54 /// first sublayer in the list(strongest).
55 ///
56 /// \p clipLayerFiles The files containing the time varying data.
57 ///
58 /// \p clipPath The path at which we will put the clip metadata.
59 ///
60 /// \p startTimeCode The first time coordinate for the rootLayer
61 /// to point to. If none is provided, it will be
62 /// the lowest startTimeCode available from
63 /// the \p clipLayers.
64 ///
65 /// \p endTimeCode The last time coordinate for the rootLayer to
66 /// point to. If none is provided, it will be the
67 /// highest endTimeCode authored from the
68 /// \p clipLayers.
69 ///
70 /// \p interpolateMissingClipValues
71 /// Whether values for clips without samples are
72 /// interpolated from surrounding clips. See
73 /// UsdClipsAPI::GetInterpolateMissingClipValues
74 /// for more details.
75 ///
76 /// \p clipSet The name of the clipSet in which the
77 /// aforementioned metadata will be authored.
78 /// \note If this parameter is omitted, the default
79 /// clipSet name will be authored.
80 ///
81 /// Details on how this is accomplished can be found below:
82 ///
83 /// Pre-existing opinions will be wiped away upon success. Upon failure, the
84 /// original topology and manifest layers, if pre-existing, will be preserved.
85 /// These layers will be named/looked up via the following scheme:
86 ///
87 /// topologyLayerName = <resultIdWithoutExt>.topology.<resultExt>
88 /// manifestLayerName = <resultIdWithoutExt>.manifest.<resultExt>
89 ///
90 /// For example: if the resultLayerFile's name is foo.usd the expected topology
91 /// layer will be foo.topology.usd and the expected manifest layer will be
92 /// foo.manifest.usd.
93 ///
94 /// The topology layer contains the aggregated topology of the set of
95 /// \p clipLayers. This process will merge prims and properties, save for time
96 /// varying properties, those will be accessed from the original
97 /// clip files.
98 ///
99 /// The aggregation of topology works by merging a clipLayer at a time with
100 /// the topologyLayer. If a prim already exists in the topologyLayer, its
101 /// attributes will be merged.
102 ///
103 /// For example, if we have a layer, clipA with attributes /World/fx/foo.bar
104 /// and a second layer with /World/fx/foo.baz. Our aggregate topology layer
105 /// will contain both /World/fx/foo.bar, /World/fx/foo.baz.
106 ///
107 /// The manifest layer contains declarations for all attributes that exist
108 /// under \p clipPath and descendants in the clip layers with authored time
109 /// samples. Any default values authored into the topology layer for these
110 /// time sampled attributes will also be authored into the manifest.
111 ///
112 /// The \p resultLayer will contain clip metadata at the specified \p clipPath.
113 /// The resultLayer will also have timeCode range data, such as start and end
114 /// timeCodes written to it, with the starting position being provided by
115 /// \p startTimeCode and the ending provided by \p endTimeCode.
116 ///
117 /// Note: an invalid clip path(because the prim doesn't exist in
118 /// the aggregate topologyLayer) will result in a TF_CODING_ERROR.
119 ///
121 bool
122 UsdUtilsStitchClips(const SdfLayerHandle& resultLayer,
123  const std::vector<std::string>& clipLayerFiles,
124  const SdfPath& clipPath,
125  const double startTimeCode
127  const double endTimeCode
129  const bool interpolateMissingClipValues
130  = false,
131  const TfToken& clipSet
132  = UsdClipsAPISetNames->default_);
133 
134 /// A function which aggregates the topology of a set of \p clipLayerFiles
135 /// for use in USD's Value Clips system. This aggregated scene topology
136 /// will only include non-time-varying data, as it is for use in conjunction
137 /// with the value clip metadata in a manifest layer.
138 ///
139 /// \p topologyLayer The layer in which topology of the
140 /// \p clipLayerFiles will be aggregated and inserted.
141 ///
142 /// \p clipLayerFiles The files containing the time varying data.
143 ///
145 bool
146 UsdUtilsStitchClipsTopology(const SdfLayerHandle& topologyLayer,
147  const std::vector<std::string>& clipLayerFiles);
148 
149 /// A function which creates a clip manifest from the set of \p clipLayerFiles
150 /// for use in USD's Value Clips system. This manifest will contain
151 /// declarations for attributes with authored time samples in the clip layers.
152 /// If a time sampled attribute has a default value authored in the given
153 /// \p topologyLayer, that value will also be authored as its default in the
154 /// manifest.
155 ///
156 /// \p manifestLayer The layer where manifest data will be inserted.
157 ///
158 /// \p topologyLayer The topology layer for \p clipLayerFiles.
159 ///
160 /// \p clipLayerFiles The files containing the time varying data.
161 ///
162 /// \p clipPrimPath The manifest will contain attributes from this
163 /// prim and its descendants in \p clipLayerFiles.
165 bool
166 UsdUtilsStitchClipsManifest(const SdfLayerHandle& manifestLayer,
167  const SdfLayerHandle& topologyLayer,
168  const std::vector<std::string>& clipLayerFiles,
169  const SdfPath& clipPath);
170 
171 /// A function which authors clip template metadata on a particular prim in a
172 /// result layer, as well as adding the topologyLayer to the list of subLayers
173 /// on the \p resultLayer. It will clear the \p resultLayer and create
174 /// a prim at \p clipPath. Specifically, this will author clipPrimPath,
175 /// clipTemplateAssetPath, clipTemplateStride, clipTemplateStartTime,
176 /// clipTemplateEndTime, and clipManifestAssetPath.
177 ///
178 /// \p resultLayer The layer in which we will author the metadata.
179 ///
180 /// \p topologyLayer The layer containing the aggregate topology of
181 /// the clipLayers which the metadata refers to.
182 ///
183 /// \p manifestLayer The layer containing manifest for the attributes
184 /// in the clipLayers.
185 ///
186 /// \p clipPath The path at which to author the metadata in
187 /// \p resultLayer
188 ///
189 /// \p templatePath The template string to be authored at the
190 /// clipTemplateAssetPath metadata key.
191 ///
192 /// \p startTime The start time to be authored at the
193 /// clipTemplateStartTime metadata key.
194 ///
195 /// \p endTime The end time to be authored at the
196 /// clipTemplateEndTime metadata key.
197 ///
198 /// \p stride The stride to be authored at the
199 /// clipTemplateStride metadata key.
200 ///
201 /// \p activeOffset The offset to be authored at the
202 /// clipTemplateActiveOffset metadata key.
203 /// \note If this parameter is omitted, no value
204 /// will be authored as the metadata is optional.
205 ///
206 /// \p interpolateMissingClipValues
207 /// Whether values for clips without samples are
208 /// interpolated from surrounding clips. See
209 /// UsdClipsAPI::GetInterpolateMissingClipValues
210 /// for more details.
211 ///
212 /// \p clipSet The name of the clipSet in which the
213 /// aforementioned metadata will be authored.
214 /// \note If this parameter is omitted, the default
215 /// clipSet name("default") will be authored.
216 ///
217 /// For further information on these metadatum, see \ref Usd_Page_AdvancedFeatures
218 ///
220 bool
221 UsdUtilsStitchClipsTemplate(const SdfLayerHandle& resultLayer,
222  const SdfLayerHandle& topologyLayer,
223  const SdfLayerHandle& manifestLayer,
224  const SdfPath& clipPath,
225  const std::string& templatePath,
226  const double startTime,
227  const double endTime,
228  const double stride,
229  const double activeOffset
231  const bool interpolateMissingClipValues
232  = false,
233  const TfToken& clipSet
234  = UsdClipsAPISetNames->default_);
235 
236 /// Generates a topology file name based on an input file name
237 ///
238 /// For example, if given 'foo.usd', it generates 'foo.topology.usd'
239 ///
240 /// Note: this will not strip preceding paths off of a file name
241 /// so /bar/baz/foo.usd will produce /bar/baz/foo.topology.usd
242 ///
243 /// \p rootLayerName The filepath used as a basis for generating
244 /// our topology layer name.
247 UsdUtilsGenerateClipTopologyName(const std::string& rootLayerName);
248 
249 /// Generates a manifest file name based on an input file name
250 ///
251 /// For example, if given 'foo.usd', it generates 'foo.manifest.usd'
252 ///
253 /// Note: this will not strip preceding paths off of a file name
254 /// so /bar/baz/foo.usd will produce /bar/baz/foo.manifest.usd
255 ///
256 /// \p rootLayerName The filepath used as a basis for generating
257 /// our manifest layer name.
260 UsdUtilsGenerateClipManifestName(const std::string& rootLayerName);
261 
263 
264 #endif /* PXR_USD_USD_UTILS_STITCH_CLIPS_H */
USDUTILS_API bool UsdUtilsStitchClipsManifest(const SdfLayerHandle &manifestLayer, const SdfLayerHandle &topologyLayer, const std::vector< std::string > &clipLayerFiles, const SdfPath &clipPath)
USDUTILS_API bool UsdUtilsStitchClips(const SdfLayerHandle &resultLayer, const std::vector< std::string > &clipLayerFiles, const SdfPath &clipPath, const double startTimeCode=std::numeric_limits< double >::max(), const double endTimeCode=std::numeric_limits< double >::max(), const bool interpolateMissingClipValues=false, const TfToken &clipSet=UsdClipsAPISetNames->default_)
Definition: layer.h:94
GLsizei const GLchar *const * string
Definition: glcorearb.h:814
USDUTILS_API bool UsdUtilsStitchClipsTopology(const SdfLayerHandle &topologyLayer, const std::vector< std::string > &clipLayerFiles)
Definition: token.h:87
USDUTILS_API std::string UsdUtilsGenerateClipTopologyName(const std::string &rootLayerName)
GLint GLenum GLboolean GLsizei stride
Definition: glcorearb.h:872
Definition: path.h:291
USDUTILS_API bool UsdUtilsStitchClipsTemplate(const SdfLayerHandle &resultLayer, const SdfLayerHandle &topologyLayer, const SdfLayerHandle &manifestLayer, const SdfPath &clipPath, const std::string &templatePath, const double startTime, const double endTime, const double stride, const double activeOffset=std::numeric_limits< double >::max(), const bool interpolateMissingClipValues=false, const TfToken &clipSet=UsdClipsAPISetNames->default_)
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1441
ImageBuf OIIO_API max(Image_or_Const A, Image_or_Const B, ROI roi={}, int nthreads=0)
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:91
PXR_NAMESPACE_OPEN_SCOPE SDF_DECLARE_HANDLES(SdfLayer)
#define USDUTILS_API
Definition: api.h:40
USDUTILS_API std::string UsdUtilsGenerateClipManifestName(const std::string &rootLayerName)