HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
IObject.h
Go to the documentation of this file.
1 //-*****************************************************************************
2 //
3 // Copyright (c) 2009-2013,
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_Abc_IObject_h_
38 #define _Alembic_Abc_IObject_h_
39 
40 #include <Alembic/Util/Export.h>
41 #include <Alembic/Abc/Foundation.h>
42 #include <Alembic/Abc/Base.h>
43 #include <Alembic/Abc/Argument.h>
44 
45 namespace Alembic {
46 namespace Abc {
47 namespace ALEMBIC_VERSION_NS {
48 
49 class IArchive;
50 class ICompoundProperty;
51 
52 //-*****************************************************************************
53 class ALEMBIC_EXPORT IObject : public Base
54 {
55 public:
56  //! By convention, we always define "this_type" in every Abc
57  //! class. This convention is relied upon by the unspecified-bool-type
58  //! conversion.
59  typedef IObject this_type;
61 
62  //-*************************************************************************
63  // CONSTRUCTION, DESTRUCTION, ASSIGNMENT
64  //-*************************************************************************
65 
66  //! The default constructor creates an empty IObject function set.
67  //! ...
68  IObject() {}
69 
70  //! This templated, explicit function creates a new object reader.
71  //! The first argument is any Abc (or AbcCoreAbstract) object
72  //! which can intrusively be converted to an AbcA::ObjectReaderPtr
73  //! to use as a parent, from which the error handler policy for
74  //! inheritance is also derived. The remaining optional arguments
75  //! can be used to override the ErrorHandlerPolicy.
76  template <class OBJECT_PTR>
77  IObject( OBJECT_PTR iParentObject,
78  const std::string &iName,
79  const Argument &iArg0 = Argument() );
80 
81  //! This attaches an IObject wrapper around an existing
82  //! ObjectReaderPtr, with an optional error handling policy.
83  template <class OBJECT_PTR>
84  IObject( OBJECT_PTR iPtr,
85  WrapExistingFlag /* iFlag */,
86  const Argument &iArg0 = Argument() )
87  : m_object( GetObjectReaderPtr( iPtr ) )
88  {
89  // Set the error handling policy
90  getErrorHandler().setPolicy(
91  GetErrorHandlerPolicy( iPtr, iArg0 ) );
92 
93  initInstance();
94  }
95 
96  //! This attaches an IObject wrapper around the top
97  //! object of an archive.
98  template <class ARCHIVE_PTR>
99  IObject( ARCHIVE_PTR iPtr,
100  TopFlag iFlag,
101  const Argument &iArg0 = Argument() )
102  {
103  // Set the error handling policy
104  getErrorHandler().setPolicy(
105  GetErrorHandlerPolicy( iPtr, iArg0 ) );
106 
107  ALEMBIC_ABC_SAFE_CALL_BEGIN( "IObject::IObject( top )" );
108 
109  m_object = GetArchiveReaderPtr( iPtr )->getTop();
110 
112  }
113 
114  //! Default copy constructor used
115  //! Default assignment operator used.
116 
117  //! Destructor
118  //! ...
119  virtual ~IObject();
120 
121  //-*************************************************************************
122  // OBJECT READER FUNCTIONALITY
123  //-*************************************************************************
124 
125  //! All objects have a header, which contains all the MetaData that was
126  //! specified upon their creation.
127  //! This function returns a constant reference to that Header.
128  const AbcA::ObjectHeader &getHeader() const;
129 
130  //! All objects have a name. This name is unique amongst their siblings
131  //! Returned by reference, since it is guaranteed to exist and be
132  //! unchanging.
133  //! This is a convenience function which returns the header's name.
134  const std::string &getName() const;
135 
136  //! The full name of an object is the complete path name all the way
137  //! to the root object of the archive. It is guaranteed to be fully
138  //! unique within the entire archive.
139  //! This is a convenience function which returns the header's full name.
140  const std::string &getFullName() const;
141 
142  //! All objects have metadata. This metadata is identical to the
143  //! Metadata of the top level compoundProperty "properties".
144  //! Because the metadata must exist and be initialized in order to
145  //! bootstrap the object, it is guaranteed to exist and is returned
146  //! by reference.
147  //! This is a convenience function which returns the header's MetaData.
149  { return getHeader().getMetaData(); }
150 
151  //! This function returns the object's archive, handily
152  //! wrapped in an IArchive wrapper.
153  IArchive getArchive() const;
154 
155  //! This function returns the object's parent, handily
156  //! wrapped in an IObject wrapper. If the object is the top
157  //! level object, the IObject returned will be NULL.
158  IObject getParent() const;
159 
160  //! This function returns the number of child objects that
161  //! this object has.
162  size_t getNumChildren() const;
163 
164  //! This function returns the headers of each of the child
165  //! objects that were written as children of this object.
166  const AbcA::ObjectHeader & getChildHeader( size_t i ) const;
167 
168  //! Return the header of an object by name.
169  //! This will return a NULL pointer if no header by that name is found.
170  const AbcA::ObjectHeader *
171  getChildHeader( const std::string &iName ) const;
172 
173  //! This returns the single top-level CompoundPropertyReader that exists
174  //! automatically as part of the object.
175  ICompoundProperty getProperties() const;
176 
177  //-*************************************************************************
178  // ADVANCED TOOLS
179  // Unless you really know why you need to be using these next few
180  // functions, they're probably best left alone. The right way to create
181  // an IObject is to actually call its constructor.
182  //-*************************************************************************
183 
184  //! This function returns an IObject constructed from the indexed
185  //! object.
186  IObject getChild( size_t iChildIndex ) const;
187 
188  //! This function returns an IObject wrapped constructed from the
189  //! header referenced by the name. If the child of the given name
190  //! does not exist, this will fail in the same way as if the
191  //! equivalent constructor was called.
192  IObject getChild( const std::string &iChildName ) const;
193 
194  //!-************************************************************************
195  // INSTANCE METHODS
196  // An IObject can refer to another IObject in the same cache and stand in
197  // as an instance for that target hierarchy. On disk only the instance
198  // object is required. When read in however, a normal hierarchy is
199  // returned. Optionally, client code could use the isInstanceRoot() and
200  // instanceSourcePath() methods to discover that the hierarchies are
201  // duplicate and instance them appropriately in memory.
202  //!-************************************************************************
203 
204  //! Returns whether this object directly instances another object.
205  bool isInstanceRoot() const;
206 
207  //! Returns whether this object has been arrived at via an instance, or if
208  //! this object is an instance itself.
209  bool isInstanceDescendant() const;
210 
211  //! If this object is an instance (isInstanceRoot), returns the source path
212  //! that the instance points at. Otherwise and empty string is returned.
213  std::string instanceSourcePath();
214 
215  bool isChildInstance(size_t iChildIndex) const;
216  bool isChildInstance(const std::string &iChildName) const;
217 
218  //! Returns the original ObjectReaderPtr, if this object is an instance
219  AbcA::ObjectReaderPtr getInstancePtr() const { return m_instanceObject; }
220 
221  //-*************************************************************************
222  // ABC BASE MECHANISMS
223  // These functions are used by Abc to deal with errors, rewrapping,
224  // and so on.
225  //-*************************************************************************
226 
227  //! getPtr, as usual, returns a shared ptr to the
228  //! underlying AbcCoreAbstract object, in this case the
229  //! ObjectReaderPtr. If this object happens to be an instance, it points
230  //! to the instance source ObjectReaderPtr
231  AbcA::ObjectReaderPtr getPtr() const { return m_object; }
232 
233  //! Reset returns this function set to an empty, default state.
234  void reset();
235 
236  //! Valid returns whether this function set is
237  //! valid.
238  bool valid() const
239  {
240  return ( Base::valid() && m_object );
241  }
242 
243  //! If an aggregated properties hash exists fill oDigest with it and
244  //! return true, if it doesn't exist return false
245  bool getPropertiesHash( Util::Digest & oDigest );
246 
247  //! If an aggregated child objects hash exists fill oDigest with it and
248  //! return true, if it doesn't exist return false
249  bool getChildrenHash( Util::Digest & oDigest );
250 
251  //! The unspecified-bool-type operator casts the object to "true"
252  //! if it is valid, and "false" otherwise.
253  ALEMBIC_OPERATOR_BOOL( valid() );
254 
255 public:
257 
258 private:
259  void init( AbcA::ObjectReaderPtr iParentObject,
260  const std::string &iName,
261  ErrorHandler::Policy iPolicy );
262 
263  void initInstance();
264 
265  void setInstancedFullName(const std::string& parentPath) const;
266 
267  // This is the "original" object when it is an instance (not the source)
268  AbcA::ObjectReaderPtr m_instanceObject;
269 
270  // All IObject ancestors of an instance object have these set.
271  mutable std::string m_instancedFullName;
272 };
273 
274 typedef Alembic::Util::shared_ptr< IObject > IObjectPtr;
275 
276 //-*****************************************************************************
278 GetObjectReaderPtr( IObject& iPrp ) { return iPrp.getPtr(); }
279 
280 //-*****************************************************************************
281 // TEMPLATE AND INLINE FUNCTIONS
282 //-*****************************************************************************
283 
284 template <class OBJ>
286  ErrorHandler::Policy iPcy )
287 {
288  Argument arg( iPcy );
289  return GetErrorHandlerPolicy( iObj, arg );
290 }
291 
292 //-*****************************************************************************
293 template <class OBJECT_PTR>
294 inline IObject::IObject( OBJECT_PTR iParentObject,
295  const std::string &iName,
296  const Argument &iArg0 )
297 {
298  init( GetObjectReaderPtr( iParentObject ),
299  iName,
300  GetErrorHandlerPolicy( iParentObject, iArg0 ) );
301 
302  initInstance();
303 }
304 
305 } // End namespace ALEMBIC_VERSION_NS
306 
307 using namespace ALEMBIC_VERSION_NS;
308 
309 } // End namespace Abc
310 } // End namespace Alembic
311 
312 #endif
#define ALEMBIC_OPERATOR_BOOL(PASS_COND)
Definition: OperatorBool.h:42
ErrorHandler::Policy GetErrorHandlerPolicy(SOMETHING iSomething, const Argument &iArg0, const Argument &iArg1=Argument(), const Argument &iArg2=Argument())
Definition: Argument.h:219
const AbcA::MetaData & getMetaData() const
Definition: IObject.h:148
GLsizei const GLchar *const * string
Definition: glcorearb.h:813
Alembic::Util::shared_ptr< ObjectReader > ObjectReaderPtr
AbcA::ObjectReaderPtr getInstancePtr() const
Returns the original ObjectReaderPtr, if this object is an instance.
Definition: IObject.h:219
png_uint_32 i
Definition: png.h:2877
AbcA::ObjectReaderPtr getPtr() const
Definition: IObject.h:231
#define ALEMBIC_ABC_SAFE_CALL_END_RESET()
Definition: ErrorHandler.h:181
AbcA::ArchiveReaderPtr GetArchiveReaderPtr(AbcA::ArchiveReaderPtr iPtr)
Definition: Foundation.h:209
Alembic::Util::shared_ptr< IObject > IObjectPtr
Definition: IObject.h:274
AbcA::ObjectReaderPtr GetObjectReaderPtr(AbcA::ObjectReaderPtr iPtr)
Definition: Foundation.h:190
#define ALEMBIC_ABC_SAFE_CALL_BEGIN(CONTEXT)
Definition: ErrorHandler.h:172
IObject(OBJECT_PTR iPtr, WrapExistingFlag, const Argument &iArg0=Argument())
Definition: IObject.h:84
IObject(ARCHIVE_PTR iPtr, TopFlag iFlag, const Argument &iArg0=Argument())
Definition: IObject.h:99
#define ALEMBIC_EXPORT
Definition: Export.h:51
#define ALEMBIC_VERSION_NS
Definition: Foundation.h:104