1 ///////////////////////////////////////////////////////////////////////////
3 // Copyright (c) 2002, Industrial Light & Magic, a division of Lucas
6 // All rights reserved.
8 // Redistribution and use in source and binary forms, with or without
9 // modification, are permitted provided that the following conditions are
11 // * Redistributions of source code must retain the above copyright
12 // notice, this list of conditions and the following disclaimer.
13 // * Redistributions in binary form must reproduce the above
14 // copyright notice, this list of conditions and the following disclaimer
15 // in the documentation and/or other materials provided with the
17 // * Neither the name of Industrial Light & Magic nor the names of
18 // its contributors may be used to endorse or promote products derived
19 // from this software without specific prior written permission.
21 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
22 // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
23 // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
24 // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
25 // OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
26 // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
27 // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
28 // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
29 // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
30 // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
31 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
33 ///////////////////////////////////////////////////////////////////////////
37 #ifndef INCLUDED_IMF_CHANNEL_LIST_H
38 #define INCLUDED_IMF_CHANNEL_LIST_H
40 //-----------------------------------------------------------------------------
45 //-----------------------------------------------------------------------------
48 #include <ImfPixelType.h>
59 //------------------------------
60 // Data type; see ImfPixelType.h
61 //------------------------------
66 //--------------------------------------------
67 // Subsampling: pixel (x, y) is present in the
70 // x % xSampling == 0 && y % ySampling == 0
72 //--------------------------------------------
82 Channel (PixelType type = HALF,
91 bool operator == (const Channel &other) const;
103 void insert (const char name[],
104 const Channel &channel);
106 //------------------------------------------------------------------
107 // Access to existing channels:
109 // [n] Returns a reference to the channel with name n.
110 // If no channel with name n exists, an Iex::ArgExc
113 // findChannel(n) Returns a pointer to the channel with name n,
114 // or 0 if no channel with name n exists.
116 //------------------------------------------------------------------
118 Channel & operator [] (const char name[]);
119 const Channel & operator [] (const char name[]) const;
121 Channel * findChannel (const char name[]);
122 const Channel * findChannel (const char name[]) const;
125 //-------------------------------------------
126 // Iterator-style access to existing channels
127 //-------------------------------------------
129 typedef std::map <Name, Channel> ChannelMap;
135 ConstIterator begin () const;
137 ConstIterator end () const;
138 Iterator find (const char name[]);
139 ConstIterator find (const char name[]) const;
142 //-----------------------------------------------------------------
143 // Support for image layers:
145 // In an image file with many channels it is sometimes useful to
146 // group the channels into "layers", that is, into sets of channels
147 // that logically belong together. Grouping channels into layers
148 // is done using a naming convention: channel C in layer L is
151 // For example, a computer graphic image may contain separate
152 // R, G and B channels for light that originated at each of
153 // several different virtual light sources. The channels in
154 // this image might be called "light1.R", "light1.G", "light1.B",
155 // "light2.R", "light2.G", "light2.B", etc.
157 // Note that this naming convention allows layers to be nested;
158 // for example, "light1.specular.R" identifies the "R" channel
159 // in the "specular" sub-layer of layer "light1".
161 // Channel names that don't contain a "." or that contain a
162 // "." only at the beginning or at the end are not considered
163 // to be part of any layer.
165 // layers(lns) sorts the channels in this ChannelList
166 // into layers and stores the names of
167 // all layers, sorted alphabetically,
168 // into string set lns.
170 // channelsInLayer(ln,f,l) stores a pair of iterators in f and l
171 // such that the loop
173 // for (ConstIterator i = f; i != l; ++i)
176 // iterates over all channels in layer ln.
177 // channelsInLayer (ln, l, p) calls
178 // channelsWithPrefix (ln + ".", l, p).
180 //-----------------------------------------------------------------
182 void layers (std::set <std::string> &layerNames) const;
184 void channelsInLayer (const std::string &layerName,
188 void channelsInLayer (const std::string &layerName,
189 ConstIterator &first,
190 ConstIterator &last) const;
193 //-------------------------------------------------------------------
194 // Find all channels whose name begins with a given prefix:
196 // channelsWithPrefix(p,f,l) stores a pair of iterators in f and l
197 // such that the following loop iterates over all channels whose name
198 // begins with string p:
200 // for (ConstIterator i = f; i != l; ++i)
203 //-------------------------------------------------------------------
205 void channelsWithPrefix (const char prefix[],
209 void channelsWithPrefix (const char prefix[],
210 ConstIterator &first,
211 ConstIterator &last) const;
217 bool operator == (const ChannelList &other) const;
229 class ChannelList::Iterator
234 Iterator (const ChannelList::ChannelMap::iterator &i);
236 Iterator & operator ++ ();
237 Iterator operator ++ (int);
239 const char * name () const;
240 Channel & channel () const;
244 friend class ChannelList::ConstIterator;
246 ChannelList::ChannelMap::iterator _i;
250 class ChannelList::ConstIterator
255 ConstIterator (const ChannelList::ChannelMap::const_iterator &i);
256 ConstIterator (const ChannelList::Iterator &other);
258 ConstIterator & operator ++ ();
259 ConstIterator operator ++ (int);
261 const char * name () const;
262 const Channel & channel () const;
266 friend bool operator == (const ConstIterator &, const ConstIterator &);
267 friend bool operator != (const ConstIterator &, const ConstIterator &);
269 ChannelList::ChannelMap::const_iterator _i;
278 ChannelList::Iterator::Iterator (): _i()
285 ChannelList::Iterator::Iterator (const ChannelList::ChannelMap::iterator &i):
292 inline ChannelList::Iterator &
293 ChannelList::Iterator::operator ++ ()
300 inline ChannelList::Iterator
301 ChannelList::Iterator::operator ++ (int)
303 Iterator tmp = *this;
310 ChannelList::Iterator::name () const
317 ChannelList::Iterator::channel () const
324 ChannelList::ConstIterator::ConstIterator (): _i()
330 ChannelList::ConstIterator::ConstIterator
331 (const ChannelList::ChannelMap::const_iterator &i): _i (i)
338 ChannelList::ConstIterator::ConstIterator (const ChannelList::Iterator &other):
344 inline ChannelList::ConstIterator &
345 ChannelList::ConstIterator::operator ++ ()
352 inline ChannelList::ConstIterator
353 ChannelList::ConstIterator::operator ++ (int)
355 ConstIterator tmp = *this;
362 ChannelList::ConstIterator::name () const
367 inline const Channel &
368 ChannelList::ConstIterator::channel () const
375 operator == (const ChannelList::ConstIterator &x,
376 const ChannelList::ConstIterator &y)
383 operator != (const ChannelList::ConstIterator &x,
384 const ChannelList::ConstIterator &y)