1 2 /* 3 * Copyright 2011 Google Inc. 4 * 5 * Use of this source code is governed by a BSD-style license that can be 6 * found in the LICENSE file. 7 */ 8 9 10 #ifndef GrStencil_DEFINED 11 #define GrStencil_DEFINED 12 13 #include "GrTypes.h" 14 #include "SkRegion.h" 15 16 /** 17 * Gr uses the stencil buffer to implement complex clipping inside the 18 * GrDrawTarget class. The GrDrawTarget makes a subset of the stencil buffer 19 * bits available for other uses by external code (clients). Client code can 20 * modify these bits. GrDrawTarget will ignore ref, mask, and writemask bits 21 * provided by clients that overlap the bits used to implement clipping. 22 * 23 * When code outside the GrDrawTarget class uses the stencil buffer the contract 24 * is as follows: 25 * 26 * > Normal stencil funcs allow the client to pass / fail regardless of the 27 * reserved clip bits. 28 * > Additional functions allow a test against the clip along with a limited 29 * set of tests against the client bits. 30 * > Client can assume all client bits are zero initially. 31 * > Client must ensure that after all its passes are finished it has only 32 * written to the color buffer in the region inside the clip. Furthermore, it 33 * must zero all client bits that were modifed (both inside and outside the 34 * clip). 35 */ 36 37 /** 38 * Determines which pixels pass / fail the stencil test. 39 * Stencil test passes if (ref & mask) FUNC (stencil & mask) is true 40 */ 41 enum GrStencilFunc { 42 kAlways_StencilFunc = 0, 43 kNever_StencilFunc, 44 kGreater_StencilFunc, 45 kGEqual_StencilFunc, 46 kLess_StencilFunc, 47 kLEqual_StencilFunc, 48 kEqual_StencilFunc, 49 kNotEqual_StencilFunc, 50 51 // Gr stores the current clip in the 52 // stencil buffer in the high bits that 53 // are not directly accessible modifiable 54 // via the GrDrawTarget interface. The below 55 // stencil funcs test against the current 56 // clip in addition to the GrDrawTarget 57 // client's stencil bits. 58 59 // pass if inside the clip 60 kAlwaysIfInClip_StencilFunc, 61 kEqualIfInClip_StencilFunc, 62 kLessIfInClip_StencilFunc, 63 kLEqualIfInClip_StencilFunc, 64 kNonZeroIfInClip_StencilFunc, // this one forces the ref to be 0 65 66 // counts 67 kStencilFuncCount, 68 kClipStencilFuncCount = kNonZeroIfInClip_StencilFunc - 69 kAlwaysIfInClip_StencilFunc + 1, 70 kBasicStencilFuncCount = kStencilFuncCount - kClipStencilFuncCount 71 }; 72 73 /** 74 * Operations to perform based on whether stencil test passed failed. 75 */ 76 enum GrStencilOp { 77 kKeep_StencilOp = 0, // preserve existing stencil value 78 kReplace_StencilOp, // replace with reference value from stencl test 79 kIncWrap_StencilOp, // increment and wrap at max 80 kIncClamp_StencilOp, // increment and clamp at max 81 kDecWrap_StencilOp, // decrement and wrap at 0 82 kDecClamp_StencilOp, // decrement and clamp at 0 83 kZero_StencilOp, // zero stencil bits 84 kInvert_StencilOp, // invert stencil bits 85 86 kStencilOpCount 87 }; 88 89 enum GrStencilFlags { 90 kIsDisabled_StencilFlag = 0x1, 91 kNotDisabled_StencilFlag = 0x2, 92 kDoesWrite_StencilFlag = 0x4, 93 kDoesNotWrite_StencilFlag = 0x8, 94 }; 95 96 /** 97 * GrStencilState needs to be a class with accessors and setters so that it 98 * can maintain flags related to its current state. However, we also want to 99 * be able to declare pre-made stencil settings at compile time (without 100 * inserting static initializer code). So all the data members are in this 101 * struct. A macro defined after the class can be used to jam an instance of 102 * this struct that is created from an initializer list into a 103 * GrStencilSettings. (We hang our heads in shame.) 104 */ 105 struct GrStencilSettingsStruct { 106 uint8_t fPassOps[2]; // op to perform when faces pass (GrStencilOp) 107 uint8_t fFailOps[2]; // op to perform when faces fail (GrStencilOp) 108 uint8_t fFuncs[2]; // test function for faces (GrStencilFunc) 109 uint8_t fPad0; 110 uint8_t fPad1; 111 uint16_t fFuncMasks[2]; // mask for face tests 112 uint16_t fFuncRefs[2]; // reference values for face tests 113 uint16_t fWriteMasks[2]; // stencil write masks 114 mutable uint32_t fFlags; 115 }; 116 // We rely on this being packed and aligned (memcmp'ed and memcpy'ed) 117 GR_STATIC_ASSERT(sizeof(GrStencilSettingsStruct) % 4 == 0); 118 GR_STATIC_ASSERT(sizeof(GrStencilSettingsStruct) == 119 4*sizeof(uint8_t) + // ops 120 2*sizeof(uint8_t) + // funcs 121 2*sizeof(uint8_t) + // pads 122 2*sizeof(uint16_t) + // func masks 123 2*sizeof(uint16_t) + // ref values 124 2*sizeof(uint16_t) + // write masks 125 sizeof(uint32_t)); // flags 126 127 // This macro is used to compute the GrStencilSettingsStructs flags 128 // associated to disabling. It is used both to define constant structure 129 // initializers and inside GrStencilSettings::isDisabled() 130 // 131 #define GR_STENCIL_SETTINGS_IS_DISABLED( \ 132 FRONT_PASS_OP, BACK_PASS_OP, \ 133 FRONT_FAIL_OP, BACK_FAIL_OP, \ 134 FRONT_FUNC, BACK_FUNC) \ 135 ((FRONT_PASS_OP) == kKeep_StencilOp && \ 136 (BACK_PASS_OP) == kKeep_StencilOp && \ 137 (FRONT_FAIL_OP) == kKeep_StencilOp && \ 138 (BACK_FAIL_OP) == kKeep_StencilOp && \ 139 (FRONT_FUNC) == kAlways_StencilFunc && \ 140 (BACK_FUNC) == kAlways_StencilFunc) 141 142 #define GR_STENCIL_SETTINGS_DOES_WRITE( \ 143 FRONT_PASS_OP, BACK_PASS_OP, \ 144 FRONT_FAIL_OP, BACK_FAIL_OP, \ 145 FRONT_FUNC, BACK_FUNC) \ 146 (!(((FRONT_FUNC) == kNever_StencilFunc || \ 147 (FRONT_PASS_OP) == kKeep_StencilOp) && \ 148 ((BACK_FUNC) == kNever_StencilFunc || \ 149 (BACK_PASS_OP) == kKeep_StencilOp) && \ 150 ((FRONT_FUNC) == kAlways_StencilFunc || \ 151 (FRONT_FAIL_OP) == kKeep_StencilOp) && \ 152 ((BACK_FUNC) == kAlways_StencilFunc || \ 153 (BACK_FAIL_OP) == kKeep_StencilOp))) 154 155 #define GR_STENCIL_SETTINGS_DEFAULT_FLAGS( \ 156 FRONT_PASS_OP, BACK_PASS_OP, \ 157 FRONT_FAIL_OP, BACK_FAIL_OP, \ 158 FRONT_FUNC, BACK_FUNC) \ 159 ((GR_STENCIL_SETTINGS_IS_DISABLED(FRONT_PASS_OP,BACK_PASS_OP, \ 160 FRONT_FAIL_OP,BACK_FAIL_OP,FRONT_FUNC,BACK_FUNC) ? \ 161 kIsDisabled_StencilFlag : kNotDisabled_StencilFlag) | \ 162 (GR_STENCIL_SETTINGS_DOES_WRITE(FRONT_PASS_OP,BACK_PASS_OP, \ 163 FRONT_FAIL_OP,BACK_FAIL_OP,FRONT_FUNC,BACK_FUNC) ? \ 164 kDoesWrite_StencilFlag : kDoesNotWrite_StencilFlag)) 165 166 /** 167 * Class representing stencil state. 168 */ 169 class GrStencilSettings : private GrStencilSettingsStruct { 170 171 public: 172 enum Face { 173 kFront_Face = 0, 174 kBack_Face = 1, 175 }; 176 177 GrStencilSettings() { 178 fPad0 = fPad1 = 0; 179 this->setDisabled(); 180 } 181 182 GrStencilOp passOp(Face f) const { return static_cast<GrStencilOp>(fPassOps[f]); } 183 GrStencilOp failOp(Face f) const { return static_cast<GrStencilOp>(fFailOps[f]); } 184 GrStencilFunc func(Face f) const { return static_cast<GrStencilFunc>(fFuncs[f]); } 185 uint16_t funcMask(Face f) const { return fFuncMasks[f]; } 186 uint16_t funcRef(Face f) const { return fFuncRefs[f]; } 187 uint16_t writeMask(Face f) const { return fWriteMasks[f]; } 188 189 void setPassOp(Face f, GrStencilOp op) { fPassOps[f] = op; fFlags = 0;} 190 void setFailOp(Face f, GrStencilOp op) { fFailOps[f] = op; fFlags = 0;} 191 void setFunc(Face f, GrStencilFunc func) { fFuncs[f] = func; fFlags = 0;} 192 void setFuncMask(Face f, unsigned short mask) { fFuncMasks[f] = mask; } 193 void setFuncRef(Face f, unsigned short ref) { fFuncRefs[f] = ref; } 194 void setWriteMask(Face f, unsigned short writeMask) { fWriteMasks[f] = writeMask; } 195 196 void copyFrontSettingsToBack() { 197 fPassOps[kBack_Face] = fPassOps[kFront_Face]; 198 fFailOps[kBack_Face] = fFailOps[kFront_Face]; 199 fFuncs[kBack_Face] = fFuncs[kFront_Face]; 200 fFuncMasks[kBack_Face] = fFuncMasks[kFront_Face]; 201 fFuncRefs[kBack_Face] = fFuncRefs[kFront_Face]; 202 fWriteMasks[kBack_Face] = fWriteMasks[kFront_Face]; 203 fFlags = 0; 204 } 205 206 void setSame(GrStencilOp passOp, 207 GrStencilOp failOp, 208 GrStencilFunc func, 209 unsigned short funcMask, 210 unsigned short funcRef, 211 unsigned short writeMask) { 212 fPassOps[kFront_Face] = fPassOps[kBack_Face] = passOp; 213 fFailOps[kFront_Face] = fFailOps[kBack_Face] = failOp; 214 fFuncs[kFront_Face] = fFuncs[kBack_Face] = func; 215 fFuncMasks[kFront_Face] = fFuncMasks[kBack_Face] = funcMask; 216 fFuncRefs[kFront_Face] = fFuncRefs[kBack_Face] = funcRef; 217 fWriteMasks[kFront_Face] = fWriteMasks[kBack_Face] = writeMask; 218 fFlags = 0; 219 } 220 221 void setDisabled() { 222 memset(this, 0, sizeof(*this)); 223 GR_STATIC_ASSERT(0 == kKeep_StencilOp); 224 GR_STATIC_ASSERT(0 == kAlways_StencilFunc); 225 fFlags = kIsDisabled_StencilFlag | kDoesNotWrite_StencilFlag; 226 } 227 228 bool isTwoSided() const { 229 return fPassOps[kFront_Face] != fPassOps[kBack_Face] || 230 fFailOps[kFront_Face] != fFailOps[kBack_Face] || 231 fFuncs[kFront_Face] != fFuncs[kBack_Face] || 232 fFuncMasks[kFront_Face] != fFuncMasks[kBack_Face] || 233 fFuncRefs[kFront_Face] != fFuncRefs[kBack_Face] || 234 fWriteMasks[kFront_Face] != fWriteMasks[kBack_Face]; 235 } 236 237 bool usesWrapOp() const { 238 return kIncWrap_StencilOp == fPassOps[kFront_Face] || 239 kDecWrap_StencilOp == fPassOps[kFront_Face] || 240 kIncWrap_StencilOp == fPassOps[kBack_Face] || 241 kDecWrap_StencilOp == fPassOps[kBack_Face] || 242 kIncWrap_StencilOp == fFailOps[kFront_Face] || 243 kDecWrap_StencilOp == fFailOps[kFront_Face] || 244 kIncWrap_StencilOp == fFailOps[kBack_Face] || 245 kDecWrap_StencilOp == fFailOps[kBack_Face]; 246 } 247 248 bool isDisabled() const { 249 if (fFlags & kIsDisabled_StencilFlag) { 250 return true; 251 } 252 if (fFlags & kNotDisabled_StencilFlag) { 253 return false; 254 } 255 bool disabled = GR_STENCIL_SETTINGS_IS_DISABLED( 256 fPassOps[kFront_Face], fPassOps[kBack_Face], 257 fFailOps[kFront_Face], fFailOps[kBack_Face], 258 fFuncs[kFront_Face], fFuncs[kBack_Face]); 259 fFlags |= disabled ? kIsDisabled_StencilFlag : kNotDisabled_StencilFlag; 260 return disabled; 261 } 262 263 bool doesWrite() const { 264 if (fFlags & kDoesWrite_StencilFlag) { 265 return true; 266 } 267 if (fFlags & kDoesNotWrite_StencilFlag) { 268 return false; 269 } 270 bool writes = GR_STENCIL_SETTINGS_DOES_WRITE( 271 fPassOps[kFront_Face], fPassOps[kBack_Face], 272 fFailOps[kFront_Face], fFailOps[kBack_Face], 273 fFuncs[kFront_Face], fFuncs[kBack_Face]); 274 fFlags |= writes ? kDoesWrite_StencilFlag : kDoesNotWrite_StencilFlag; 275 return writes; 276 } 277 278 void invalidate() { 279 // write an illegal value to the first member 280 fPassOps[0] = kStencilOpCount; 281 fFlags = 0; 282 } 283 284 bool isValid() const { 285 return fPassOps[0] < kStencilOpCount; 286 } 287 288 bool operator == (const GrStencilSettings& s) const { 289 static const size_t gCompareSize = sizeof(GrStencilSettings) - 290 sizeof(fFlags); 291 SkASSERT((const char*)&fFlags + sizeof(fFlags) == 292 (const char*)this + sizeof(GrStencilSettings)); 293 if (this->isDisabled() & s.isDisabled()) { // using & not && 294 return true; 295 } 296 return 0 == memcmp(this, &s, gCompareSize); 297 } 298 299 bool operator != (const GrStencilSettings& s) const { 300 return !(*this == s); 301 } 302 303 GrStencilSettings& operator =(const GrStencilSettings& s) { 304 memcpy(this, &s, sizeof(GrStencilSettings)); 305 return *this; 306 } 307 308 private: 309 friend class GrClipMaskManager; 310 311 enum { 312 kMaxStencilClipPasses = 2 // maximum number of passes to add a clip 313 // element to the stencil buffer. 314 }; 315 316 /** 317 * Given a thing to draw into the stencil clip, a fill type, and a set op 318 * this function determines: 319 * 1. Whether the thing can be draw directly to the stencil clip or 320 * needs to be drawn to the client portion of the stencil first. 321 * 2. How many passes are needed. 322 * 3. What those passes are. 323 * 4. The fill rule that should actually be used to render (will 324 * always be non-inverted). 325 * 326 * @param op the set op to combine this element with the 327 * existing clip 328 * @param stencilClipMask mask with just the stencil bit used for clipping 329 * enabled. 330 * @param invertedFill is this path inverted 331 * @param numPasses out: the number of passes needed to add the 332 * element to the clip. 333 * @param settings out: the stencil settings to use for each pass 334 * 335 * @return true if the clip element's geometry can be drawn directly to the 336 * stencil clip bit. Will only be true if canBeDirect is true. 337 * numPasses will be 1 if return value is true. 338 */ 339 static bool GetClipPasses(SkRegion::Op op, 340 bool canBeDirect, 341 unsigned int stencilClipMask, 342 bool invertedFill, 343 int* numPasses, 344 GrStencilSettings settings[kMaxStencilClipPasses]); 345 }; 346 347 GR_STATIC_ASSERT(sizeof(GrStencilSettingsStruct) == sizeof(GrStencilSettings)); 348 349 #define GR_STATIC_CONST_STENCIL_STRUCT(STRUCT_NAME, \ 350 FRONT_PASS_OP, BACK_PASS_OP, \ 351 FRONT_FAIL_OP, BACK_FAIL_OP, \ 352 FRONT_FUNC, BACK_FUNC, \ 353 FRONT_MASK, BACK_MASK, \ 354 FRONT_REF, BACK_REF, \ 355 FRONT_WRITE_MASK, BACK_WRITE_MASK) \ 356 static const GrStencilSettingsStruct STRUCT_NAME = { \ 357 {(FRONT_PASS_OP), (BACK_PASS_OP) }, \ 358 {(FRONT_FAIL_OP), (BACK_FAIL_OP) }, \ 359 {(FRONT_FUNC), (BACK_FUNC) }, \ 360 (0), (0), \ 361 {(FRONT_MASK), (BACK_MASK) }, \ 362 {(FRONT_REF), (BACK_REF) }, \ 363 {(FRONT_WRITE_MASK), (BACK_WRITE_MASK)}, \ 364 GR_STENCIL_SETTINGS_DEFAULT_FLAGS( \ 365 FRONT_PASS_OP, BACK_PASS_OP, FRONT_FAIL_OP, BACK_FAIL_OP, \ 366 FRONT_FUNC, BACK_FUNC) \ 367 }; 368 369 #define GR_CONST_STENCIL_SETTINGS_PTR_FROM_STRUCT_PTR(STRUCT_PTR) \ 370 reinterpret_cast<const GrStencilSettings*>(STRUCT_PTR) 371 372 #define GR_STATIC_CONST_SAME_STENCIL_STRUCT(STRUCT_NAME, \ 373 PASS_OP, FAIL_OP, FUNC, MASK, REF, WRITE_MASK) \ 374 GR_STATIC_CONST_STENCIL_STRUCT(STRUCT_NAME, (PASS_OP), (PASS_OP), \ 375 (FAIL_OP),(FAIL_OP), (FUNC), (FUNC), (MASK), (MASK), (REF), (REF), \ 376 (WRITE_MASK),(WRITE_MASK)) 377 378 #define GR_STATIC_CONST_STENCIL(NAME, \ 379 FRONT_PASS_OP, BACK_PASS_OP, \ 380 FRONT_FAIL_OP, BACK_FAIL_OP, \ 381 FRONT_FUNC, BACK_FUNC, \ 382 FRONT_MASK, BACK_MASK, \ 383 FRONT_REF, BACK_REF, \ 384 FRONT_WRITE_MASK, BACK_WRITE_MASK) \ 385 GR_STATIC_CONST_STENCIL_STRUCT(NAME ## _STRUCT, \ 386 (FRONT_PASS_OP),(BACK_PASS_OP),(FRONT_FAIL_OP),(BACK_FAIL_OP), \ 387 (FRONT_FUNC),(BACK_FUNC),(FRONT_MASK),(BACK_MASK), \ 388 (FRONT_REF),(BACK_REF),(FRONT_WRITE_MASK),(BACK_WRITE_MASK)) \ 389 static const GrStencilSettings& NAME = \ 390 *GR_CONST_STENCIL_SETTINGS_PTR_FROM_STRUCT_PTR(&(NAME ## _STRUCT)); 391 392 393 #define GR_STATIC_CONST_SAME_STENCIL(NAME, \ 394 PASS_OP, FAIL_OP, FUNC, MASK, REF, WRITE_MASK) \ 395 GR_STATIC_CONST_STENCIL(NAME, (PASS_OP), (PASS_OP), (FAIL_OP), \ 396 (FAIL_OP), (FUNC), (FUNC), (MASK), (MASK), (REF), (REF), (WRITE_MASK), \ 397 (WRITE_MASK)) 398 399 #endif 400
