1//
2// SPDX-License-Identifier: BSD-3-Clause
3// Copyright (c) Contributors to the OpenEXR Project.
4//
5
6
7#ifndef INCLUDED_IMF_CHANNEL_LIST_H
8#define INCLUDED_IMF_CHANNEL_LIST_H
9
10//-----------------------------------------------------------------------------
11//
12// class Channel
13// class ChannelList
14//
15//-----------------------------------------------------------------------------
16
17#include "ImfForward.h"
18
19#include "ImfName.h"
20#include "ImfPixelType.h"
21
22
23#include <map>
24#include <set>
25#include <string>
26
27OPENEXR_IMF_INTERNAL_NAMESPACE_HEADER_ENTER
28
29
30struct IMF_EXPORT_TYPE Channel
31{
32 //------------------------------
33 // Data type; see ImfPixelType.h
34 //------------------------------
35
36 PixelType type;
37
38
39 //--------------------------------------------
40 // Subsampling: pixel (x, y) is present in the
41 // channel only if
42 //
43 // x % xSampling == 0 && y % ySampling == 0
44 //
45 //--------------------------------------------
46
47 int xSampling;
48 int ySampling;
49
50
51 //--------------------------------------------------------------
52 // Hint to lossy compression methods that indicates whether
53 // human perception of the quantity represented by this channel
54 // is closer to linear or closer to logarithmic. Compression
55 // methods may optimize image quality by adjusting pixel data
56 // quantization acording to this hint.
57 // For example, perception of red, green, blue and luminance is
58 // approximately logarithmic; the difference between 0.1 and 0.2
59 // is perceived to be roughly the same as the difference between
60 // 1.0 and 2.0. Perception of chroma coordinates tends to be
61 // closer to linear than logarithmic; the difference between 0.1
62 // and 0.2 is perceived to be roughly the same as the difference
63 // between 1.0 and 1.1.
64 //--------------------------------------------------------------
65
66 bool pLinear;
67
68
69 //------------
70 // Constructor
71 //------------
72
73 IMF_EXPORT
74 Channel (PixelType type = HALF,
75 int xSampling = 1,
76 int ySampling = 1,
77 bool pLinear = false);
78
79
80 //------------
81 // Operator ==
82 //------------
83
84 IMF_EXPORT
85 bool operator == (const Channel &other) const;
86};
87
88
89class IMF_EXPORT_TYPE ChannelList
90{
91 public:
92
93 //--------------
94 // Add a channel
95 //--------------
96
97 IMF_EXPORT
98 void insert (const char name[],
99 const Channel &channel);
100
101 IMF_EXPORT
102 void insert (const std::string &name,
103 const Channel &channel);
104
105 //------------------------------------------------------------------
106 // Access to existing channels:
107 //
108 // [n] Returns a reference to the channel with name n.
109 // If no channel with name n exists, an IEX_NAMESPACE::ArgExc
110 // is thrown.
111 //
112 // findChannel(n) Returns a pointer to the channel with name n,
113 // or 0 if no channel with name n exists.
114 //
115 //------------------------------------------------------------------
116
117 IMF_EXPORT
118 Channel & operator [] (const char name[]);
119 IMF_EXPORT
120 const Channel & operator [] (const char name[]) const;
121
122 IMF_EXPORT
123 Channel & operator [] (const std::string &name);
124 IMF_EXPORT
125 const Channel & operator [] (const std::string &name) const;
126
127 IMF_EXPORT
128 Channel * findChannel (const char name[]);
129 IMF_EXPORT
130 const Channel * findChannel (const char name[]) const;
131
132 IMF_EXPORT
133 Channel * findChannel (const std::string &name);
134 IMF_EXPORT
135 const Channel * findChannel (const std::string &name) const;
136
137
138 //-------------------------------------------
139 // Iterator-style access to existing channels
140 //-------------------------------------------
141
142 typedef std::map <Name, Channel> ChannelMap;
143
144 class Iterator;
145 class ConstIterator;
146
147 IMF_EXPORT
148 Iterator begin ();
149 IMF_EXPORT
150 ConstIterator begin () const;
151
152 IMF_EXPORT
153 Iterator end ();
154 IMF_EXPORT
155 ConstIterator end () const;
156
157 IMF_EXPORT
158 Iterator find (const char name[]);
159 IMF_EXPORT
160 ConstIterator find (const char name[]) const;
161
162 IMF_EXPORT
163 Iterator find (const std::string &name);
164 IMF_EXPORT
165 ConstIterator find (const std::string &name) const;
166
167
168 //-----------------------------------------------------------------
169 // Support for image layers:
170 //
171 // In an image file with many channels it is sometimes useful to
172 // group the channels into "layers", that is, into sets of channels
173 // that logically belong together. Grouping channels into layers
174 // is done using a naming convention: channel C in layer L is
175 // called "L.C".
176 //
177 // For example, a computer graphic image may contain separate
178 // R, G and B channels for light that originated at each of
179 // several different virtual light sources. The channels in
180 // this image might be called "light1.R", "light1.G", "light1.B",
181 // "light2.R", "light2.G", "light2.B", etc.
182 //
183 // Note that this naming convention allows layers to be nested;
184 // for example, "light1.specular.R" identifies the "R" channel
185 // in the "specular" sub-layer of layer "light1".
186 //
187 // Channel names that don't contain a "." or that contain a
188 // "." only at the beginning or at the end are not considered
189 // to be part of any layer.
190 //
191 // layers(lns) sorts the channels in this ChannelList
192 // into layers and stores the names of
193 // all layers, sorted alphabetically,
194 // into string set lns.
195 //
196 // channelsInLayer(ln,f,l) stores a pair of iterators in f and l
197 // such that the loop
198 //
199 // for (ConstIterator i = f; i != l; ++i)
200 // ...
201 //
202 // iterates over all channels in layer ln.
203 // channelsInLayer (ln, l, p) calls
204 // channelsWithPrefix (ln + ".", l, p).
205 //
206 //-----------------------------------------------------------------
207
208 IMF_EXPORT
209 void layers (std::set <std::string> &layerNames) const;
210
211 IMF_EXPORT
212 void channelsInLayer (const std::string &layerName,
213 Iterator &first,
214 Iterator &last);
215
216 IMF_EXPORT
217 void channelsInLayer (const std::string &layerName,
218 ConstIterator &first,
219 ConstIterator &last) const;
220
221
222 //-------------------------------------------------------------------
223 // Find all channels whose name begins with a given prefix:
224 //
225 // channelsWithPrefix(p,f,l) stores a pair of iterators in f and l
226 // such that the following loop iterates over all channels whose name
227 // begins with string p:
228 //
229 // for (ConstIterator i = f; i != l; ++i)
230 // ...
231 //
232 //-------------------------------------------------------------------
233
234 IMF_EXPORT
235 void channelsWithPrefix (const char prefix[],
236 Iterator &first,
237 Iterator &last);
238
239 IMF_EXPORT
240 void channelsWithPrefix (const char prefix[],
241 ConstIterator &first,
242 ConstIterator &last) const;
243
244 IMF_EXPORT
245 void channelsWithPrefix (const std::string &prefix,
246 Iterator &first,
247 Iterator &last);
248
249 IMF_EXPORT
250 void channelsWithPrefix (const std::string &prefix,
251 ConstIterator &first,
252 ConstIterator &last) const;
253
254 //------------
255 // Operator ==
256 //------------
257
258 IMF_EXPORT
259 bool operator == (const ChannelList &other) const;
260
261 private:
262
263 ChannelMap _map;
264};
265
266
267//----------
268// Iterators
269//----------
270
271class IMF_EXPORT_TYPE ChannelList::Iterator
272{
273 public:
274
275 IMF_EXPORT
276 Iterator ();
277 IMF_EXPORT
278 Iterator (const ChannelList::ChannelMap::iterator &i);
279
280 IMF_EXPORT
281 Iterator & operator ++ ();
282 IMF_EXPORT
283 Iterator operator ++ (int);
284
285 IMF_EXPORT
286 const char * name () const;
287 IMF_EXPORT
288 Channel & channel () const;
289
290 private:
291
292 friend class ChannelList::ConstIterator;
293
294 ChannelList::ChannelMap::iterator _i;
295};
296
297
298class IMF_EXPORT_TYPE ChannelList::ConstIterator
299{
300 public:
301
302 IMF_EXPORT
303 ConstIterator ();
304 IMF_EXPORT
305 ConstIterator (const ChannelList::ChannelMap::const_iterator &i);
306 IMF_EXPORT
307 ConstIterator (const ChannelList::Iterator &other);
308
309 IMF_EXPORT
310 ConstIterator & operator ++ ();
311 IMF_EXPORT
312 ConstIterator operator ++ (int);
313
314 IMF_EXPORT
315 const char * name () const;
316 IMF_EXPORT
317 const Channel & channel () const;
318
319 private:
320
321 friend bool operator == (const ConstIterator &, const ConstIterator &);
322 friend bool operator != (const ConstIterator &, const ConstIterator &);
323
324 ChannelList::ChannelMap::const_iterator _i;
325};
326
327
328//-----------------
329// Inline Functions
330//-----------------
331
332inline
333ChannelList::Iterator::Iterator (): _i()
334{
335 // empty
336}
337
338
339inline
340ChannelList::Iterator::Iterator (const ChannelList::ChannelMap::iterator &i):
341 _i (i)
342{
343 // empty
344}
345
346
347inline ChannelList::Iterator &
348ChannelList::Iterator::operator ++ ()
349{
350 ++_i;
351 return *this;
352}
353
354
355inline ChannelList::Iterator
356ChannelList::Iterator::operator ++ (int)
357{
358 Iterator tmp = *this;
359 ++_i;
360 return tmp;
361}
362
363
364inline const char *
365ChannelList::Iterator::name () const
366{
367 return *_i->first;
368}
369
370
371inline Channel &
372ChannelList::Iterator::channel () const
373{
374 return _i->second;
375}
376
377
378inline
379ChannelList::ConstIterator::ConstIterator (): _i()
380{
381 // empty
382}
383
384inline
385ChannelList::ConstIterator::ConstIterator
386 (const ChannelList::ChannelMap::const_iterator &i): _i (i)
387{
388 // empty
389}
390
391
392inline
393ChannelList::ConstIterator::ConstIterator (const ChannelList::Iterator &other):
394 _i (other._i)
395{
396 // empty
397}
398
399inline ChannelList::ConstIterator &
400ChannelList::ConstIterator::operator ++ ()
401{
402 ++_i;
403 return *this;
404}
405
406
407inline ChannelList::ConstIterator
408ChannelList::ConstIterator::operator ++ (int)
409{
410 ConstIterator tmp = *this;
411 ++_i;
412 return tmp;
413}
414
415
416inline const char *
417ChannelList::ConstIterator::name () const
418{
419 return *_i->first;
420}
421
422inline const Channel &
423ChannelList::ConstIterator::channel () const
424{
425 return _i->second;
426}
427
428
429inline bool
430operator == (const ChannelList::ConstIterator &x,
431 const ChannelList::ConstIterator &y)
432{
433 return x._i == y._i;
434}
435
436
437inline bool
438operator != (const ChannelList::ConstIterator &x,
439 const ChannelList::ConstIterator &y)
440{
441 return !(x == y);
442}
443
444
445OPENEXR_IMF_INTERNAL_NAMESPACE_HEADER_EXIT
446
447#endif
448

source code of include/OpenEXR/ImfChannelList.h