HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
ObjectWriter.h
Go to the documentation of this file.
1 //-*****************************************************************************
2 //
3 // Copyright (c) 2009-2012,
4 // Sony Pictures Imageworks Inc. and
5 // Industrial Light & Magic, a division of Lucasfilm Entertainment Company Ltd.
6 //
7 // All rights reserved.
8 //
9 // Redistribution and use in source and binary forms, with or without
10 // modification, are permitted provided that the following conditions are
11 // met:
12 // * Redistributions of source code must retain the above copyright
13 // notice, this list of conditions and the following disclaimer.
14 // * Redistributions in binary form must reproduce the above
15 // copyright notice, this list of conditions and the following disclaimer
16 // in the documentation and/or other materials provided with the
17 // distribution.
18 // * Neither the name of Sony Pictures Imageworks, nor
19 // Industrial Light & Magic, nor the names of their contributors may be used
20 // to endorse or promote products derived from this software without specific
21 // prior written permission.
22 //
23 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
24 // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
25 // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
26 // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
27 // OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
28 // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
29 // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
30 // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
31 // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
32 // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
33 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
34 //
35 //-*****************************************************************************
36 
37 #ifndef Alembic_AbcCoreAbstract_ObjectWriter_h
38 #define Alembic_AbcCoreAbstract_ObjectWriter_h
39 
40 #include <Alembic/Util/Export.h>
44 
45 namespace Alembic {
46 namespace AbcCoreAbstract {
47 namespace ALEMBIC_VERSION_NS {
48 
49 //-*****************************************************************************
50 //! An Object consists of a list of children objects, which may be empty,
51 //! and a single compound property which is the root of any properties
52 //! which the object may contain.
53 //! Objects have MetaData, which is identical to the MetaData of the root
54 //! Compound Property.
57 {
58 public:
59  //! Virtual destructor
60  //! ...
61  virtual ~ObjectWriter();
62 
63  //-*************************************************************************
64  // NEW FUNCTIONS
65  //-*************************************************************************
66 
67  //! All objects are created from an ObjectHeader, which contains their
68  //! name, their full name, and their MetaData. This returns
69  //! a const reference to the ObjectHeader which was given upon
70  //! creation.
71  virtual const ObjectHeader & getHeader() const = 0;
72 
73  //! All objects have a name. This name is unique amongst their siblings
74  //! Returned by reference, since it is guaranteed to exist and be
75  //! unchanging. This is the name that was given when the object was
76  //! created.
77  const std::string &getName() const
78  { return getHeader().getName(); }
79 
80  //! The full name of an object is the complete path name all the way
81  //! to the root object of the archive. It is guaranteed to be fully
82  //! unique within the entire archive.
83  const std::string &getFullName() const
84  { return getHeader().getFullName(); }
85 
86  //! All objects have metadata. This metadata is identical to the
87  //! Metadata of the top level compoundProperty "properties".
88  //! Because the metadata must exist and be initialized in order to
89  //! bootstrap the object, it is guaranteed to exist and is returned
90  //! by reference. While MetaData was required to create the object,
91  //! additional MetaData may be appended during the writing of the
92  //! object. This returns the accumulated MetaData, which may change
93  //! as writing occurs. The reference will remain valid, but the
94  //! MetaData it points to may change over time.
95  const MetaData &getMetaData() const
96  { return getHeader().getMetaData(); }
97 
98  //! All objects have a shared link to the root. This may seem
99  //! wasteful, but it is essential in order to allow for the flexible,
100  //! reference-counted autonomy of the writer objects. Alembic
101  //! allows you to keep references to writers wherever you want,
102  //! without requiring you to keep track of (or store) the parental
103  //! hierarchy directly. In order to make this possible, we have
104  //! the ability to walk upwards. This may be stored as a direct
105  //! link, or retrieved by walking up the parent chain, which is
106  //! a feature of the individual implementations. (it might not be
107  //! cheap, basically).
108  //! In order to prevent shared_ptr cycles, it is important
109  //! that objects only store their children via weak ptrs.
110  virtual ArchiveWriterPtr getArchive() = 0;
111 
112  //! All objects have a shared link to their parent. This may seem
113  //! wasteful, but it is essential in order to allow for the flexible,
114  //! reference-counted autonomy of the writer objects. Alembic
115  //! allows you to keep references to writers wherever you want,
116  //! without requiring you to keep track of (or store) the parental
117  //! hierarchy directly. In order to make this possible, we have
118  //! the ability to walk upwards.
119  //! In order to prevent shared_ptr cycles, it is important
120  //! that objects only store their children via weak ptrs.
121  virtual ObjectWriterPtr getParent() = 0;
122 
123  //! All objects have a single compound property which is the
124  //! root for any properties which are associated with this object.
125  //! Guaranteed to exist, even if the compound property itself is
126  //! empty. This may change as properties are added.
127  virtual CompoundPropertyWriterPtr getProperties() = 0;
128 
129  //-*************************************************************************
130  // CHILDREN
131  //-*************************************************************************
132 
133  //! Returns the number of objects that are contained as children.
134  //! this number may increase (but not decrease) as objects are
135  //! created. This is the number of children object writers that
136  //! have ALREADY BEEN ADDED. It may increase.
137  virtual size_t getNumChildren() = 0;
138 
139  //! Returns the header of an object that has already been added.
140  //! Object is selected by index.
141  //! This will throw an exception on out-of-range access.
142  virtual const ObjectHeader & getChildHeader( size_t i ) = 0;
143 
144  //! Returns the header of an object that has already been added,
145  //! by name.
146  //! This will return NULL pointer if no header by that name is found.
147  //! Even if the object assosciated with this header is no longer
148  //! existing, the header will be non-null if any such object
149  //! had been created. This is a mechanism for testing if something
150  //! has already been made.
151  virtual const ObjectHeader *
152  getChildHeader( const std::string &iName ) = 0;
153 
154  //! Returns a pointer to an object writer at the given index,
155  //! that has ALREADY BEEN ADDED. It is an error to request a child
156  //! with an out of range index, and an exception will be thrown.
157  //! In a strange case,
158  //! this will return an empty pointer if the writer has been
159  //! added in the past, but was closed (deleted). There is really
160  //! no distinction between an empty weak pointer and a weak pointer
161  //! to an expired object, so we simply return an empty pointer
162  //! if the object had been created but no longer exists.
163  //! This is just a convenience function that uses getChildHeader
164  //! and getChild( name );
165  ObjectWriterPtr getChild( size_t i );
166 
167  //! Returns a pointer to an object writer of the given name iName,
168  //! for an object that has ALREADY BEEN ADDED. This will return
169  //! an empty pointer if no object of the given name has been added.
170  virtual ObjectWriterPtr getChild( const std::string &iName ) = 0;
171 
172  //! Create an object with given header.
173  //! the header's "fullName" will be ignored and set by the parent object.
174  //! If an object with the given name already exists, an exception will
175  //! be thrown, as this is a programming error.
176  virtual ObjectWriterPtr createChild( const ObjectHeader &iHeader ) = 0;
177 
178  //! Returns shared pointer to myself.
179  //! Sometimes this may be a spoofed ptr.
180  virtual ObjectWriterPtr asObjectPtr() = 0;
181 };
182 
183 } // End namespace ALEMBIC_VERSION_NS
184 
185 using namespace ALEMBIC_VERSION_NS;
186 
187 } // End namespace AbcCoreAbstract
188 } // End namespace Alembic
189 
190 #endif
191 
Alembic::Util::shared_ptr< ObjectWriter > ObjectWriterPtr
GLsizei const GLchar *const * string
Definition: glcorearb.h:814
#define ALEMBIC_EXPORT
Definition: Export.h:51
GU_API GA_Offset getParent(const GU_Detail *gdp, const GA_Offset &node)
Alembic::Util::shared_ptr< ArchiveWriter > ArchiveWriterPtr
Smart Ptrs to Writers.
#define ALEMBIC_VERSION_NS
Definition: Foundation.h:88
Alembic::Util::shared_ptr< CompoundPropertyWriter > CompoundPropertyWriterPtr