1//
2// SPDX-License-Identifier: BSD-3-Clause
3// Copyright (c) Contributors to the OpenEXR Project.
4//
5
6
7#ifndef INCLUDED_IMF_FRAME_BUFFER_H
8#define INCLUDED_IMF_FRAME_BUFFER_H
9
10//-----------------------------------------------------------------------------
11//
12// class Slice
13// class FrameBuffer
14//
15//-----------------------------------------------------------------------------
16
17#include "ImfForward.h"
18
19#include "ImfName.h"
20#include "ImfPixelType.h"
21
22#include <ImathBox.h>
23
24#include <map>
25#include <string>
26#include <cstdint>
27
28
29OPENEXR_IMF_INTERNAL_NAMESPACE_HEADER_ENTER
30
31//-------------------------------------------------------
32// Description of a single slice of the frame buffer:
33//
34// Note -- terminology: as part of a file, a component of
35// an image (e.g. red, green, blue, depth etc.) is called
36// a "channel". As part of a frame buffer, an image
37// component is called a "slice".
38//-------------------------------------------------------
39
40struct IMF_EXPORT_TYPE Slice
41{
42 //------------------------------
43 // Data type; see ImfPixelType.h
44 //------------------------------
45
46 PixelType type;
47
48
49 //---------------------------------------------------------------------
50 // Memory layout: The address of pixel (x, y) is
51 //
52 // base + (xp / xSampling) * xStride + (yp / ySampling) * yStride
53 //
54 // where xp and yp are computed as follows:
55 //
56 // * If we are reading or writing a scanline-based file:
57 //
58 // xp = x
59 // yp = y
60 //
61 // * If we are reading a tile whose upper left coorner is at (xt, yt):
62 //
63 // if xTileCoords is true then xp = x - xt, else xp = x
64 // if yTileCoords is true then yp = y - yt, else yp = y
65 //
66 //---------------------------------------------------------------------
67
68 char * base;
69 size_t xStride;
70 size_t yStride;
71
72
73 //--------------------------------------------
74 // Subsampling: pixel (x, y) is present in the
75 // slice only if
76 //
77 // x % xSampling == 0 && y % ySampling == 0
78 //
79 //--------------------------------------------
80
81 int xSampling;
82 int ySampling;
83
84
85 //----------------------------------------------------------
86 // Default value, used to fill the slice when a file without
87 // a channel that corresponds to this slice is read.
88 //----------------------------------------------------------
89
90 double fillValue;
91
92
93 //-------------------------------------------------------
94 // For tiled files, the xTileCoords and yTileCoords flags
95 // determine whether pixel addressing is performed using
96 // absolute coordinates or coordinates relative to a
97 // tile's upper left corner. (See the comment on base,
98 // xStride and yStride, above.)
99 //
100 // For scanline-based files these flags have no effect;
101 // pixel addressing is always done using absolute
102 // coordinates.
103 //-------------------------------------------------------
104
105 bool xTileCoords;
106 bool yTileCoords;
107
108
109 //------------
110 // Constructor
111 //------------
112
113 IMF_EXPORT
114 Slice (PixelType type = HALF,
115 char * base = 0,
116 size_t xStride = 0,
117 size_t yStride = 0,
118 int xSampling = 1,
119 int ySampling = 1,
120 double fillValue = 0.0,
121 bool xTileCoords = false,
122 bool yTileCoords = false);
123
124 // Does the heavy lifting of computing the base pointer for a slice,
125 // avoiding overflow issues with large origin offsets
126 //
127 // if xStride == 0, assumes sizeof(pixeltype)
128 // if yStride == 0, assumes xStride * ( w / xSampling )
129 IMF_EXPORT
130 static Slice Make(PixelType type,
131 const void *ptr,
132 const IMATH_NAMESPACE::V2i &origin,
133 int64_t w,
134 int64_t h,
135 size_t xStride = 0,
136 size_t yStride = 0,
137 int xSampling = 1,
138 int ySampling = 1,
139 double fillValue = 0.0,
140 bool xTileCoords = false,
141 bool yTileCoords = false);
142 // same as above, just computes w and h for you
143 // from a data window
144 IMF_EXPORT
145 static Slice Make(PixelType type,
146 const void *ptr,
147 const IMATH_NAMESPACE::Box2i &dataWindow,
148 size_t xStride = 0,
149 size_t yStride = 0,
150 int xSampling = 1,
151 int ySampling = 1,
152 double fillValue = 0.0,
153 bool xTileCoords = false,
154 bool yTileCoords = false);
155};
156
157
158class IMF_EXPORT_TYPE FrameBuffer
159{
160 public:
161
162 //------------
163 // Add a slice
164 //------------
165
166 IMF_EXPORT
167 void insert (const char name[],
168 const Slice &slice);
169
170 IMF_EXPORT
171 void insert (const std::string &name,
172 const Slice &slice);
173
174 //----------------------------------------------------------------
175 // Access to existing slices:
176 //
177 // [n] Returns a reference to the slice with name n.
178 // If no slice with name n exists, an IEX_NAMESPACE::ArgExc
179 // is thrown.
180 //
181 // findSlice(n) Returns a pointer to the slice with name n,
182 // or 0 if no slice with name n exists.
183 //
184 //----------------------------------------------------------------
185
186 IMF_EXPORT
187 Slice & operator [] (const char name[]);
188 IMF_EXPORT
189 const Slice & operator [] (const char name[]) const;
190
191 IMF_EXPORT
192 Slice & operator [] (const std::string &name);
193 IMF_EXPORT
194 const Slice & operator [] (const std::string &name) const;
195
196 IMF_EXPORT
197 Slice * findSlice (const char name[]);
198 IMF_EXPORT
199 const Slice * findSlice (const char name[]) const;
200
201 IMF_EXPORT
202 Slice * findSlice (const std::string &name);
203 IMF_EXPORT
204 const Slice * findSlice (const std::string &name) const;
205
206
207 //-----------------------------------------
208 // Iterator-style access to existing slices
209 //-----------------------------------------
210
211 typedef std::map <Name, Slice> SliceMap;
212
213 class Iterator;
214 class ConstIterator;
215
216 IMF_EXPORT
217 Iterator begin ();
218 IMF_EXPORT
219 ConstIterator begin () const;
220
221 IMF_EXPORT
222 Iterator end ();
223 IMF_EXPORT
224 ConstIterator end () const;
225
226 IMF_EXPORT
227 Iterator find (const char name[]);
228 IMF_EXPORT
229 ConstIterator find (const char name[]) const;
230
231 IMF_EXPORT
232 Iterator find (const std::string &name);
233 IMF_EXPORT
234 ConstIterator find (const std::string &name) const;
235
236 private:
237
238 SliceMap _map;
239};
240
241
242//----------
243// Iterators
244//----------
245
246class IMF_EXPORT_TYPE FrameBuffer::Iterator
247{
248 public:
249
250 IMF_EXPORT
251 Iterator ();
252 IMF_EXPORT
253 Iterator (const FrameBuffer::SliceMap::iterator &i);
254
255 IMF_EXPORT
256 Iterator & operator ++ ();
257 IMF_EXPORT
258 Iterator operator ++ (int);
259
260 IMF_EXPORT
261 const char * name () const;
262 IMF_EXPORT
263 Slice & slice () const;
264
265 private:
266
267 friend class FrameBuffer::ConstIterator;
268
269 FrameBuffer::SliceMap::iterator _i;
270};
271
272
273class IMF_EXPORT_TYPE FrameBuffer::ConstIterator
274{
275 public:
276
277 IMF_EXPORT
278 ConstIterator ();
279 IMF_EXPORT
280 ConstIterator (const FrameBuffer::SliceMap::const_iterator &i);
281 IMF_EXPORT
282 ConstIterator (const FrameBuffer::Iterator &other);
283
284 IMF_EXPORT
285 ConstIterator & operator ++ ();
286 IMF_EXPORT
287 ConstIterator operator ++ (int);
288
289 IMF_EXPORT
290 const char * name () const;
291 IMF_EXPORT
292 const Slice & slice () const;
293
294 private:
295
296 friend bool operator == (const ConstIterator &, const ConstIterator &);
297 friend bool operator != (const ConstIterator &, const ConstIterator &);
298
299 FrameBuffer::SliceMap::const_iterator _i;
300};
301
302
303//-----------------
304// Inline Functions
305//-----------------
306
307inline
308FrameBuffer::Iterator::Iterator (): _i()
309{
310 // empty
311}
312
313
314inline
315FrameBuffer::Iterator::Iterator (const FrameBuffer::SliceMap::iterator &i):
316 _i (i)
317{
318 // empty
319}
320
321
322inline FrameBuffer::Iterator &
323FrameBuffer::Iterator::operator ++ ()
324{
325 ++_i;
326 return *this;
327}
328
329
330inline FrameBuffer::Iterator
331FrameBuffer::Iterator::operator ++ (int)
332{
333 Iterator tmp = *this;
334 ++_i;
335 return tmp;
336}
337
338
339inline const char *
340FrameBuffer::Iterator::name () const
341{
342 return *_i->first;
343}
344
345
346inline Slice &
347FrameBuffer::Iterator::slice () const
348{
349 return _i->second;
350}
351
352
353inline
354FrameBuffer::ConstIterator::ConstIterator (): _i()
355{
356 // empty
357}
358
359inline
360FrameBuffer::ConstIterator::ConstIterator
361 (const FrameBuffer::SliceMap::const_iterator &i): _i (i)
362{
363 // empty
364}
365
366
367inline
368FrameBuffer::ConstIterator::ConstIterator (const FrameBuffer::Iterator &other):
369 _i (other._i)
370{
371 // empty
372}
373
374inline FrameBuffer::ConstIterator &
375FrameBuffer::ConstIterator::operator ++ ()
376{
377 ++_i;
378 return *this;
379}
380
381
382inline FrameBuffer::ConstIterator
383FrameBuffer::ConstIterator::operator ++ (int)
384{
385 ConstIterator tmp = *this;
386 ++_i;
387 return tmp;
388}
389
390
391inline const char *
392FrameBuffer::ConstIterator::name () const
393{
394 return *_i->first;
395}
396
397inline const Slice &
398FrameBuffer::ConstIterator::slice () const
399{
400 return _i->second;
401}
402
403
404inline bool
405operator == (const FrameBuffer::ConstIterator &x,
406 const FrameBuffer::ConstIterator &y)
407{
408 return x._i == y._i;
409}
410
411
412inline bool
413operator != (const FrameBuffer::ConstIterator &x,
414 const FrameBuffer::ConstIterator &y)
415{
416 return !(x == y);
417}
418
419
420OPENEXR_IMF_INTERNAL_NAMESPACE_HEADER_EXIT
421
422#endif
423

source code of include/OpenEXR/ImfFrameBuffer.h