HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
changeBlock.h
Go to the documentation of this file.
1 //
2 // Copyright 2016 Pixar
3 //
4 // Licensed under the terms set forth in the LICENSE.txt file available at
5 // https://openusd.org/license.
6 //
7 #ifndef PXR_USD_SDF_CHANGE_BLOCK_H
8 #define PXR_USD_SDF_CHANGE_BLOCK_H
9 
10 #include "pxr/pxr.h"
11 #include "pxr/usd/sdf/api.h"
12 
14 
15 /// \class SdfChangeBlock
16 ///
17 /// <b>DANGER DANGER DANGER</b>
18 ///
19 /// Please make sure you have read and fully understand the
20 /// issues below before using a changeblock! They are very
21 /// easy to use in an unsafe way that could make the system
22 /// crash or corrupt data. If you have any questions, please
23 /// contact the USD team, who would be happy to help!
24 ///
25 /// SdfChangeBlock provides a way to group a round of related changes to
26 /// scene description in order to process them more efficiently.
27 ///
28 /// Normally, Sdf sends notification immediately as changes are made so
29 /// that downstream representations like UsdStage can update accordingly.
30 ///
31 /// However, sometimes it can be advantageous to group a series of Sdf
32 /// changes into a batch so that they can be processed more efficiently,
33 /// with a single round of change processing. An example might be when
34 /// setting many avar values on a model at the same time.
35 ///
36 /// Opening a changeblock tells Sdf to delay sending notification about
37 /// changes until the outermost changeblock is exited. Until then,
38 /// Sdf internally queues up the notification it needs to send.
39 ///
40 /// \note It is *not* safe to use Usd or other downstream API
41 /// while a changeblock is open!! This is because those derived
42 /// representations will not have had a chance to update while the
43 /// changeblock is open. Not only will their view of the world be
44 /// stale, it could be unsafe to even make queries from, since they
45 /// may be holding onto expired handles to Sdf objects that no longer
46 /// exist.
47 ///
48 /// If you need to make a bunch of changes to scene description,
49 /// the best approach is to build a list of necessary changes that
50 /// can be performed directly via the Sdf API, then submit those all
51 /// inside a changeblock without talking to any downstream libraries.
52 /// For example, this is how many mutators in Usd that operate on more
53 /// than one field or Spec work.
54 ///
55 
57 public:
58  SDF_API
61  if (_key) {
62  _CloseChangeBlock(_key);
63  }
64  }
65 private:
66  SDF_API
67  void _CloseChangeBlock(void const *key) const;
68 
69  void const *_key;
70 };
71 
73 
74 #endif // PXR_USD_SDF_CHANGE_BLOCK_H
#define SDF_API
Definition: api.h:23
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1425
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:74
SDF_API SdfChangeBlock()