Overte C++ Documentation
State.h
1 //
2 // State
3 // libraries/gpu/src/gpu
4 //
5 // Created by Sam Gateau on 3/8/2015.
6 // Copyright 2014 High Fidelity, Inc.
7 //
8 // Distributed under the Apache License, Version 2.0.
9 // See the accompanying file LICENSE or http://www.apache.org/licenses/LICENSE-2.0.html
10 //
11 #ifndef hifi_gpu_State_h
12 #define hifi_gpu_State_h
13 
14 #include "Format.h"
15 
16 #include <memory>
17 #include <sstream>
18 #include <vector>
19 #include <unordered_map>
20 #include <bitset>
21 #include <QString>
22 
23 #include "Sampler.h"
24 
25 // Why a macro and not a fancy template you will ask me ?
26 // Because some of the fields are bool packed tightly in the State::Cache class
27 // and it s just not good anymore for template T& variable manipulation...
28 #define SET_FIELD(FIELD, PATH, value) \
29  { \
30  _values.PATH = value; \
31  if (value == DEFAULT.PATH) { \
32  _signature.reset(FIELD); \
33  } else { \
34  _signature.set(FIELD); \
35  } \
36  _stamp++; \
37  }
38 
39 namespace gpu {
40 
41 class GPUObject;
42 
43 class State {
44 public:
45  State();
46  State(const State& state) : _values(state._values), _signature(state._signature), _stamp(state._stamp) {}
47  virtual ~State();
48 
49  Stamp getStamp() const { return _stamp; }
50 
51  enum FillMode
52  {
53  FILL_POINT = 0,
54  FILL_LINE,
55  FILL_FACE,
56 
57  NUM_FILL_MODES,
58  };
59 
60  enum CullMode
61  {
62  CULL_NONE = 0,
63  CULL_FRONT,
64  CULL_BACK,
65 
66  NUM_CULL_MODES,
67  };
68 
69  enum StencilOp
70  {
71  STENCIL_OP_KEEP = 0,
72  STENCIL_OP_ZERO,
73  STENCIL_OP_REPLACE,
74  STENCIL_OP_INCR_SAT,
75  STENCIL_OP_DECR_SAT,
76  STENCIL_OP_INVERT,
77  STENCIL_OP_INCR,
78  STENCIL_OP_DECR,
79 
80  NUM_STENCIL_OPS,
81  };
82 
83  enum BlendArg
84  {
85  ZERO = 0,
86  ONE,
87  SRC_COLOR,
88  INV_SRC_COLOR,
89  SRC_ALPHA,
90  INV_SRC_ALPHA,
91  DEST_ALPHA,
92  INV_DEST_ALPHA,
93  DEST_COLOR,
94  INV_DEST_COLOR,
95  SRC_ALPHA_SAT,
96  FACTOR_COLOR,
97  INV_FACTOR_COLOR,
98  FACTOR_ALPHA,
99  INV_FACTOR_ALPHA,
100 
101  NUM_BLEND_ARGS,
102  };
103 
104  enum BlendOp
105  {
106  BLEND_OP_ADD = 0,
107  BLEND_OP_SUBTRACT,
108  BLEND_OP_REV_SUBTRACT,
109  BLEND_OP_MIN,
110  BLEND_OP_MAX,
111 
112  NUM_BLEND_OPS,
113  };
114 
115  enum ColorMask
116  {
117  WRITE_NONE = 0,
118  WRITE_RED = 1,
119  WRITE_GREEN = 2,
120  WRITE_BLUE = 4,
121  WRITE_ALPHA = 8,
122  WRITE_ALL = (WRITE_RED | WRITE_GREEN | WRITE_BLUE | WRITE_ALPHA),
123  };
124 
125  class DepthTest {
126  public:
127  uint8 writeMask{ true };
128  uint8 enabled{ false };
129  ComparisonFunction function{ ComparisonFunction::LESS };
130 
131  public:
132  DepthTest(bool enabled = false, bool writeMask = true, ComparisonFunction func = ComparisonFunction::LESS) :
133  writeMask(writeMask), enabled(enabled), function(func) {}
134 
135  bool isEnabled() const { return enabled != 0; }
136  ComparisonFunction getFunction() const { return function; }
137  uint8 getWriteMask() const { return writeMask; }
138 
139  bool operator==(const DepthTest& right) const {
140  return
141  writeMask == right.writeMask &&
142  enabled == right.enabled &&
143  function == right.function;
144  }
145 
146  bool operator!=(const DepthTest& right) const {
147  return !(*this == right);
148  }
149 
150  operator QString() const {
151  return QString("{ writeMask = %1, enabled = %2, function = %3 }").arg(writeMask).arg(enabled).arg((uint8_t)function);
152  }
153  };
154 
155  struct StencilTest {
156  ComparisonFunction function;
157  StencilOp failOp;
158  StencilOp depthFailOp;
159  StencilOp passOp;
160  int8 reference{ 0 };
161  uint8 readMask{ 0xff };
162 
163  public:
164  StencilTest(int8 reference = 0,
165  uint8 readMask = 0xFF,
166  ComparisonFunction func = ComparisonFunction::ALWAYS,
167  StencilOp failOp = STENCIL_OP_KEEP,
168  StencilOp depthFailOp = STENCIL_OP_KEEP,
169  StencilOp passOp = STENCIL_OP_KEEP) :
170  function(func),
171  failOp(failOp), depthFailOp(depthFailOp), passOp(passOp), reference(reference), readMask(readMask) {}
172 
173  ComparisonFunction getFunction() const { return function; }
174  StencilOp getFailOp() const { return failOp; }
175  StencilOp getDepthFailOp() const { return depthFailOp; }
176  StencilOp getPassOp() const { return passOp; }
177 
178  int8 getReference() const { return reference; }
179  uint8 getReadMask() const { return readMask; }
180 
181  bool operator==(const StencilTest& right) const {
182  return
183  function == right.function &&
184  failOp == right.failOp &&
185  depthFailOp == right.depthFailOp &&
186  passOp == right.passOp &&
187  reference == right.reference &&
188  readMask == right.readMask;
189 
190  }
191 
192  bool operator!=(const StencilTest &right) const { return !(right==*this); }
193  };
194 
195  StencilTest stencilTestFront;
196 
197  struct StencilActivation {
198  uint8 frontWriteMask = 0xFF;
199  uint8 backWriteMask = 0xFF;
200  bool enabled;
201 
202  public:
203  StencilActivation(bool enabled = false, uint8 frontWriteMask = 0xFF, uint8 backWriteMask = 0xFF) :
204  frontWriteMask(frontWriteMask), backWriteMask(backWriteMask), enabled(enabled) {}
205 
206  bool isEnabled() const { return enabled; }
207  uint8 getWriteMaskFront() const { return frontWriteMask; }
208  uint8 getWriteMaskBack() const { return backWriteMask; }
209 
210  bool operator==(const StencilActivation& right) const {
211  return
212  frontWriteMask == right.frontWriteMask &&
213  backWriteMask == right.backWriteMask &&
214  enabled == right.enabled;
215  }
216 
217  bool operator!=(const StencilActivation& right) const {
218  return !(*this == right);
219  }
220  };
221 
222  struct BlendFunction {
223  // Using uint8 here will make the structure as a whole not align to 32 bits
224  uint16 enabled;
225  BlendArg sourceColor;
226  BlendArg sourceAlpha;
227  BlendArg destColor;
228  BlendArg destAlpha;
229  BlendOp opColor;
230  BlendOp opAlpha;
231 
232  public:
233  BlendFunction(bool enabled,
234  BlendArg sourceColor,
235  BlendOp operationColor,
236  BlendArg destinationColor,
237  BlendArg sourceAlpha,
238  BlendOp operationAlpha,
239  BlendArg destinationAlpha) :
240  enabled(enabled),
241  sourceColor(sourceColor), sourceAlpha(sourceAlpha),
242  destColor(destinationColor), destAlpha(destinationAlpha),
243  opColor(operationColor), opAlpha(operationAlpha) {}
244 
245  BlendFunction(bool enabled = false, BlendArg source = ONE, BlendOp operation = BLEND_OP_ADD, BlendArg destination = ZERO) :
246  BlendFunction(enabled, source, operation, destination, source, operation, destination) {}
247 
248  bool isEnabled() const { return (enabled != 0); }
249 
250  BlendArg getSourceColor() const { return sourceColor; }
251  BlendArg getDestinationColor() const { return destColor; }
252  BlendOp getOperationColor() const { return opColor; }
253 
254  BlendArg getSourceAlpha() const { return sourceAlpha; }
255  BlendArg getDestinationAlpha() const { return destAlpha; }
256  BlendOp getOperationAlpha() const { return opAlpha; }
257 
258  bool operator==(const BlendFunction& right) const {
259  return
260  enabled == right.enabled &&
261  sourceColor == right.sourceColor &&
262  sourceAlpha == right.sourceAlpha &&
263  destColor == right.destColor &&
264  destAlpha == right.destAlpha &&
265  opColor == right.opColor &&
266  opAlpha == right.opAlpha;
267 
268  }
269 
270  bool operator!=(const BlendFunction& right) const {
271  return !(*this == right);
272  }
273  };
274 
275  struct Flags {
276  Flags() :
277  frontFaceClockwise(false), depthClampEnable(false), scissorEnable(false), multisampleEnable(false),
278  antialisedLineEnable(true), alphaToCoverageEnable(false) {}
279  bool frontFaceClockwise;
280  bool depthClampEnable;
281  bool scissorEnable;
282  bool multisampleEnable;
283  bool antialisedLineEnable;
284  bool alphaToCoverageEnable;
285 
286 
287  bool operator==(const Flags& right) const {
288  return
289  frontFaceClockwise == right.frontFaceClockwise &&
290  depthClampEnable == right.depthClampEnable &&
291  scissorEnable == right.scissorEnable &&
292  multisampleEnable == right.multisampleEnable &&
293  antialisedLineEnable == right.antialisedLineEnable &&
294  alphaToCoverageEnable == right.alphaToCoverageEnable;
295 
296  }
297 
298  bool operator!=(const Flags& right) const {
299  return !(*this == right);
300  }
301  };
302 
303  // The Data class is the full explicit description of the State class fields value.
304  // Useful for having one const static called Default for reference or for the gpu::Backend to keep track of the current value
305  class Data {
306  public:
307  float depthBias = 0.0f;
308  float depthBiasSlopeScale = 0.0f;
309 
310  DepthTest depthTest;
311  StencilActivation stencilActivation;
312  StencilTest stencilTestFront;
313  StencilTest stencilTestBack;
314  uint32 sampleMask = 0xFFFFFFFF;
315  BlendFunction blendFunction;
316  FillMode fillMode{ FILL_FACE };
317  CullMode cullMode{ CULL_NONE };
318  ColorMask colorWriteMask{ WRITE_ALL };
319 
320  Flags flags;
321  };
322  std::string getKey() const;
323 
324  // The unique default values for all the fields
325  static const Data DEFAULT;
326  void setFillMode(FillMode fill) { SET_FIELD(FILL_MODE, fillMode, fill); }
327  FillMode getFillMode() const { return _values.fillMode; }
328 
329  void setCullMode(CullMode cull) { SET_FIELD(CULL_MODE, cullMode, cull); }
330  CullMode getCullMode() const { return _values.cullMode; }
331 
332  const Flags& getFlags() const { return _values.flags; }
333 
334  void setFrontFaceClockwise(bool isClockwise) { SET_FIELD(FRONT_FACE_CLOCKWISE, flags.frontFaceClockwise, isClockwise); }
335  bool isFrontFaceClockwise() const { return _values.flags.frontFaceClockwise; }
336 
337  void setDepthClampEnable(bool enable) { SET_FIELD(DEPTH_CLAMP_ENABLE, flags.depthClampEnable, enable); }
338  bool isDepthClampEnable() const { return _values.flags.depthClampEnable; }
339 
340  void setScissorEnable(bool enable) { SET_FIELD(SCISSOR_ENABLE, flags.scissorEnable, enable); }
341  bool isScissorEnable() const { return _values.flags.scissorEnable; }
342 
343  void setMultisampleEnable(bool enable) { SET_FIELD(MULTISAMPLE_ENABLE, flags.multisampleEnable, enable); }
344  bool isMultisampleEnable() const { return _values.flags.multisampleEnable; }
345 
346  void setAntialiasedLineEnable(bool enable) { SET_FIELD(ANTIALISED_LINE_ENABLE, flags.antialisedLineEnable, enable); }
347  bool isAntialiasedLineEnable() const { return _values.flags.antialisedLineEnable; }
348 
349  // Depth Bias
350  void setDepthBias(float bias) { SET_FIELD(DEPTH_BIAS, depthBias, bias); }
351  float getDepthBias() const { return _values.depthBias; }
352 
353  void setDepthBiasSlopeScale(float scale) { SET_FIELD(DEPTH_BIAS_SLOPE_SCALE, depthBiasSlopeScale, scale); }
354  float getDepthBiasSlopeScale() const { return _values.depthBiasSlopeScale; }
355 
356  // Depth Test
357  void setDepthTest(DepthTest newDepthTest) { SET_FIELD(DEPTH_TEST, depthTest, newDepthTest); }
358  void setDepthTest(bool enable, bool writeMask, ComparisonFunction func) {
359  setDepthTest(DepthTest(enable, writeMask, func));
360  }
361  DepthTest getDepthTest() const { return _values.depthTest; }
362 
363  bool isDepthTestEnabled() const { return getDepthTest().isEnabled(); }
364  uint8 getDepthTestWriteMask() const { return getDepthTest().getWriteMask(); }
365  ComparisonFunction getDepthTestFunc() const { return getDepthTest().getFunction(); }
366 
367  // Stencil test
368  void setStencilTest(bool enabled, uint8 frontWriteMask, StencilTest frontTest, uint8 backWriteMask, StencilTest backTest) {
369  SET_FIELD(STENCIL_ACTIVATION, stencilActivation, StencilActivation(enabled, frontWriteMask, backWriteMask));
370  SET_FIELD(STENCIL_TEST_FRONT, stencilTestFront, frontTest);
371  SET_FIELD(STENCIL_TEST_BACK, stencilTestBack, backTest);
372  }
373 
374  void setStencilTest(bool enabled, uint8 frontWriteMask, StencilTest frontTest) {
375  setStencilTest(enabled, frontWriteMask, frontTest, frontWriteMask, frontTest);
376  }
377 
378  StencilActivation getStencilActivation() const { return _values.stencilActivation; }
379  StencilTest getStencilTestFront() const { return _values.stencilTestFront; }
380  StencilTest getStencilTestBack() const { return _values.stencilTestBack; }
381 
382  bool isStencilEnabled() const { return getStencilActivation().isEnabled(); }
383  uint8 getStencilWriteMaskFront() const { return getStencilActivation().getWriteMaskFront(); }
384  uint8 getStencilWriteMaskBack() const { return getStencilActivation().getWriteMaskBack(); }
385 
386  // Alpha to coverage
387  void setAlphaToCoverageEnable(bool enable) { SET_FIELD(ALPHA_TO_COVERAGE_ENABLE, flags.alphaToCoverageEnable, enable); }
388  bool isAlphaToCoverageEnabled() const { return _values.flags.alphaToCoverageEnable; }
389 
390  // Sample mask
391  void setSampleMask(uint32 mask) { SET_FIELD(SAMPLE_MASK, sampleMask, mask); }
392  uint32 getSampleMask() const { return _values.sampleMask; }
393 
394  // Blend Function
395  void setBlendFunction(BlendFunction function) { SET_FIELD(BLEND_FUNCTION, blendFunction, function); }
396  const BlendFunction& getBlendFunction() const { return _values.blendFunction; }
397 
398  void setBlendFunction(bool enabled,
399  BlendArg sourceColor,
400  BlendOp operationColor,
401  BlendArg destinationColor,
402  BlendArg sourceAlpha,
403  BlendOp operationAlpha,
404  BlendArg destinationAlpha) {
405  setBlendFunction(BlendFunction(enabled, sourceColor, operationColor, destinationColor, sourceAlpha, operationAlpha,
406  destinationAlpha));
407  }
408  void setBlendFunction(bool enabled, BlendArg source, BlendOp operation, BlendArg destination) {
409  setBlendFunction(BlendFunction(enabled, source, operation, destination));
410  }
411 
412  bool isBlendEnabled() const { return getBlendFunction().isEnabled(); }
413 
414  // Color write mask
415  void setColorWriteMask(ColorMask mask) { SET_FIELD(COLOR_WRITE_MASK, colorWriteMask, mask); }
416  void setColorWriteMask(bool red, bool green, bool blue, bool alpha) {
417  ColorMask value = (ColorMask)((WRITE_RED * red) | (WRITE_GREEN * green) | (WRITE_BLUE * blue) | (WRITE_ALPHA * alpha));
418  SET_FIELD(COLOR_WRITE_MASK, colorWriteMask, value);
419  }
420  ColorMask getColorWriteMask() const { return _values.colorWriteMask; }
421 
422  // All the possible fields
423  // NOTE: If you change this, you must update GLBackend::GLState::_resetStateCommands
424  enum Field
425  {
426  FILL_MODE,
427  CULL_MODE,
428  FRONT_FACE_CLOCKWISE,
429  DEPTH_CLAMP_ENABLE,
430  SCISSOR_ENABLE,
431  MULTISAMPLE_ENABLE,
432  ANTIALISED_LINE_ENABLE,
433 
434  DEPTH_BIAS,
435  DEPTH_BIAS_SLOPE_SCALE,
436 
437  DEPTH_TEST,
438 
439  STENCIL_ACTIVATION,
440  STENCIL_TEST_FRONT,
441  STENCIL_TEST_BACK,
442 
443  SAMPLE_MASK,
444 
445  ALPHA_TO_COVERAGE_ENABLE,
446 
447  BLEND_FUNCTION,
448 
449  COLOR_WRITE_MASK,
450 
451  NUM_FIELDS, // not a valid field, just the count
452  };
453 
454  // The signature of the state tells which fields of the state are not default
455  // this way during rendering the Backend can compare it's current state and try to minimize the job to do
456  typedef std::bitset<NUM_FIELDS> Signature;
457 
458  Signature getSignature() const { return _signature; }
459 
460  static Signature evalSignature(const Data& state);
461 
462  // For convenience, create a State from the values directly
463  State(const Data& values);
464  const Data& getValues() const { return _values; }
465 
466  const GPUObjectPointer gpuObject{};
467 
468 protected:
469  State& operator=(const State& state);
470 
471  Data _values;
472  Signature _signature{ 0 };
473  Stamp _stamp{ 0 };
474 };
475 
476 typedef std::shared_ptr<State> StatePointer;
477 typedef std::vector<StatePointer> States;
478 
479 }; // namespace gpu
480 
481 #endif