HDK
Main Page
Related Pages
Modules
Namespaces
Classes
Files
Examples
File List
File Members
All
Classes
Namespaces
Files
Functions
Variables
Typedefs
Enumerations
Enumerator
Friends
Macros
Groups
Pages
stageCacheContext.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_STAGE_CACHE_CONTEXT_H
25
#define PXR_USD_USD_STAGE_CACHE_CONTEXT_H
26
27
#include "
pxr/pxr.h
"
28
#include "
pxr/usd/usd/api.h
"
29
#include "
pxr/base/tf/stacked.h
"
30
31
#include <vector>
32
33
PXR_NAMESPACE_OPEN_SCOPE
34
35
36
class
UsdStageCache
;
37
38
// Private helper wrapper class, holds a const reference to a stage cache.
39
struct
Usd_NonPopulatingStageCacheWrapper
{
40
explicit
Usd_NonPopulatingStageCacheWrapper
(
const
UsdStageCache
&
cache
)
41
: cache(cache) {}
42
const
UsdStageCache
&
cache
;
43
};
44
45
// Using a template arg for 'cache' in UsdUseButDoNotPopulateCache enforces
46
// lvalue requirement: rvalues will not bind to function template non-const
47
// reference parameters.
48
49
/// Indicate that a UsdStageCacheContext should be bound in a read-only fashion.
50
/// Calls to UsdStage::Open() will attempt to find stages in \p cache when a
51
/// UsdStageCacheContext is present on the stack. See UsdStageCacheContext for
52
/// more details and example use.
53
template
<
class
StageCache>
54
Usd_NonPopulatingStageCacheWrapper
55
UsdUseButDoNotPopulateCache
(StageCache &cache) {
56
return
Usd_NonPopulatingStageCacheWrapper
(cache);
57
}
58
59
enum
UsdStageCacheContextBlockType
60
{
61
/// Indicate that a UsdStageCacheContext should ignore all currently bound
62
/// UsdStageCacheContexts, preventing reading from or writing to their
63
/// UsdStageCaches. See UsdStageCache for more details and example use.
64
UsdBlockStageCaches
,
65
/// Indicate that a UsdStageCacheContext should ignore all currently bound
66
/// writable UsdStageCacheContexts, writing to their UsdStageCaches. See
67
/// UsdStageCache for more details and example use.
68
UsdBlockStageCachePopulation
,
69
70
Usd_NoBlock
71
};
72
73
/// \class UsdStageCacheContext
74
///
75
/// A context object that lets the UsdStage::Open() API read from or read
76
/// from and write to a UsdStageCache instance during a scope of execution.
77
///
78
/// Code examples illustrate typical use:
79
/// \code
80
/// {
81
/// // A stage cache to work with.
82
/// UsdStageCache stageCache;
83
///
84
/// // Bind this cache. UsdStage::Open() will attempt to find a matching
85
/// // stage in the cache. If none is found, it will open a new stage and
86
/// // insert it into the cache.
87
/// UsdStageCacheContext context(stageCache);
88
///
89
/// // Since the cache is currently empty, this Open call will not find an
90
/// // existing stage in the cache, but will insert the newly opened stage
91
/// // in it.
92
/// auto stage = UsdStage::Open(<args>);
93
///
94
/// assert(stageCache.Contains(stage));
95
///
96
/// // A subsequent Open() call with the same arguments will retrieve the
97
/// // stage from cache.
98
/// auto stage2 = UsdStage::Open(<args>);
99
/// assert(stage2 == stage);
100
/// }
101
/// \endcode
102
///
103
/// The UsdStage::Open() API examines caches in UsdStageCacheContexts that exist
104
/// on the stack in the current thread in order starting with the most recently
105
/// created (deepest in the stack) to the least recently created.
106
///
107
/// The UsdUseButDoNotPopulateCache() function makes a cache available for
108
/// UsdStage::Open() to find stages in, but newly opened stages will not be
109
/// published to it. This can be useful if you want to make use of a cache but
110
/// cannot or do not wish to mutate that cache.
111
///
112
/// Passing UsdBlockStageCaches disables cache use entirely (as if no
113
/// UsdStageCacheContexts exist on the stack), while
114
/// UsdBlockStageCachePopulation disables writing to all bound caches (as if
115
/// they were all established with UsdUseButDoNotPopulateCache()).
116
///
117
/// Threading note: Different threads have different call stacks, so
118
/// UsdStageCacheContext objects that exist in one thread's stack do not
119
/// influence calls to UsdStage::Open() from a different thread.
120
///
121
TF_DEFINE_STACKED
(
UsdStageCacheContext
,
true
,
USD_API
)
122
{
123
public
:
124
/// Bind a cache for calls to UsdStage::Open() to read from and write to.
125
explicit
UsdStageCacheContext
(
UsdStageCache
&cache)
126
: _rwCache(&cache)
127
, _isReadOnlyCache(
false
)
128
, _blockType(
Usd_NoBlock
) {}
129
130
/// Bind a cache for calls to UsdStage::Open() to read from.
131
/// \see UsdUseButDoNotPopulateCache()
132
explicit
UsdStageCacheContext
(
Usd_NonPopulatingStageCacheWrapper
holder)
133
: _roCache(&holder.
cache
)
134
, _isReadOnlyCache(
true
)
135
, _blockType(
Usd_NoBlock
) {}
136
137
/// Disable cache use completely (with UsdBlockStageCaches) or only
138
/// for writing (with UsdBlockStageCacheWrites).
139
explicit
UsdStageCacheContext
(
UsdStageCacheContextBlockType
blockType)
140
: _blockType(blockType) {}
141
142
private
:
143
friend
class
UsdStage
;
144
145
static
std::vector<const UsdStageCache *> _GetReadOnlyCaches();
146
static
std::vector<const UsdStageCache *> _GetReadableCaches();
147
static
std::vector<UsdStageCache *> _GetWritableCaches();
148
149
// A blocking context is encoded with both members variables null.
150
union
{
151
UsdStageCache
*_rwCache;
152
const
UsdStageCache
*_roCache;
153
};
154
bool
_isReadOnlyCache;
155
UsdStageCacheContextBlockType
_blockType;
156
};
157
158
159
PXR_NAMESPACE_CLOSE_SCOPE
160
161
#endif // PXR_USD_USD_STAGE_CACHE_CONTEXT_H
api.h
Usd_NonPopulatingStageCacheWrapper
Definition:
stageCacheContext.h:39
Usd_NoBlock
Definition:
stageCacheContext.h:70
stacked.h
USD_API
#define USD_API
Definition:
api.h:40
UsdStage
Definition:
stage.h:151
UsdStageCacheContext
Usd_NonPopulatingStageCacheWrapper::cache
const UsdStageCache & cache
Definition:
stageCacheContext.h:42
TF_DEFINE_STACKED
TF_DEFINE_STACKED(UsdStageCacheContext, true, USD_API)
Definition:
stageCacheContext.h:121
UsdStageCache
Definition:
stageCache.h:84
UsdUseButDoNotPopulateCache
Usd_NonPopulatingStageCacheWrapper UsdUseButDoNotPopulateCache(StageCache &cache)
Definition:
stageCacheContext.h:55
pxr.h
UsdBlockStageCaches
Definition:
stageCacheContext.h:64
Usd_NonPopulatingStageCacheWrapper::Usd_NonPopulatingStageCacheWrapper
Usd_NonPopulatingStageCacheWrapper(const UsdStageCache &cache)
Definition:
stageCacheContext.h:40
PXR_NAMESPACE_OPEN_SCOPE
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition:
path.h:1432
UsdStageCacheContextBlockType
UsdStageCacheContextBlockType
Definition:
stageCacheContext.h:59
UsdBlockStageCachePopulation
Definition:
stageCacheContext.h:68
PXR_NAMESPACE_CLOSE_SCOPE
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition:
pxr.h:91
pxr
usd
usd
stageCacheContext.h
Generated on Mon Oct 7 2024 02:48:28 for HDK by
1.8.6