HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
ArrayPropertyReader.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_ArrayPropertyReader_h
38 #define Alembic_AbcCoreAbstract_ArrayPropertyReader_h
39 
40 #include <Alembic/Util/Export.h>
44 
45 namespace Alembic {
46 namespace AbcCoreAbstract {
47 namespace ALEMBIC_VERSION_NS {
48 
49 //-*****************************************************************************
50 //! An Array Property is a Rank N (usually 1-3) property which has a
51 //! multidimensional array of identically typed values for each
52 //! sample. This is distinguished from a Simple Property, which has a
53 //! single element per sample, and requires less sophisticated
54 //! resource management.
56  : public BasePropertyReader
57 {
58 public:
59  //! Virtual destructor
60  //! ...
61  virtual ~ArrayPropertyReader();
62 
63  //-*************************************************************************
64  // NEW FUNCTIONS
65  //-*************************************************************************
66 
67  //! Return the number of samples contained in the property.
68  //! This can be any number, including zero.
69  //! This returns the number of samples that were written, independently
70  //! of whether or not they were constant. Implementations may (and should)
71  //! choose to condense identical samples.
72  virtual size_t getNumSamples() = 0;
73 
74  //! Ask if we're constant - no change in value amongst samples,
75  //! regardless of the time sampling.
76  virtual bool isConstant() = 0;
77 
78  //! It returns a shared pointer to a thing which _is_ the data, in a
79  //! locked and retrieved form. This represents the point of demand,
80  //! not below here.
81  //! Implementations of this library can (and should) utilize the
82  //! custom-deleter capabilities of the smart_ptr to add locking and
83  //! unlocking access to cache or management code.
84  //! It will throw an exception on an out-of-range access.
85  //! Though it could technically return the pointer by value efficiently
86  //! enough, we return by reference so that the calling signature
87  //! mirrors the ScalarPropertyReader.
88  //!
89  //! For each DataType, the ( void * ) data buffer returned in the
90  //! array sample points to one data element, which in the case of
91  //! DataType( kStringPOD, 1 ) and DataType( kWstringPOD, 1 ) are
92  //! arrays of std::string and std::wstring, respectively.
93  virtual void getSample( index_t iSampleIndex,
94  ArraySamplePtr &oSample ) = 0;
95 
96  //! Find the largest valid index that has a time less than or equal
97  //! to the given time. Invalid to call this with zero samples.
98  //! If the minimum sample time is greater than iTime, index
99  //! 0 will be returned.
100  virtual std::pair<index_t, chrono_t> getFloorIndex( chrono_t iTime ) = 0;
101 
102  //! Find the smallest valid index that has a time greater
103  //! than the given time. Invalid to call this with zero samples.
104  //! If the maximum sample time is less than iTime, index
105  //! numSamples-1 will be returned.
106  virtual std::pair<index_t, chrono_t> getCeilIndex( chrono_t iTime ) = 0;
107 
108  //! Find the valid index with the closest time to the given
109  //! time. Invalid to call this with zero samples.
110  virtual std::pair<index_t, chrono_t> getNearIndex( chrono_t iTime ) = 0;
111 
112  //! Expose the key for apps that use their own custom cache management.
113  virtual bool getKey( index_t iSampleIndex, ArraySampleKey & oKey ) = 0;
114 
115  //! The ArraySample may have incorrect dimensions, (even though the packed
116  //! data will be correct) expose the correct dimensions here for those
117  //! clients that need it.
118  virtual void getDimensions( index_t iSampleIndex, Dimensions & oDim ) = 0;
119 
120  //! A hint about whether this property has 1 and only 1 DataType
121  //! for each of it's samples. Array Properties with no samples written to
122  //! it are still considered scalar like.
123  virtual bool isScalarLike() = 0;
124 
125  //! Reads the data for the requested sample into the memory location
126  //! specified by iIntoLocation as the requested POD type specified by iPod.
127  //! Out-of-range indices, or incompatible POD types will cause an
128  //! exception to be thrown.
129  //!
130  //! Incompatible POD types include trying to read a std::string,
131  //! std::wstring, or float16_t as anything OTHER than itself.
132  //!
133  //! In all cases EXCEPT String and Wstring, the iPod type and the total
134  //! number of items from getDimensions for this property can be used to
135  //! determine the size of the memory buffer which iIntoLocation must point
136  //! to. In the case of String and Wstring,
137  //! iIntoLocation should be an array of std::string or std::wstring.
138  //!
139  //! This is one of the only places where we break from POD types at
140  //! the base, and we're making an explicit decision to use std::string
141  //! and std::wstring as core language-level primitives.
142  virtual void getAs( index_t iSample, void *iIntoLocation,
143  PlainOldDataType iPod ) = 0;
144 };
145 
146 } // End namespace ALEMBIC_VERSION_NS
147 
148 using namespace ALEMBIC_VERSION_NS;
149 
150 } // End namespace AbcCoreAbstract
151 } // End namespace Alembic
152 
153 
154 
155 #endif
Alembic::Util::shared_ptr< ArraySample > ArraySamplePtr
Definition: ArraySample.h:138
BaseDimensions< Alembic::Util::uint64_t > Dimensions
Definition: Dimensions.h:189
#define ALEMBIC_EXPORT
Definition: Export.h:51
#define ALEMBIC_VERSION_NS
Definition: Foundation.h:105