HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
paramlist.h
Go to the documentation of this file.
1 /*
2  Copyright 2008 Larry Gritz and the other authors and contributors.
3  All Rights Reserved.
4 
5  Redistribution and use in source and binary forms, with or without
6  modification, are permitted provided that the following conditions are
7  met:
8  * Redistributions of source code must retain the above copyright
9  notice, this list of conditions and the following disclaimer.
10  * Redistributions in binary form must reproduce the above copyright
11  notice, this list of conditions and the following disclaimer in the
12  documentation and/or other materials provided with the distribution.
13  * Neither the name of the software's owners nor the names of its
14  contributors may be used to endorse or promote products derived from
15  this software without specific prior written permission.
16  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
17  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
18  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
19  A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
20  OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
21  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
22  LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
23  DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
24  THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
25  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
26  OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
27 
28  (This is the Modified BSD License)
29 */
30 
31 
32 /// \file
33 ///
34 /// Define the ParamValue and ParamValueList classes, which are used to
35 /// store lists of arbitrary name/data pairs for internal storage of
36 /// parameter lists, attributes, geometric primitive data, etc.
37 
38 
39 #pragma once
40 
41 #include <vector>
42 
43 #include <OpenImageIO/export.h>
44 #include <OpenImageIO/typedesc.h>
45 #include <OpenImageIO/ustring.h>
46 
47 
49 
50 /// ParamValue holds a parameter and a pointer to its value(s)
51 ///
52 /// Nomenclature: if you have an array of 4 colors for each of 15 points...
53 /// - There are 15 VALUES
54 /// - Each value has an array of 4 ELEMENTS, each of which is a color
55 /// - A color has 3 COMPONENTS (R, G, B)
56 ///
58 public:
59  /// Interpolation types
60  ///
61  enum Interp {
62  INTERP_CONSTANT = 0, ///< Constant for all pieces/faces
63  INTERP_PERPIECE = 1, ///< Piecewise constant per piece/face
64  INTERP_LINEAR = 2, ///< Linearly interpolated across each piece/face
65  INTERP_VERTEX = 3 ///< Interpolated like vertices
66  };
67 
68  ParamValue() { m_data.ptr = nullptr; }
69  ParamValue(const ustring& _name, TypeDesc _type, int _nvalues,
70  const void* _value, bool _copy = true)
71  {
72  init_noclear(_name, _type, _nvalues, _value, _copy);
73  }
74  ParamValue(const ustring& _name, TypeDesc _type, int _nvalues,
75  Interp _interp, const void* _value, bool _copy = true)
76  {
77  init_noclear(_name, _type, _nvalues, _interp, _value, _copy);
78  }
79  ParamValue(string_view _name, TypeDesc _type, int _nvalues,
80  const void* _value, bool _copy = true)
81  {
82  init_noclear(ustring(_name), _type, _nvalues, _value, _copy);
83  }
84  ParamValue(string_view _name, TypeDesc _type, int _nvalues, Interp _interp,
85  const void* _value, bool _copy = true)
86  {
87  init_noclear(ustring(_name), _type, _nvalues, _interp, _value, _copy);
88  }
90  {
91  init_noclear(ustring(_name), TypeDesc::INT, 1, &value);
92  }
94  {
95  init_noclear(ustring(_name), TypeDesc::FLOAT, 1, &value);
96  }
98  {
99  init_noclear(ustring(_name), TypeDesc::STRING, 1, &value);
100  }
102  {
103  ustring u(value);
104  init_noclear(ustring(_name), TypeDesc::STRING, 1, &u);
105  }
106 
107  // Set from string -- parse
109 
110  // Copy constructor
112  {
113  init_noclear(p.name(), p.type(), p.nvalues(), p.interp(), p.data(),
114  true);
115  }
116  ParamValue(const ParamValue& p, bool _copy)
117  {
118  init_noclear(p.name(), p.type(), p.nvalues(), p.interp(), p.data(),
119  _copy);
120  }
121 
122  // Rvalue (move) constructor
124  {
125  init_noclear(p.name(), p.type(), p.nvalues(), p.interp(), p.data(),
126  false);
127  m_copy = p.m_copy;
128  m_nonlocal = p.m_nonlocal;
129  p.m_data.ptr = nullptr; // make sure the old one won't free
130  }
131 
132  ~ParamValue() { clear_value(); }
133 
134  void init(ustring _name, TypeDesc _type, int _nvalues, Interp _interp,
135  const void* _value, bool _copy = true)
136  {
137  clear_value();
138  init_noclear(_name, _type, _nvalues, _interp, _value, _copy);
139  }
140  void init(ustring _name, TypeDesc _type, int _nvalues, const void* _value,
141  bool _copy = true)
142  {
143  init(_name, _type, _nvalues, INTERP_CONSTANT, _value, _copy);
144  }
145  void init(string_view _name, TypeDesc _type, int _nvalues,
146  const void* _value, bool _copy = true)
147  {
148  init(ustring(_name), _type, _nvalues, _value, _copy);
149  }
150  void init(string_view _name, TypeDesc _type, int _nvalues, Interp _interp,
151  const void* _value, bool _copy = true)
152  {
153  init(ustring(_name), _type, _nvalues, _interp, _value, _copy);
154  }
155 
156  // Assignment
158  {
159  if (this != &p)
160  init(p.name(), p.type(), p.nvalues(), p.interp(), p.data(),
161  p.m_copy);
162  return *this;
163  }
165  {
166  if (this != &p) {
167  init(p.name(), p.type(), p.nvalues(), p.interp(), p.data(), false);
168  m_copy = p.m_copy;
169  m_nonlocal = p.m_nonlocal;
170  p.m_data.ptr = nullptr;
171  }
172  return *this;
173  }
174 
175  // FIXME -- some time in the future (after more cleanup), we should make
176  // name() return a string_view, and use uname() for the rare time when
177  // the caller truly requires the ustring.
178  const ustring& name() const { return m_name; }
179  const ustring& uname() const { return m_name; }
180  TypeDesc type() const { return m_type; }
181  int nvalues() const { return m_nvalues; }
182  const void* data() const { return m_nonlocal ? m_data.ptr : &m_data; }
183  int datasize() const { return m_nvalues * static_cast<int>(m_type.size()); }
184  Interp interp() const { return (Interp)m_interp; }
185  void interp(Interp i) { m_interp = (unsigned char)i; }
186  bool is_nonlocal() const { return m_nonlocal; }
187 
188  friend void swap(ParamValue& a, ParamValue& b)
189  {
190  auto tmp = std::move(a);
191  a = std::move(b);
192  b = std::move(tmp);
193  }
194 
195  // Use with extreme caution! This is just doing a cast. You'd better
196  // be really sure you are asking for the right type. Note that for
197  // "string" data, you can get<ustring> or get<char*>, but it's not
198  // a std::string.
199  template<typename T> const T& get(int i = 0) const
200  {
201  return (reinterpret_cast<const T*>(data()))[i];
202  }
203 
204  /// Retrive an integer, with converstions from a wide variety of type
205  /// cases, including unsigned, short, byte. Not float. It will retrive
206  /// from a string, but only if the string is entirely a valid int
207  /// format. Unconvertable types return the default value.
208  int get_int(int defaultval = 0) const;
209  int get_int_indexed(int index, int defaultval = 0) const;
210 
211  /// Retrive a float, with converstions from a wide variety of type
212  /// cases, including integers. It will retrive from a string, but only
213  /// if the string is entirely a valid float format. Unconvertable types
214  /// return the default value.
215  float get_float(float defaultval = 0) const;
216  float get_float_indexed(int index, float defaultval = 0) const;
217 
218  /// Convert any type to a string value. An optional maximum number of
219  /// elements is also passed. In the case of a single string, just the
220  /// string directly is returned. But for an array of strings, the array
221  /// is returned as one string that's a comma-separated list of double-
222  /// quoted, escaped strings.
223  std::string get_string(int maxsize = 64) const;
224  /// Convert any type to a ustring value. An optional maximum number of
225  /// elements is also passed. Same behavior as get_string, but returning
226  /// a ustring.
227  ustring get_ustring(int maxsize = 64) const;
228 
229 private:
230  ustring m_name; ///< data name
231  TypeDesc m_type; ///< data type, which may itself be an array
232  union {
233  char localval[16];
234  const void* ptr;
235  } m_data; ///< Our data, either a pointer or small local value
236  int m_nvalues = 0; ///< number of values of the given type
237  unsigned char m_interp = INTERP_CONSTANT; ///< Interpolation type
238  bool m_copy = false;
239  bool m_nonlocal = false;
240 
241  void init_noclear(ustring _name, TypeDesc _type, int _nvalues,
242  const void* _value, bool _copy = true);
243  void init_noclear(ustring _name, TypeDesc _type, int _nvalues,
244  Interp _interp, const void* _value, bool _copy = true);
245  void clear_value();
246 };
247 
248 
249 
250 /// A list of ParamValue entries, that can be iterated over or searched.
251 /// It's really just a std::vector<ParamValue>, but with a few more handy
252 /// methods.
253 class OIIO_API ParamValueList : public std::vector<ParamValue> {
254 public:
256 
257  /// Add space for one more ParamValue to the list, and return a
258  /// reference to its slot.
260  {
261  resize(size() + 1);
262  return back();
263  }
264 
265  /// Find the first entry with matching name, and if type != UNKNOWN,
266  /// then also with matching type. The name search is case sensitive if
267  /// casesensitive == true.
269  bool casesensitive = true);
271  bool casesensitive = true);
273  bool casesensitive = true) const;
274  const_iterator find(ustring name, TypeDesc type = TypeDesc::UNKNOWN,
275  bool casesensitive = true) const;
276 
277  /// Case insensitive search for an integer, with default if not found.
278  /// Automatically will return an int even if the data is really
279  /// unsigned, short, or byte, but not float. It will retrive from a
280  /// string, but only if the string is entirely a valid int format.
281  int get_int(string_view name, int defaultval = 0,
282  bool casesensitive = false, bool convert = true) const;
283 
284  /// Case insensitive search for a float, with default if not found.
285  /// Automatically will return a float even if the data is really double
286  /// or half. It will retrive from a string, but only if the string is
287  /// entirely a valid float format.
288  float get_float(string_view name, float defaultval = 0,
289  bool casesensitive = false, bool convert = true) const;
290 
291  /// Simple way to get a string attribute, with default provided.
292  /// If the value is another type, it will be turned into a string.
293  string_view get_string(string_view name,
294  string_view defaultval = string_view(),
295  bool casesensitive = false,
296  bool convert = true) const;
297  ustring get_ustring(string_view name,
298  string_view defaultval = string_view(),
299  bool casesensitive = false, bool convert = true) const;
300 
301  /// Remove the named parameter, if it is in the list.
303  bool casesensitive = true);
304 
305  /// Does the list contain the named attribute?
307  bool casesensitive = true);
308 
309  // Add the param to the list, replacing in-place any existing one with
310  // the same name.
311  void add_or_replace(const ParamValue& pv, bool casesensitive = true);
312  void add_or_replace(ParamValue&& pv, bool casesensitive = true);
313 
314  // Sort alphabetically, optionally case-insensitively, locale-
315  // independently, and with all the "un-namespaced" items appearing
316  // first, followed by items with "prefixed namespaces" (e.g. "z" comes
317  // before "foo:a").
318  void sort(bool casesensitive = true);
319 
320  /// Even more radical than clear, free ALL memory associated with the
321  /// list itself.
322  void free()
323  {
324  clear();
325  shrink_to_fit();
326  }
327 };
328 
329 
ParamValue(string_view _name, TypeDesc _type, int _nvalues, const void *_value, bool _copy=true)
Definition: paramlist.h:79
void init(ustring _name, TypeDesc _type, int _nvalues, Interp _interp, const void *_value, bool _copy=true)
Definition: paramlist.h:134
ParamValue(string_view _name, TypeDesc _type, int _nvalues, Interp _interp, const void *_value, bool _copy=true)
Definition: paramlist.h:84
GLsizeiptr size
Definition: glew.h:1681
GLuint const GLchar * name
Definition: glew.h:1814
reference grow()
Definition: paramlist.h:259
ParamValue(string_view _name, ustring value)
Definition: paramlist.h:97
ParamValue(string_view _name, float value)
Definition: paramlist.h:93
GLuint index
Definition: glew.h:1814
ParamValue()
Definition: paramlist.h:68
GLboolean GLboolean GLboolean GLboolean a
Definition: glew.h:9477
bool is_nonlocal() const
Definition: paramlist.h:186
void init(string_view _name, TypeDesc _type, int _nvalues, const void *_value, bool _copy=true)
Definition: paramlist.h:145
int datasize() const
Definition: paramlist.h:183
friend void swap(ParamValue &a, ParamValue &b)
Definition: paramlist.h:188
TypeDesc type() const
Definition: paramlist.h:180
const ustring & uname() const
Definition: paramlist.h:179
void init(ustring _name, TypeDesc _type, int _nvalues, const void *_value, bool _copy=true)
Definition: paramlist.h:140
GLint GLenum GLsizei GLint GLsizei const void * data
Definition: glew.h:1379
ParamValue(ParamValue &&p)
Definition: paramlist.h:123
basic_string_view< char > string_view
Definition: core.h:426
void init(string_view _name, TypeDesc _type, int _nvalues, Interp _interp, const void *_value, bool _copy=true)
Definition: paramlist.h:150
ParamValue(const ParamValue &p, bool _copy)
Definition: paramlist.h:116
ImageBuf OIIO_API resize(const ImageBuf &src, string_view filtername="", float filterwidth=0.0f, ROI roi={}, int nthreads=0)
const ParamValue & operator=(ParamValue &&p)
Definition: paramlist.h:164
void interp(Interp i)
Definition: paramlist.h:185
GLuint GLuint GLsizei GLenum type
Definition: glew.h:1253
const void * data() const
Definition: paramlist.h:182
bool OIIO_API contains(string_view a, string_view b)
Does 'a' contain the string 'b' within it?
GLdouble GLdouble GLdouble b
Definition: glew.h:9122
GLfloat GLfloat p
Definition: glew.h:16321
GLsizei const GLchar *const * string
Definition: glew.h:1844
ParamValue(string_view _name, int value)
Definition: paramlist.h:89
ParamValue(string_view _name, string_view value)
Definition: paramlist.h:101
ParamValue(const ParamValue &p)
Definition: paramlist.h:111
FMT_CONSTEXPR bool find(Ptr first, Ptr last, T value, Ptr &out)
Definition: format.h:2104
const ustring & name() const
Definition: paramlist.h:178
GLenum const void GLuint GLint reference
Definition: glew.h:13644
#define OIIO_NAMESPACE_END
Definition: oiioversion.h:66
ParamValue(const ustring &_name, TypeDesc _type, int _nvalues, const void *_value, bool _copy=true)
Definition: paramlist.h:69
const void * ptr
Definition: paramlist.h:234
GLsizei const GLfloat * value
Definition: glew.h:1849
void sort(I begin, I end, const Pred &pred)
Definition: pugixml.cpp:7334
ParamValue(const ustring &_name, TypeDesc _type, int _nvalues, Interp _interp, const void *_value, bool _copy=true)
Definition: paramlist.h:74
int nvalues() const
Definition: paramlist.h:181
const ParamValue & operator=(const ParamValue &p)
Definition: paramlist.h:157
Interp interp() const
Definition: paramlist.h:184
#define OIIO_NAMESPACE_BEGIN
Definition: oiioversion.h:65
#define OIIO_API
Definition: export.h:91