1Name 2 3 NV_path_rendering 4 5Name Strings 6 7 GL_NV_path_rendering 8 9Contact 10 11 Mark Kilgard, NVIDIA (mjk 'at' nvidia.com) 12 13Contributors 14 15 Roger Allen, NVIDIA 16 Jeff Bolz, NVIDIA 17 Chris Dalton, NVIDIA 18 Pierre-Loup Griffais, NVIDIA 19 Chris Hebert, Samsung 20 Scott Nations, NVIDIA 21 David Chait, NVIDIA 22 Daniel Koch, NVIDIA 23 Bas Schouten, Mozilla 24 Sandeep Shinde, NVIDIA 25 26Status 27 28 Released in NVIDIA Driver Release 275.33 (June 2011). 29 30 Substantially optimized in NVIDIA Driver Release 301.42 (May 2012). 31 32 Further optimized in NVIDIA Driver Release 314.xx (February 2013). 33 34 Version 1.3 functionality shipping in NVIDIA Driver Release 337.88 35 and on (May, 27 2014). 36 37Version 38 39 Last Modified Date: September 9, 2014 40 Version: 35 41 42Number 43 44 OpenGL Extension #410 45 OpenGL ES Extension #199 46 47Dependencies 48 49 This extension is written against the OpenGL 3.2 Specification with 50 Compatibility Profile but can apply to OpenGL 1.1 and up. 51 52 When used with a Core profile or OpenGL ES context, certain 53 functionality is unavailable (see "Dependencies on Core Profile and 54 OpenGL ES" section). 55 56 This extension depends on ARB_program_interface_query. 57 58 EXT_direct_state_access commands are used in specifying portions 59 of this extension but EXT_direct_state_access is not required to 60 implement this extension as long as the functionality implemented 61 is equivalent to the EXT_direct_state_access commands. 62 63 EXT_separate_shader_objects is recommended. 64 65 ARB_program_interface_query is recommended. 66 67Overview 68 69 Conventional OpenGL supports rendering images (pixel rectangles and 70 bitmaps) and simple geometric primitives (points, lines, polygons). 71 72 This extension adds a new rendering paradigm, known as path rendering, 73 for rendering filled and stroked paths. Path rendering is not novel 74 but rather a standard part of most resolution-independent 2D rendering 75 systems such as Flash, PDF, Silverlight, SVG, Java 2D, Office 76 drawings, TrueType fonts, PostScript and its fonts, Quartz 2D, XML 77 Paper Specification (XPS), and OpenVG. What is novel is the ability 78 to mix path rendering with arbitrary OpenGL 3D rendering and imaging. 79 80 With this extension, path rendering becomes a first-class rendering 81 mode within the OpenGL graphics system that can be arbitrarily mixed 82 with existing OpenGL rendering and can take advantage of OpenGL's 83 existing mechanisms for texturing, programmability, and per-fragment 84 operations. 85 86 Unlike geometric primitive rendering, paths are specified on a 2D 87 (non-projective) plane rather than in 3D (projective) space. 88 Even though the path is defined in a 2D plane, every path can 89 be transformed into 3D clip space allowing for 3D view frustum & 90 user-defined clipping, depth offset, and depth testing in the same 91 manner as geometric primitive rendering. 92 93 Both geometric primitive rendering and path rendering support 94 rasterization of edges defined by line segments; however, path 95 rendering also allows path segments to be specified by Bezier (cubic 96 or quadratic) curves or partial elliptical arcs. This allows path 97 rendering to define truly curved primitive boundaries unlike the 98 straight edges of line and polygon primitives. Whereas geometric 99 primitive rendering requires convex polygons for well-defined 100 rendering results, path rendering allows (and encourages!) concave 101 and curved outlines to be specified. These paths are even allowed 102 to self-intersect. 103 104 When filling closed paths, the winding of paths (counterclockwise 105 or clockwise) determines whether pixels are inside or outside of 106 the path. 107 108 Paths can also be stroked whereby, conceptually, a fixed-width "brush" 109 is pulled along the path such that the brush remains orthogonal to 110 the gradient of each path segment. Samples within the sweep of this 111 brush are considered inside the stroke of the path. 112 113 This extension supports path rendering through a sequence of three 114 operations: 115 116 1. Path specification is the process of creating and updating 117 a path object consisting of a set of path commands and a 118 corresponding set of 2D vertices. 119 120 Path commands can be specified explicitly from path command 121 and coordinate data, parsed from a string based on standard 122 grammars for representing paths, or specified by a particular 123 glyph of standard font representations. Also new paths can 124 be specified by weighting one or more existing paths so long 125 as all the weighted paths have consistent command sequences. 126 127 Each path object contains zero or more subpaths specified 128 by a sequence of line segments, partial elliptical arcs, 129 and (cubic or quadratic) Bezier curve segments. Each path 130 may contain multiple subpaths that can be closed (forming 131 a contour) or open. 132 133 2. Path stenciling is the process of updating the stencil buffer 134 based on a path's coverage transformed into window space. 135 136 Path stenciling can determine either the filled or stroked 137 coverage of a path. 138 139 The details of path stenciling are explained within the core 140 of the specification. 141 142 Stenciling a stroked path supports all the standard 143 embellishments for path stroking such as end caps, join 144 styles, miter limits, dashing, and dash caps. These stroking 145 properties specified are parameters of path objects. 146 147 3. Path covering is the process of emitting simple (convex & 148 planar) geometry that (conservatively) "covers" the path's 149 sample coverage in the stencil buffer. During path covering, 150 stencil testing can be configured to discard fragments not 151 within the actual coverage of the path as determined by 152 prior path stenciling. 153 154 Path covering can cover either the filled or stroked coverage 155 of a path. 156 157 The details of path covering are explained within the core 158 of the specification. 159 160 To render a path object into the color buffer, an application specifies 161 a path object and then uses a two-step rendering process. First, the 162 path object is stenciled whereby the path object's stroked or filled 163 coverage is rasterized into the stencil buffer. Second, the path object 164 is covered whereby conservative bounding geometry for the path is 165 transformed and rasterized with stencil testing configured to test against 166 the coverage information written to the stencil buffer in the first step 167 so that only fragments covered by the path are written during this second 168 step. Also during this second step written pixels typically have 169 their stencil value reset (so there's no need for clearing the 170 stencil buffer between rendering each path). 171 172 Here is an example of specifying and then rendering a five-point 173 star and a heart as a path using Scalable Vector Graphics (SVG) 174 path description syntax: 175 176 GLuint pathObj = 42; 177 const char *svgPathString = 178 // star 179 "M100,180 L40,10 L190,120 L10,120 L160,10 z" 180 // heart 181 "M300 300 C 100 400,100 200,300 100,500 200,500 400,300 300Z"; 182 glPathStringNV(pathObj, GL_PATH_FORMAT_SVG_NV, 183 (GLsizei)strlen(svgPathString), svgPathString); 184 185 Alternatively applications oriented around the PostScript imaging 186 model can use the PostScript user path syntax instead: 187 188 const char *psPathString = 189 // star 190 "100 180 moveto" 191 " 40 10 lineto 190 120 lineto 10 120 lineto 160 10 lineto closepath" 192 // heart 193 " 300 300 moveto" 194 " 100 400 100 200 300 100 curveto" 195 " 500 200 500 400 300 300 curveto closepath"; 196 glPathStringNV(pathObj, GL_PATH_FORMAT_PS_NV, 197 (GLsizei)strlen(psPathString), psPathString); 198 199 The PostScript path syntax also supports compact and precise binary 200 encoding and includes PostScript-style circular arcs. 201 202 Or the path's command and coordinates can be specified explicitly: 203 204 static const GLubyte pathCommands[10] = 205 { GL_MOVE_TO_NV, GL_LINE_TO_NV, GL_LINE_TO_NV, GL_LINE_TO_NV, 206 GL_LINE_TO_NV, GL_CLOSE_PATH_NV, 207 'M', 'C', 'C', 'Z' }; // character aliases 208 static const GLshort pathCoords[12][2] = 209 { {100, 180}, {40, 10}, {190, 120}, {10, 120}, {160, 10}, 210 {300,300}, {100,400}, {100,200}, {300,100}, 211 {500,200}, {500,400}, {300,300} }; 212 glPathCommandsNV(pathObj, 10, pathCommands, 24, GL_SHORT, pathCoords); 213 214 Before rendering to a window with a stencil buffer, clear the stencil 215 buffer to zero and the color buffer to black: 216 217 glClearStencil(0); 218 glClearColor(0,0,0,0); 219 glStencilMask(~0); 220 glClear(GL_COLOR_BUFFER_BIT | GL_STENCIL_BUFFER_BIT); 221 222 Use an orthographic path-to-clip-space transform to map the 223 [0..500]x[0..400] range of the star's path coordinates to the [-1..1] 224 clip space cube: 225 226 glMatrixLoadIdentityEXT(GL_PROJECTION); 227 glMatrixLoadIdentityEXT(GL_MODELVIEW); 228 glMatrixOrthoEXT(GL_MODELVIEW, 0, 500, 0, 400, -1, 1); 229 230 Stencil the path: 231 232 glStencilFillPathNV(pathObj, GL_COUNT_UP_NV, 0x1F); 233 234 The 0x1F mask means the counting uses modulo-32 arithmetic. In 235 principle the star's path is simple enough (having a maximum winding 236 number of 2) that modulo-4 arithmetic would be sufficient so the mask 237 could be 0x3. Or a mask of all 1's (~0) could be used to count with 238 all available stencil bits. 239 240 Now that the coverage of the star and the heart have been rasterized 241 into the stencil buffer, cover the path with a non-zero fill style 242 (indicated by the GL_NOTEQUAL stencil function with a zero reference 243 value): 244 245 glEnable(GL_STENCIL_TEST); 246 glStencilFunc(GL_NOTEQUAL, 0, 0x1F); 247 glStencilOp(GL_KEEP, GL_KEEP, GL_ZERO); 248 glColor3f(1,1,0); // yellow 249 glCoverFillPathNV(pathObj, GL_BOUNDING_BOX_NV); 250 251 The result is a yellow star (with a filled center) to the left of 252 a yellow heart. 253 254 The GL_ZERO stencil operation ensures that any covered samples 255 (meaning those with non-zero stencil values) are zero'ed when 256 the path cover is rasterized. This allows subsequent paths to be 257 rendered without clearing the stencil buffer again. 258 259 A similar two-step rendering process can draw a white outline 260 over the star and heart. 261 262 Before rendering, configure the path object with desirable path 263 parameters for stroking. Specify a wider 6.5-unit stroke and 264 the round join style: 265 266 glPathParameteriNV(pathObj, GL_PATH_JOIN_STYLE_NV, GL_ROUND_NV); 267 glPathParameterfNV(pathObj, GL_PATH_STROKE_WIDTH_NV, 6.5); 268 269 Now stencil the path's stroked coverage into the stencil buffer, 270 setting the stencil to 0x1 for all stencil samples within the 271 transformed path. 272 273 glStencilStrokePathNV(pathObj, 0x1, ~0); 274 275 Cover the path's stroked coverage (with a hull this time instead 276 of a bounding box; the choice doesn't really matter here) while 277 stencil testing that writes white to the color buffer and again 278 zero the stencil buffer. 279 280 glColor3f(1,1,1); // white 281 glCoverStrokePathNV(pathObj, GL_CONVEX_HULL_NV); 282 283 In this example, constant color shading is used but the application 284 can specify their own arbitrary shading and/or blending operations, 285 whether with Cg compiled to fragment program assembly, GLSL, or 286 fixed-function fragment processing. 287 288 More complex path rendering is possible such as clipping one path to 289 another arbitrary path. This is because stencil testing (as well 290 as depth testing, depth bound test, clip planes, and scissoring) 291 can restrict path stenciling. 292 293 Now let's render the word "OpenGL" atop the star and heart. 294 295 First create a sequence of path objects for the glyphs for the 296 characters in "OpenGL": 297 298 GLuint glyphBase = glGenPathsNV(6); 299 const unsigned char *word = "OpenGL"; 300 const GLsizei wordLen = (GLsizei)strlen(word); 301 const GLfloat emScale = 2048; // match TrueType convention 302 GLuint templatePathObject = ~0; // Non-existent path object 303 glPathGlyphsNV(glyphBase, 304 GL_SYSTEM_FONT_NAME_NV, "Helvetica", GL_BOLD_BIT_NV, 305 wordLen, GL_UNSIGNED_BYTE, word, 306 GL_SKIP_MISSING_GLYPH_NV, ~0, emScale); 307 glPathGlyphsNV(glyphBase, 308 GL_SYSTEM_FONT_NAME_NV, "Arial", GL_BOLD_BIT_NV, 309 wordLen, GL_UNSIGNED_BYTE, word, 310 GL_SKIP_MISSING_GLYPH_NV, ~0, emScale); 311 glPathGlyphsNV(glyphBase, 312 GL_STANDARD_FONT_NAME_NV, "Sans", GL_BOLD_BIT_NV, 313 wordLen, GL_UNSIGNED_BYTE, word, 314 GL_USE_MISSING_GLYPH_NV, ~0, emScale); 315 316 Glyphs are loaded for three different fonts in priority order: 317 Helvetica first, then Arial, and if neither of those loads, use the 318 standard sans-serif font. If a prior glPathGlyphsNV is successful 319 and specifies the path object range, the subsequent glPathGlyphsNV 320 commands silently avoid re-specifying the already existent path 321 objects. 322 323 Now query the (kerned) separations for the word "OpenGL" and build 324 a set of horizontal translations advancing each successive glyph by 325 its kerning distance with the following glyph. 326 327 GLfloat xtranslate[6+1]; // wordLen+1 328 glGetPathSpacingNV(GL_ACCUM_ADJACENT_PAIRS_NV, 329 wordLen+1, GL_UNSIGNED_BYTE, 330 "\000\001\002\003\004\005\005", // repeat last letter twice 331 glyphBase, 332 1.0f, 1.0f, 333 GL_TRANSLATE_X_NV, 334 xtranslate); 335 336 Next determine the font-wide vertical minimum and maximum for the 337 font face by querying the per-font metrics of any one of the glyphs 338 from the font face. 339 340 GLfloat yMinMax[2]; 341 glGetPathMetricRangeNV(GL_FONT_Y_MIN_BOUNDS_BIT_NV|GL_FONT_Y_MAX_BOUNDS_BIT_NV, 342 glyphBase, /*count*/1, 343 2*sizeof(GLfloat), 344 yMinMax); 345 346 Use an orthographic path-to-clip-space transform to map the 347 word's bounds to the [-1..1] clip space cube: 348 349 glMatrixLoadIdentityEXT(GL_PROJECTION); 350 glMatrixOrthoEXT(GL_MODELVIEW, 351 0, xtranslate[6], yMinMax[0], yMinMax[1], 352 -1, 1); 353 354 Stencil the filled paths of the sequence of glyphs for "OpenGL", 355 each transformed by the appropriate 2D translations for spacing. 356 357 glStencilFillPathInstancedNV(6, GL_UNSIGNED_BYTE, 358 "\000\001\002\003\004\005", 359 glyphBase, 360 GL_PATH_FILL_MODE_NV, 0xFF, 361 GL_TRANSLATE_X_NV, xtranslate); 362 363 Cover the bounding box union of the glyphs with 50% gray. 364 365 glEnable(GL_STENCIL_TEST); 366 glStencilFunc(GL_NOTEQUAL, 0, 0xFF); 367 glStencilOp(GL_KEEP, GL_KEEP, GL_ZERO); 368 glColor3f(0.5,0.5,0.5); // 50% gray 369 glCoverFillPathInstancedNV(6, GL_UNSIGNED_BYTE, 370 "\000\001\002\003\004\005", 371 glyphBase, 372 GL_BOUNDING_BOX_OF_BOUNDING_BOXES_NV, 373 GL_TRANSLATE_X_NV, xtranslate); 374 375 Voila, the word "OpenGL" in gray is now stenciled into the framebuffer. 376 377 Instead of solid 50% gray, the cover operation can apply a linear 378 gradient that changes from green (RGB=0,1,0) at the top of the word 379 "OpenGL" to blue (RGB=0,0,1) at the bottom of "OpenGL": 380 381 GLfloat rgbGen[3][3] = { 382 0, 0, 0, // red = constant zero 383 0, 1, 0, // green = varies with y from bottom (0) to top (1) 384 0, -1, 1 // blue = varies with y from bottom (1) to top (0) 385 }; 386 glPathColorGenNV(GL_PRIMARY_COLOR, GL_PATH_OBJECT_BOUNDING_BOX_NV, 387 GL_RGB, &rgbGen[0][0]); 388 389 Instead of loading just the glyphs for the characters in "OpenGL", 390 the entire character set could be loaded. This allows the characters 391 of the string to be mapped (offset by the glyphBase) to path object names. 392 A range of glyphs can be loaded like this: 393 394 const int numChars = 256; // ISO/IEC 8859-1 8-bit character range 395 GLuint glyphBase = glGenPathsNV(numChars); 396 glPathGlyphRangeNV(glyphBase, 397 GL_SYSTEM_FONT_NAME_NV, "Helvetica", GL_BOLD_BIT_NV, 398 0, numChars, 399 GL_SKIP_MISSING_GLYPH_NV, ~0, emScale); 400 glPathGlyphRangeNV(glyphBase, 401 GL_SYSTEM_FONT_NAME_NV, "Arial", GL_BOLD_BIT_NV, 402 0, numChars, 403 GL_SKIP_MISSING_GLYPH_NV, ~0, emScale); 404 glPathGlyphRangeNV(glyphBase, 405 GL_STANDARD_FONT_NAME_NV, "Sans", GL_BOLD_BIT_NV, 406 0, numChars, 407 GL_USE_MISSING_GLYPH_NV, ~0, emScale); 408 409 Given a range of glyphs loaded as path objects, (kerned) spacing 410 information can now be queried for the string: 411 412 glGetPathSpacingNV(GL_ACCUM_ADJACENT_PAIRS_NV, 413 7, GL_UNSIGNED_BYTE, "OpenGLL", // repeat L to get final spacing 414 glyphBase, 415 1.0f, 1.0f, 416 GL_TRANSLATE_X_NV, 417 kerning); 418 419 Using the range of glyphs, stenciling and covering the instanced 420 paths for "OpenGL" can be done this way: 421 422 glStencilFillPathInstancedNV(6, GL_UNSIGNED_BYTE, "OpenGL", 423 glyphBase, 424 GL_PATH_FILL_MODE_NV, 0xFF, 425 GL_TRANSLATE_X_NV, xtranslate); 426 427 glCoverFillPathInstancedNV(6, GL_UNSIGNED_BYTE, "OpenGL", 428 glyphBase, 429 GL_BOUNDING_BOX_OF_BOUNDING_BOXES_NV, 430 GL_TRANSLATE_X_NV, xtranslate); 431 432 The "stencil" and "cover" steps can be combined in a single command: 433 434 glStencilThenCoverFillPathInstancedNV(6, GL_UNSIGNED_BYTE, "OpenGL", 435 glyphBase, 436 GL_PATH_FILL_MODE_NV, 0xFF, 437 GL_BOUNDING_BOX_OF_BOUNDING_BOXES_NV 438 GL_TRANSLATE_X_NV, xtranslate); 439 440 XXX add path clipping example to demonstrate glPathStencilFuncNV. 441 442New Procedures and Functions 443 444 PATH SPECIFICATION COMMANDS 445 446 EXPLICIT PATH DATA 447 448 void PathCommandsNV(uint path, 449 sizei numCommands, const ubyte *commands, 450 sizei numCoords, enum coordType, 451 const void *coords); 452 void PathCoordsNV(uint path, 453 sizei numCoords, enum coordType, 454 const void *coords); 455 456 void PathSubCommandsNV(uint path, 457 sizei commandStart, sizei commandsToDelete, 458 sizei numCommands, const ubyte *commands, 459 sizei numCoords, enum coordType, 460 const void *coords); 461 void PathSubCoordsNV(uint path, 462 sizei coordStart, 463 sizei numCoords, enum coordType, 464 const void *coords); 465 466 STRING PATH DESCRIPTION 467 468 void PathStringNV(uint path, enum format, 469 sizei length, const void *pathString); 470 471 PATHS FROM FONT GLYPHS BY UNICODE CHARACTER POINT 472 473 void PathGlyphsNV(uint firstPathName, 474 enum fontTarget, 475 const void *fontName, 476 bitfield fontStyle, 477 sizei numGlyphs, enum type, 478 const void *charcodes, 479 enum handleMissingGlyphs, 480 uint pathParameterTemplate, 481 float emScale); 482 void PathGlyphRangeNV(uint firstPathName, 483 enum fontTarget, 484 const void *fontName, 485 bitfield fontStyle, 486 uint firstGlyph, 487 sizei numGlyphs, 488 enum handleMissingGlyphs, 489 uint pathParameterTemplate, 490 float emScale); 491 492 PATHS FROM FONT GLYPHS BY PER-FONT GLYPH INDEX 493 494 enum PathGlyphIndexArrayNV(uint firstPathName, 495 enum fontTarget, 496 const void *fontName, 497 bitfield fontStyle, 498 uint firstGlyphIndex, 499 sizei numGlyphs, 500 uint pathParameterTemplate, 501 float emScale); 502 enum PathMemoryGlyphIndexArrayNV(uint firstPathName, 503 enum fontTarget, 504 sizeiptr fontSize, 505 const void *fontData, 506 sizei faceIndex, 507 uint firstGlyphIndex, 508 sizei numGlyphs, 509 uint pathParameterTemplate, 510 float emScale); 511 enum PathGlyphIndexRangeNV(enum fontTarget, 512 const void *fontName, 513 bitfield fontStyle, 514 uint pathParameterTemplate, 515 float emScale, 516 uint* baseAndCount); 517 518 PATH SPECIFICATION WITH EXISTING PATHS 519 520 void WeightPathsNV(uint resultPath, 521 sizei numPaths, 522 const uint paths[], const float weights[]); 523 void CopyPathNV(uint resultPath, uint srcPath); 524 void InterpolatePathsNV(uint resultPath, 525 uint pathA, uint pathB, 526 float weight); 527 void TransformPathNV(uint resultPath, 528 uint srcPath, 529 enum transformType, 530 const float *transformValues); 531 532 PATH PARAMETER SPECIFICATION COMMANDS 533 534 void PathParameterivNV(uint path, enum pname, const int *value); 535 void PathParameteriNV(uint path, enum pname, int value); 536 void PathParameterfvNV(uint path, enum pname, const float *value); 537 void PathParameterfNV(uint path, enum pname, float value); 538 539 void PathDashArrayNV(uint path, 540 sizei dashCount, const float *dashArray); 541 542 PATH NAME MANAGEMENT 543 544 uint GenPathsNV(sizei range); 545 void DeletePathsNV(uint path, sizei range); 546 boolean IsPathNV(uint path); 547 548 PATH STENCILING 549 550 void PathStencilFuncNV(enum func, int ref, uint mask); 551 void PathStencilDepthOffsetNV(float factor, float units); 552 553 void StencilFillPathNV(uint path, 554 enum fillMode, uint mask); 555 556 void StencilStrokePathNV(uint path, 557 int reference, uint mask); 558 559 void StencilFillPathInstancedNV(sizei numPaths, 560 enum pathNameType, const void *paths, 561 uint pathBase, 562 enum fillMode, uint mask, 563 enum transformType, 564 const float *transformValues); 565 566 void StencilStrokePathInstancedNV(sizei numPaths, 567 enum pathNameType, const void *paths, 568 uint pathBase, 569 int reference, uint mask, 570 enum transformType, 571 const float *transformValues); 572 573 PATH COVERING 574 575 void PathCoverDepthFuncNV(enum zfunc); 576 577 void PathColorGenNV(enum color, 578 enum genMode, 579 enum colorFormat, const float *coeffs); 580 void PathTexGenNV(enum texCoordSet, 581 enum genMode, 582 int components, const float *coeffs); 583 void PathFogGenNV(enum genMode); 584 585 void CoverFillPathNV(uint path, enum coverMode); 586 587 void CoverStrokePathNV(uint path, enum coverMode); 588 589 void CoverFillPathInstancedNV(sizei numPaths, 590 enum pathNameType, const void *paths, 591 uint pathBase, 592 enum coverMode, 593 enum transformType, 594 const float *transformValues); 595 596 void CoverStrokePathInstancedNV(sizei numPaths, 597 enum pathNameType, const void *paths, 598 uint pathBase, 599 enum coverMode, 600 enum transformType, 601 const float *transformValues); 602 603 PATH STENCILING THEN COVERING 604 605 void StencilThenCoverFillPathNV(uint path, enum fillMode, 606 uint mask, enum coverMode); 607 void StencilThenCoverStrokePathNV(uint path, int reference, 608 uint mask, enum coverMode); 609 void StencilThenCoverFillPathInstancedNV(sizei numPaths, 610 enum pathNameType, 611 const void *paths, 612 uint pathBase, 613 enum fillMode, uint mask, 614 enum coverMode, 615 enum transformType, 616 const float *transformValues); 617 void StencilThenCoverStrokePathInstancedNV(sizei numPaths, 618 enum pathNameType, 619 const void *paths, 620 uint pathBase, 621 int reference, uint mask, 622 enum coverMode, 623 enum transformType, 624 const float *transformValues); 625 626 PATH COVERING OF GLSL FRAGMENT INPUTS 627 628 void ProgramPathFragmentInputGenNV(uint program, 629 int location, 630 enum genMode, 631 int components, 632 const float *coeffs); 633 634 PATH QUERIES 635 636 void GetPathParameterivNV(uint path, enum pname, int *value); 637 void GetPathParameterfvNV(uint path, enum pname, float *value); 638 639 void GetPathCommandsNV(uint path, ubyte *commands); 640 void GetPathCoordsNV(uint path, float *coords); 641 void GetPathDashArrayNV(uint path, float *dashArray); 642 643 void GetPathMetricsNV(bitfield metricQueryMask, 644 sizei numPaths, 645 enum pathNameType, const void *paths, 646 uint pathBase, 647 sizei stride, 648 float *metrics); 649 void GetPathMetricRangeNV(bitfield metricQueryMask, 650 uint firstPathName, 651 sizei numPaths, 652 sizei stride, 653 float *metrics); 654 655 void GetPathSpacingNV(enum pathListMode, 656 sizei numPaths, 657 enum pathNameType, const void *paths, 658 uint pathBase, 659 float advanceScale, 660 float kerningScale, 661 enum transformType, 662 float *returnedSpacing); 663 664 void GetPathColorGenivNV(enum color, enum pname, int *value); 665 void GetPathColorGenfvNV(enum color, enum pname, float *value); 666 void GetPathTexGenivNV(enum texCoordSet, enum pname, int *value); 667 void GetPathTexGenfvNV(enum texCoordSet, enum pname, float *value); 668 669 boolean IsPointInFillPathNV(uint path, 670 uint mask, float x, float y); 671 boolean IsPointInStrokePathNV(uint path, 672 float x, float y); 673 674 float GetPathLengthNV(uint path, 675 sizei startSegment, sizei numSegments); 676 677 boolean PointAlongPathNV(uint path, 678 sizei startSegment, sizei numSegments, 679 float distance, 680 float *x, float *y, 681 float *tangentX, float *tangentY); 682 683 MATRIX SPECIFICATION 684 685 void MatrixLoad3x2fNV(enum matrixMode, const float *m); 686 void MatrixLoad3x3fNV(enum matrixMode, const float *m); 687 void MatrixLoadTranspose3x3fNV(enum matrixMode, const float *m); 688 689 void MatrixMult3x2fNV(enum matrixMode, const float *m); 690 void MatrixMult3x3fNV(enum matrixMode, const float *m); 691 void MatrixMultTranspose3x3fNV(enum matrixMode, const float *m); 692 693 FLOATING-POINT PROGRAM RESOURCE QUERY 694 695 void GetProgramResourcefvNV(uint program, enum programInterface, 696 uint index, sizei propCount, 697 const enum *props, sizei bufSize, 698 sizei *length, float *params); 699 700New Tokens 701 702 Accepted in elements of the <commands> array parameter of 703 PathCommandsNV and PathSubCommandsNV: 704 705 CLOSE_PATH_NV 0x00 706 MOVE_TO_NV 0x02 707 RELATIVE_MOVE_TO_NV 0x03 708 LINE_TO_NV 0x04 709 RELATIVE_LINE_TO_NV 0x05 710 HORIZONTAL_LINE_TO_NV 0x06 711 RELATIVE_HORIZONTAL_LINE_TO_NV 0x07 712 VERTICAL_LINE_TO_NV 0x08 713 RELATIVE_VERTICAL_LINE_TO_NV 0x09 714 QUADRATIC_CURVE_TO_NV 0x0A 715 RELATIVE_QUADRATIC_CURVE_TO_NV 0x0B 716 CUBIC_CURVE_TO_NV 0x0C 717 RELATIVE_CUBIC_CURVE_TO_NV 0x0D 718 SMOOTH_QUADRATIC_CURVE_TO_NV 0x0E 719 RELATIVE_SMOOTH_QUADRATIC_CURVE_TO_NV 0x0F 720 SMOOTH_CUBIC_CURVE_TO_NV 0x10 721 RELATIVE_SMOOTH_CUBIC_CURVE_TO_NV 0x11 722 SMALL_CCW_ARC_TO_NV 0x12 723 RELATIVE_SMALL_CCW_ARC_TO_NV 0x13 724 SMALL_CW_ARC_TO_NV 0x14 725 RELATIVE_SMALL_CW_ARC_TO_NV 0x15 726 LARGE_CCW_ARC_TO_NV 0x16 727 RELATIVE_LARGE_CCW_ARC_TO_NV 0x17 728 LARGE_CW_ARC_TO_NV 0x18 729 RELATIVE_LARGE_CW_ARC_TO_NV 0x19 730 CONIC_CURVE_TO_NV 0x1A 731 RELATIVE_CONIC_CURVE_TO_NV 0x1B 732 ROUNDED_RECT_NV 0xE8 733 RELATIVE_ROUNDED_RECT_NV 0xE9 734 ROUNDED_RECT2_NV 0xEA 735 RELATIVE_ROUNDED_RECT2_NV 0xEB 736 ROUNDED_RECT4_NV 0xEC 737 RELATIVE_ROUNDED_RECT4_NV 0xED 738 ROUNDED_RECT8_NV 0xEE 739 RELATIVE_ROUNDED_RECT8_NV 0xEF 740 RESTART_PATH_NV 0xF0 741 DUP_FIRST_CUBIC_CURVE_TO_NV 0xF2 742 DUP_LAST_CUBIC_CURVE_TO_NV 0xF4 743 RECT_NV 0xF6 744 RELATIVE_RECT_NV 0xF7 745 CIRCULAR_CCW_ARC_TO_NV 0xF8 746 CIRCULAR_CW_ARC_TO_NV 0xFA 747 CIRCULAR_TANGENT_ARC_TO_NV 0xFC 748 ARC_TO_NV 0xFE 749 RELATIVE_ARC_TO_NV 0xFF 750 751 Accepted by the <format> parameter of PathStringNV: 752 753 PATH_FORMAT_SVG_NV 0x9070 754 PATH_FORMAT_PS_NV 0x9071 755 756 Accepted by the <fontTarget> parameter of PathGlyphsNV, 757 PathGlyphRangeNV, and PathGlyphIndexRangeNV: 758 759 STANDARD_FONT_NAME_NV 0x9072 760 SYSTEM_FONT_NAME_NV 0x9073 761 FILE_NAME_NV 0x9074 762 763 Accepted by the <fontTarget> parameter of PathMemoryGlyphIndexArrayNV: 764 765 STANDARD_FONT_FORMAT_NV 0x936C 766 767 Accepted by the <handleMissingGlyph> parameter of PathGlyphsNV and 768 PathGlyphRangeNV: 769 770 SKIP_MISSING_GLYPH_NV 0x90A9 771 USE_MISSING_GLYPH_NV 0x90AA 772 773 Returned by PathGlyphIndexRangeNV: 774 775 FONT_GLYPHS_AVAILABLE_NV 0x9368 776 FONT_TARGET_UNAVAILABLE_NV 0x9369 777 FONT_UNAVAILABLE_NV 0x936A 778 FONT_UNINTELLIGIBLE_NV 0x936B // once was FONT_CORRUPT_NV 779 INVALID_ENUM 780 INVALID_VALUE 781 OUT_OF_MEMORY 782 783 Accepted by the <pname> parameter of PathParameterfNV, 784 PathParameterfvNV, GetPathParameterfvNV, PathParameteriNV, 785 PathParameterivNV, and GetPathParameterivNV: 786 787 PATH_STROKE_WIDTH_NV 0x9075 788 PATH_INITIAL_END_CAP_NV 0x9077 789 PATH_TERMINAL_END_CAP_NV 0x9078 790 PATH_JOIN_STYLE_NV 0x9079 791 PATH_MITER_LIMIT_NV 0x907A 792 PATH_INITIAL_DASH_CAP_NV 0x907C 793 PATH_TERMINAL_DASH_CAP_NV 0x907D 794 PATH_DASH_OFFSET_NV 0x907E 795 PATH_CLIENT_LENGTH_NV 0x907F 796 PATH_DASH_OFFSET_RESET_NV 0x90B4 797 798 PATH_FILL_MODE_NV 0x9080 799 PATH_FILL_MASK_NV 0x9081 800 PATH_FILL_COVER_MODE_NV 0x9082 801 PATH_STROKE_COVER_MODE_NV 0x9083 802 PATH_STROKE_MASK_NV 0x9084 803 PATH_STROKE_BOUND_NV 0x9086 804 805 Accepted by the <pname> parameter of PathParameterfNV and 806 PathParameterfvNV: 807 808 PATH_END_CAPS_NV 0x9076 809 PATH_DASH_CAPS_NV 0x907B 810 811 Accepted by the <fillMode> parameter of StencilFillPathNV and 812 StencilFillPathInstancedNV: 813 814 INVERT 815 COUNT_UP_NV 0x9088 816 COUNT_DOWN_NV 0x9089 817 PATH_FILL_MODE_NV see above 818 819 Accepted by the <color> parameter of PathColorGenNV, 820 GetPathColorGenivNV, and GetPathColorGenfvNV: 821 822 PRIMARY_COLOR 0x8577 // from OpenGL 1.3 823 PRIMARY_COLOR_NV 0x852C // from NV_register_combiners 824 SECONDARY_COLOR_NV 0x852D // from NV_register_combiners 825 826 Accepted by the <genMode> parameter of PathColorGenNV, PathTexGenNV, 827 ProgramPathFragmentInputGenNV: 828 829 NONE 830 EYE_LINEAR 831 OBJECT_LINEAR 832 PATH_OBJECT_BOUNDING_BOX_NV 0x908A 833 CONSTANT 834 835 Accepted by the <coverMode> parameter of CoverFillPathNV and 836 CoverFillPathInstancedNV: 837 838 CONVEX_HULL_NV 0x908B 839 BOUNDING_BOX_NV 0x908D 840 PATH_FILL_COVER_MODE_NV see above 841 842 Accepted by the <coverMode> parameter of CoverStrokePathNV and 843 CoverStrokePathInstancedNV: 844 845 CONVEX_HULL_NV see above 846 BOUNDING_BOX_NV see above 847 PATH_STROKE_COVER_MODE_NV see above 848 849 Accepted by the <transformType> parameter of 850 StencilFillPathInstancedNV, StencilStrokePathInstancedNV, 851 CoverFillPathInstancedNV, and CoverStrokePathInstancedNV: 852 853 NONE 854 TRANSLATE_X_NV 0x908E 855 TRANSLATE_Y_NV 0x908F 856 TRANSLATE_2D_NV 0x9090 857 TRANSLATE_3D_NV 0x9091 858 AFFINE_2D_NV 0x9092 859 AFFINE_3D_NV 0x9094 860 TRANSPOSE_AFFINE_2D_NV 0x9096 861 TRANSPOSE_AFFINE_3D_NV 0x9098 862 863 Accepted by the <transformType> parameter of TransformPathNV: 864 865 NONE 866 TRANSLATE_X_NV see above 867 TRANSLATE_Y_NV see above 868 TRANSLATE_2D_NV see above 869 TRANSLATE_3D_NV see above 870 AFFINE_2D_NV see above 871 AFFINE_3D_NV see above 872 TRANSPOSE_AFFINE_2D_NV see above 873 TRANSPOSE_AFFINE_3D_NV see above 874 875 Accepted by the <type> or <pathNameType> parameter of 876 StencilFillPathInstancedNV, StencilStrokePathInstancedNV, 877 CoverFillPathInstancedNV, CoverStrokePathInstancedNV, 878 GetPathMetricsNV, and GetPathSpacingNV: 879 880 UTF8_NV 0x909A 881 UTF16_NV 0x909B 882 883 Accepted by the <coverMode> parameter of CoverFillPathInstancedNV: 884 885 CONVEX_HULL_NV see above 886 BOUNDING_BOX_NV see above 887 BOUNDING_BOX_OF_BOUNDING_BOXES_NV 0x909C 888 PATH_FILL_COVER_MODE_NV see above 889 890 Accepted by the <coverMode> parameter of CoverStrokePathInstancedNV: 891 892 CONVEX_HULL_NV see above 893 BOUNDING_BOX_NV see above 894 BOUNDING_BOX_OF_BOUNDING_BOXES_NV see above 895 PATH_STROKE_COVER_MODE_NV see above 896 897 Accepted by the <pname> parameter of GetPathParameterfvNV and 898 GetPathParameterivNV: 899 900 PATH_COMMAND_COUNT_NV 0x909D 901 PATH_COORD_COUNT_NV 0x909E 902 PATH_DASH_ARRAY_COUNT_NV 0x909F 903 904 PATH_COMPUTED_LENGTH_NV 0x90A0 905 906 PATH_OBJECT_BOUNDING_BOX_NV see above 907 PATH_FILL_BOUNDING_BOX_NV 0x90A1 908 PATH_STROKE_BOUNDING_BOX_NV 0x90A2 909 910 Accepted by the <value> parameter of PathParameterfNV, 911 PathParameterfvNV, PathParameteriNV, and PathParameterivNV 912 when <pname> is one of PATH_END_CAPS_NV, PATH_INTIAL_END_CAP_NV, 913 PATH_TERMINAL_END_CAP_NV, PATH_DASH_CAPS_NV, PATH_INITIAL_DASH_CAP_NV, 914 and PATH_TERMINAL_DASH_CAP_NV: 915 916 FLAT 917 SQUARE_NV 0x90A3 918 ROUND_NV 0x90A4 919 TRIANGULAR_NV 0x90A5 920 921 Accepted by the <value> parameter of PathParameterfNV, 922 PathParameterfvNV, PathParameteriNV, and PathParameterivNV 923 when <pname> is PATH_JOIN_STYLE_NV: 924 925 NONE 926 ROUND_NV see above 927 BEVEL_NV 0x90A6 928 MITER_REVERT_NV 0x90A7 929 MITER_TRUNCATE_NV 0x90A8 930 931 Accepted by the <value> parameter of PathParameterfNV, 932 PathParameterfvNV, PathParameteriNV, and PathParameterivNV when 933 <pname> is PATH_DASH_OFFSET_RESET_NV: 934 935 MOVE_TO_RESETS_NV 0x90B5 936 MOVE_TO_CONTINUES_NV 0x90B6 937 938 Accepted by the <fontStyle> parameter of PathGlyphsNV, 939 PathGlyphRangeNV, and PathGlyphIndexRangeNV: 940 941 NONE 942 BOLD_BIT_NV 0x01 943 ITALIC_BIT_NV 0x02 944 945 Accepted by the <pname> parameter of GetBooleanv, GetIntegerv, 946 GetInteger64v, GetFloatv, and GetDoublev: 947 948 PATH_ERROR_POSITION_NV 0x90AB 949 950 PATH_FOG_GEN_MODE_NV 0x90AC 951 952 PATH_STENCIL_FUNC_NV 0x90B7 953 PATH_STENCIL_REF_NV 0x90B8 954 PATH_STENCIL_VALUE_MASK_NV 0x90B9 955 956 PATH_STENCIL_DEPTH_OFFSET_FACTOR_NV 0x90BD 957 PATH_STENCIL_DEPTH_OFFSET_UNITS_NV 0x90BE 958 959 PATH_COVER_DEPTH_FUNC_NV 0x90BF 960 961 Accepted as a bit within the <metricQueryMask> parameter of 962 GetPathMetricRangeNV or GetPathMetricsNV: 963 964 // per-glyph metrics 965 GLYPH_WIDTH_BIT_NV 0x01 966 GLYPH_HEIGHT_BIT_NV 0x02 967 GLYPH_HORIZONTAL_BEARING_X_BIT_NV 0x04 968 GLYPH_HORIZONTAL_BEARING_Y_BIT_NV 0x08 969 GLYPH_HORIZONTAL_BEARING_ADVANCE_BIT_NV 0x10 970 GLYPH_VERTICAL_BEARING_X_BIT_NV 0x20 971 GLYPH_VERTICAL_BEARING_Y_BIT_NV 0x40 972 GLYPH_VERTICAL_BEARING_ADVANCE_BIT_NV 0x80 973 GLYPH_HAS_KERNING_BIT_NV 0x100 974 975 // per-font face metrics 976 FONT_X_MIN_BOUNDS_BIT_NV 0x00010000 977 FONT_Y_MIN_BOUNDS_BIT_NV 0x00020000 978 FONT_X_MAX_BOUNDS_BIT_NV 0x00040000 979 FONT_Y_MAX_BOUNDS_BIT_NV 0x00080000 980 FONT_UNITS_PER_EM_BIT_NV 0x00100000 981 FONT_ASCENDER_BIT_NV 0x00200000 982 FONT_DESCENDER_BIT_NV 0x00400000 983 FONT_HEIGHT_BIT_NV 0x00800000 984 FONT_MAX_ADVANCE_WIDTH_BIT_NV 0x01000000 985 FONT_MAX_ADVANCE_HEIGHT_BIT_NV 0x02000000 986 FONT_UNDERLINE_POSITION_BIT_NV 0x04000000 987 FONT_UNDERLINE_THICKNESS_BIT_NV 0x08000000 988 FONT_HAS_KERNING_BIT_NV 0x10000000 989 FONT_NUM_GLYPH_INDICES_BIT_NV 0x20000000 990 991 Accepted by the <pathListMode> parameter of GetPathSpacingNV: 992 993 ACCUM_ADJACENT_PAIRS_NV 0x90AD 994 ADJACENT_PAIRS_NV 0x90AE 995 FIRST_TO_REST_NV 0x90AF 996 997 Accepted by the <pname> parameter of GetPathColorGenivNV, 998 GetPathColorGenfvNV, GetPathTexGenivNV and GetPathTexGenfvNV: 999 1000 PATH_GEN_MODE_NV 0x90B0 1001 PATH_GEN_COEFF_NV 0x90B1 1002 1003 Accepted by the <pname> parameter of GetPathColorGenivNV and 1004 GetPathColorGenfvNV: 1005 1006 PATH_GEN_COLOR_FORMAT_NV 0x90B2 1007 1008 Accepted by the <pname> parameter of GetPathTexGenivNV and 1009 GetPathTexGenfvNV: 1010 1011 PATH_GEN_COMPONENTS_NV 0x90B3 1012 1013 Accepted by the <programInterface> parameter of GetProgramInterfaceiv, 1014 GetProgramResourceIndex, GetProgramResourceName, GetProgramResourceiv, 1015 GetProgramResourcefvNV, and GetProgramResourceLocation: 1016 1017 FRAGMENT_INPUT_NV 0x936D 1018 1019 Accepted in the <props> array of GetProgramResourceiv: 1020 1021 PATH_GEN_MODE_NV see above 1022 PATH_GEN_COMPONENTS_NV see above 1023 1024 Accepted in the <props> array of GetProgramResourcefvNV: 1025 1026 PATH_GEN_COEFF_NV see above 1027 1028Additions to Chapter 2 of the OpenGL 3.2 (unabridged) Specification 1029(OpenGL Operation) 1030 1031 Add to the end of Section 2.12.1 (Matrices) with 1032 EXT_direct_state_access language applied... 1033 1034 "The command 1035 1036 void MatrixLoad3x2fNV(enum matrixMode, const float *m); 1037 1038 is equivalent to: 1039 1040 const float equiv_3x2matrix[16] = { 1041 m[0], m[2], 0, m[4], 1042 m[1], m[3], 0, m[5], 1043 0, 0, 1, 0, 1044 0, 0, 0, 1 1045 }; 1046 MatrixLoadTransposefEXT(matrixMode, equiv_3x2matrix); 1047 1048 The command 1049 1050 void MatrixLoad3x3fNV(enum matrixMode, const float *m); 1051 1052 is equivalent to: 1053 1054 const float equiv_3x3matrix[16] = { 1055 m[0], m[3], 0, m[6], 1056 m[1], m[4], 0, m[7], 1057 0, 0, 1, 0, 1058 m[2], m[5], 0, m[8], 1059 }; 1060 MatrixLoadTransposefEXT(matrixMode, equiv_3x3matrix); 1061 1062 The command 1063 1064 void MatrixLoadTranspose3x3fNV(enum matrixMode, const float *m); 1065 1066 is equivalent to: 1067 1068 const float equiv_3x3matrix[16] = { 1069 m[0], m[1], 0, m[2], 1070 m[3], m[4], 0, m[5], 1071 0, 0, 1, 0, 1072 m[6], m[7], 0, m[8], 1073 }; 1074 MatrixLoadTransposefEXT(matrixMode, equiv_3x3matrix); 1075 1076 The command 1077 1078 void MatrixMult3x2fNV(enum matrixMode, const float *m); 1079 1080 is equivalent to: 1081 1082 const float equiv_3x2matrix[16] = { 1083 m[0], m[2], 0, m[4], 1084 m[1], m[3], 0, m[5], 1085 0, 0, 1, 0, 1086 0, 0, 0, 1 1087 }; 1088 MatrixMultTransposefEXT(matrixMode, equiv_3x2matrix); 1089 1090 The command 1091 1092 void MatrixMult3x3fNV(enum matrixMode, const float *m); 1093 1094 is equivalent to: 1095 1096 const float equiv_3x3matrix[16] = { 1097 m[0], m[3], 0, m[6], 1098 m[1], m[4], 0, m[7], 1099 0, 0, 1, 0, 1100 m[2], m[5], 0, m[8], 1101 }; 1102 MatrixMultTransposefEXT(matrixMode, equiv_3x3matrix); 1103 1104 The command 1105 1106 void MatrixMultTranspose3x3fNV(enum matrixMode, const float *m); 1107 1108 is equivalent to: 1109 1110 const float equiv_3x3matrix[16] = { 1111 m[0], m[1], 0, m[2], 1112 m[3], m[4], 0, m[5], 1113 0, 0, 1, 0, 1114 m[6], m[7], 0, m[8], 1115 }; 1116 MatrixMultTransposefEXT(matrixMode, equiv_3x3matrix);" 1117 1118 Modify the ARB_program_interface_query language as follows... 1119 1120 Add to the "query properties of the interfaces of a program object" 1121 paragraph, so the "supported values of <programInterface>" includes: 1122 1123 * FRAGMENT_INPUT_NV corresponds to the set of active input variables 1124 used by the fragment shader stage of <program> (if a fragment 1125 stage exists). (This may be different from PROGRAM_INPUT except 1126 when the first shader stage is the fragment stage when they will 1127 be identical.) 1128 1129 Change this sentence about when locations are assigned to include 1130 FRAGMENT_INPUT_NV so it reads: 1131 1132 "When a program is linked successfully, active variables in the 1133 UNIFORM, PROGRAM_INPUT, FRAGMENT_INPUT_NV, PROGRAM_OUTPUT interface, 1134 or in any of the subroutine uniform interfaces, are assigned one or 1135 more signed integer /locations/." 1136 1137 Amend Table X.1 "GetProgramResourceiv properties and supported 1138 interfaces" to add FRAGMENT_INPUT_NV to all the properties that 1139 allow PROGRAM_INPUT. Specifically: 1140 1141 * NAME_LENGTH 1142 * TYPE 1143 * ARRAY_SIZE 1144 * REFERENCED_BY_*_SHADER 1145 * LOCATION 1146 * IS_PER_PATCH (will always be false for FRAGMENT_INPUT_NV) 1147 1148 Further amend Table X.1 "GetProgramResourceiv properties with two 1149 more properties for fragment input path generation state: 1150 1151 Property Supported Interfaces 1152 --------------------------- ---------------------------------------- 1153 PATH_GEN_MODE_NV FRAGMENT_INPUT_NV 1154 PATH_GEN_COMPONENTS_NV FRAGMENT_INPUT_NV 1155 1156 Amend the discussion of GetProgramResourceiv properties, adding: 1157 1158 "For the property PATH_GEN_MODE_NV, a single integer identifying 1159 the path generation mode of an active variable is written to 1160 <params>. The integer returned is one of NONE, OBJECT_LINEAR, 1161 PATH_OBJECT_BOUNDING_BOX_NV, or EYE_LINEAR based on how 1162 ProgramPathFragmentInputGenNV last specified the program resource's 1163 path generation mode. The initial state is NONE. 1164 1165 For the property PATH_GEN_COMPONENTS_NV, a single integer identifying 1166 the number of generated path components an active variable is written 1167 to <params>. The integer returned is between 0 and 4 based on how 1168 ProgramPathFragmentInputGenNV last specified the program resource's 1169 path generation number of components. The initial state is 0." 1170 1171 Amend the list of tokens supported for the <programInterface> parameter of 1172 GetProgramResourceLocation to include FRAGMENT_INPUT_NV so the relevant 1173 sentence reads: 1174 1175 "For GetProgramResourceLocation, <programInterface> must be one 1176 of UNIFORM, PROGRAM_INPUT, FRAGMENT_INPUT_NV, PROGRAM_OUTPUT, 1177 VERTEX_SUBROUTINE_UNIFORM, TESS_CONTROL_SUBROUTINE_UNIFORM, 1178 TESS_EVALUATION_SUBROUTINE_UNIFORM, GEOMETRY_SUBROUTINE_UNIFORM, 1179 FRAGMENT_SUBROUTINE_UNIFORM, or COMPUTE_SUBROUTINE_UNIFORM." 1180 1181 After the discussion of GetProgramResourceiv, add: 1182 1183 "The command 1184 1185 void GetProgramResourcefvNV(uint program, enum programInterface, 1186 uint index, sizei propCount, 1187 const enum *props, sizei bufSize, 1188 sizei *length, float *params); 1189 1190 operates in the same manner as GetProgramResourceiv expect the 1191 returned parameters values are floating-point and the only valid 1192 value of <programInterface> is FRAGMENT_INPUT_NV and the only valid value 1193 for the elements of the <props> array is PATH_GEN_COEFF_NV; otherwise 1194 INVALID_ENUM is generated. 1195 1196 For the property PATH_GEN_COEFF_NV, sixteen floating-point values 1197 are written to <params> (limited to writing <bufSize> floating-point 1198 values)." 1199 1200Additions to Chapter 3 of the OpenGL 3.2 (unabridged) Specification 1201(Rasterization) 1202 1203 Append to the end of the "Shader Inputs" subsection of Section 3.12.2 1204 "Shader Execution": 1205 1206 The command 1207 1208 void ProgramPathFragmentInputGenNV(uint program, 1209 int location, 1210 enum genMode, 1211 int components, 1212 const float *coeffs); 1213 1214 controls how a user-defined (non-built-in) fragment input of a 1215 GLSL program object is computed for fragment shading operations that 1216 occur as a result of CoverFillPathNV or CoverStrokePathNV. 1217 1218 /program/ names a GLSL program object. If /program/ has not been 1219 successfully linked, the error INVALID_OPERATION is generated. 1220 1221 The given fragment input generation state is loaded into the fragment 1222 input variable location identified by /location/. This location 1223 is a value returned either by GetProgramResourceLocation with a 1224 /programInterface/ of FRAGMENT_INPUT_NV and a given fragment shader 1225 input variable name or by GetProgramResourceiv with FRAGMENT_INPUT_NV 1226 for the /programInterface/ and LOCATION for the property for a given 1227 fragment input resource index. 1228 1229 If the value of location is -1, the ProgramPathFragmentInputGenNV command 1230 will silently ignore the command, and the program's path fragment input 1231 generation state will not be changed. 1232 1233 If any of the following conditions occur, an INVALID_OPERATION error 1234 is generated by the ProgramPathFragmentInputGenNV, and no state is changed: 1235 1236 * if the size indicated in the /components/ of the 1237 ProgramPathFragmentInputGenNV command used does not match the 1238 size of the fragment input scalar or vector declared in the 1239 shader, 1240 1241 * if the fragment input declared in the shader is not 1242 single-precision floating-point, or 1243 1244 * if no fragment input variable with a location of /location/ 1245 exists in the program object named by /program/ and location 1246 is not -1, or 1247 1248 * if the fragment input declared in the shader is a built-in 1249 variables (i.e. prefixed by "gl_"). 1250 1251 When covering paths, fragment input variables are interpolated at 1252 each shaded fragment based on the corresponding fragment input 1253 generation state specified by ProgramPathFragmentInputGenNV for 1254 each respective fragment input. 1255 1256 The /genMode/, /components/, and /coeffs/ parameters are used to 1257 generate the fragment input variable values identically as the 1258 PathTexGenNV command's corresponding parameters except it is a 1259 fragment input that is generated rather than a texture coordinate set 1260 (see the "TEXTURE COORDINATE SET GENERATION FOR PATH COVER COMMANDS" 1261 discussion in section 5.X.2.2 "Path Covering"). Because there is 1262 no associated texture coordinate set, the sc, tc, rc, and qc values 1263 when discussing PathTexGenNV are always zero when generating fragment 1264 input variables. 1265 1266 When covering paths, if a fragment input variable has not had its 1267 path fragment input generation state successfully generated, it as 1268 if the values of this variable are always initialized to zero when 1269 the fragment shader is executing. 1270 1271 Also when covering paths, GLSL fragment shaders support the following 1272 built-in fragment input variables: 1273 1274 in vec4 gl_TexCoord[gl_MaxTextureCoords]; 1275 in vec4 gl_Color 1276 in vec4 gl_FrontColor; 1277 in vec4 gl_BackColor; 1278 in vec4 gl_SecondaryColor; 1279 in vec4 gl_FrontSecondaryColor; 1280 in vec4 gl_BackSecondaryColor; 1281 in float gl_FogFragCoord; 1282 1283 These respectively are initialized to the fragment input generated 1284 coordinates of PathTexGenNV, PathColorGenNV for GL_PRIMARY_COLOR_NV 1285 (front or back), PathColorGenNV for GL_SECONDARY_COLOR_NV (front or 1286 back), and glPathFogGenNV." 1287 1288Additions to Chapter 4 of the OpenGL 3.2 (unabridged) Specification 1289(Per-Fragment Operations and the Frame Buffer) 1290 1291 None 1292 1293Additions to Chapter 5 of the OpenGL 3.2 (unabridged) Specification 1294(Special Functions) 1295 1296 -- Insert section 5.X "Path Rendering" after 5.3 "Feedback" 1297 1298 5.X Path Rendering 1299 1300 5.X.1 Path Specification 1301 1302 PATH COMMANDS 1303 1304 Paths are specified as a sequence of path commands; each path command 1305 has an associated sequence of floating-point coordinates with the 1306 number of such coordinates depending on the specific path command. 1307 Coordinates are specified in a sequence independent from the path 1308 command sequence; coordinates from the coordinate sequence are matched 1309 up with (associated with) commands, in the order of the command, 1310 with coordinates extracted from the front of the coordinate sequence. 1311 1312 Valid path commands are listed in table 5.pathCommands. Each path 1313 command is listed with its associated token, description, character 1314 alias, count of associated coordinates. 1315 1316 As an example of how path commands associated with path coordinates, 1317 if the command sequence was MOVE_TO_NV, LINE_TO_NV, CUBIC_CURVE_TO_NV, 1318 CLOSE_PATH_NV and the coordinates were 1, 2, 3, 4, 5, 6, 7, 8, 9, 1319 10, the MOVE_TO_NV command would be matched to coordinates 1 and 2, 1320 LINE_TO_NV would be matched to 3 and 4, CUBIC_CURVE_TO_NV would be 1321 matched to 5, 6, 7, 8, 9, 10, and CLOSE_PATH_NV would be matched to 1322 no coordinates. 1323 1324 Path commands are processed in their sequence order to generate the 1325 path's outline. The outline generation process maintains three 2D 1326 (x,y) state variables for each path processed: the start position 1327 (sp), the current position (cp), and the prior end point (pep); 1328 /sp/, /cp/ and /pep/ are initially (0,0) when a path starts being 1329 processed. 1330 1331 Table 5.pathCommands: Path Commands 1332 1333 Character Coordinate 1334 Token Description alias count 1335 ========================== ===================== ========== ========== 1336 MOVE_TO_NV Absolute move 'M' 2 1337 current point 1338 RELATIVE_MOVE_TO_NV Relative move 'm' 2 1339 current point 1340 -------------------------- --------------------- ---------- ---------- 1341 CLOSE_PATH_NV Close path 'Z' or 'z' 0 1342 RESTART_PATH_NV Reset the path - 0 1343 -------------------------- --------------------- ---------- ---------- 1344 LINE_TO_NV Absolute line 'L' 2 1345 RELATIVE_LINE_TO_NV Relative line 'l' 2 1346 -------------------------- --------------------- ---------- ---------- 1347 HORIZONTAL_LINE_TO_NV Absolute horizontal 'H' 1 1348 line 1349 RELATIVE_HORIZONTAL- Relative horizontal 'h' 1 1350 _LINE_TO_NV line 1351 VERTICAL_LINE_TO_NV Absolute vertical 'V' 1 1352 line 1353 RELATIVE_VERTICAL- Relative vertical 'v' 1 1354 _LINE_TO_NV line 1355 -------------------------- --------------------- ---------- ---------- 1356 QUADRATIC_CURVE_TO_NV Absolute quadratic 'Q' 4 1357 Bezier segment 1358 RELATIVE- Relative quadratic 'q' 4 1359 _QUADRATIC_CURVE_TO_NV Bezier segment 1360 -------------------------- --------------------- ---------- ---------- 1361 CUBIC_CURVE_TO_NV Absolute cubic 'C' 6 1362 Bezier segment 1363 RELATIVE_CUBIC_CURVE_TO_NV Relative cubic 'c' 6 1364 Bezier segment 1365 -------------------------- --------------------- ---------- ---------- 1366 SMOOTH- Absolute smooth 'T' 2 1367 _QUADRATIC_CURVE_TO_NV quadratic Bezier 1368 segment 1369 RELATIVE_SMOOTH- Relative smooth 't' 2 1370 _QUADRATIC_CURVE_TO_NV quadratic Bezier 1371 segment 1372 -------------------------- --------------------- ---------- ---------- 1373 SMOOTH- Absolute smooth 'S' 4 1374 _CUBIC_CURVE_TO_NV cubic Bezier segment 1375 RELATIVE_SMOOTH- Relative smooth 's' 4 1376 _CUBIC_CURVE_TO_NV cubic Bezier segment 1377 -------------------------- --------------------- ---------- ---------- 1378 SMALL_CCW_ARC_TO_NV Absolute small-sweep - 5 1379 counterclockwise 1380 partial elliptical 1381 arc segment 1382 RELATIVE- Relative small-sweep - 5 1383 _SMALL_CCW_ARC_TO_NV counterclockwise 1384 partial elliptical 1385 arc segment 1386 SMALL_CW_ARC_TO_NV Absolute small-sweep - 5 1387 clockwise partial 1388 elliptical arc 1389 segment 1390 RELATIVE- Relative small-sweep - 5 1391 _SMALL_CW_ARC_TO_NV clockwise partial 1392 elliptical arc 1393 segment 1394 LARGE_CCW_ARC_TO_NV Absolute large-sweep - 5 1395 counterclockwise 1396 partial elliptical 1397 arc segment 1398 RELATIVE- Relative large-sweep - 5 1399 _LARGE_CCW_ARC_TO_NV counterclockwise 1400 partial elliptical 1401 arc segment 1402 LARGE_CW_ARC_TO_NV Absolute large-sweep - 5 1403 clockwise partial 1404 elliptical arc 1405 segment 1406 RELATIVE- Relative large-sweep - 5 1407 _LARGE_CW_ARC_TO_NV clockwise partial 1408 elliptical arc 1409 segment 1410 -------------------------- --------------------- ---------- ---------- 1411 CONIC_CURVE_TO_NV Absolute conic 'W' 5 1412 (rational Bezier) 1413 segment 1414 RELATIVE- Relative conic 'w' 5 1415 _CONIC_CURVE_TO_NV (rational Bezier) 1416 segment 1417 -------------------------- --------------------- ---------- ---------- 1418 ROUNDED_RECT_NV Absolute rounded - 5 1419 rectangle with 1420 uniform circular 1421 corners (1 radius) 1422 RELATIVE_ROUNDED_RECT_NV Relative rounded - 5 1423 rectangle with 1424 uniform circular 1425 corners (1 radius) 1426 ROUNDED_RECT2_NV Absolute rounded - 6 1427 rectangle with 1428 uniform elliptical 1429 corners (2 x&y radii) 1430 RELATIVE_ROUNDED_RECT2_NV Relative rounded - 6 1431 rectangle with 1432 uniform elliptical 1433 corners (2 x&y radii) 1434 ROUNDED_RECT4_NV Absolute rounded - 8 1435 rectangle with 1436 varying circular 1437 corners (4 radii) 1438 RELATIVE_ROUNDED_RECT4_NV Relative rounded - 8 1439 rectangle with 1440 varying circular 1441 corners (4 radii) 1442 ROUNDED_RECT8_NV Absolute rounded - 12 1443 rectangle with 1444 varying elliptical 1445 corners (8 radii) 1446 RELATIVE_ROUNDED_RECT8_NV Relative rounded - 12 1447 rectangle with 1448 varying elliptical 1449 corners (8 radii) 1450 -------------------------- --------------------- ---------- ---------- 1451 DUP_FIRST_- Absolute cubic Bezier - 4 1452 CUBIC_CURVE_TO_NV segment, duplicating 1453 first control point 1454 DUP_LAST_CUBIC_CURVE_TO_NV Absolute cubic Bezier - 4 1455 segment, duplicating 1456 last control point 1457 RECT_NV Closed absolute - 4 1458 rectangle 1459 RELATIVE_RECT_NV Closed relative - 4 1460 rectangle 1461 -------------------------- --------------------- ---------- ---------- 1462 CIRCULAR_CCW_ARC_TO_NV Absolute - 5 1463 counterclockwise 1464 circular arc segment 1465 CIRCULAR_CW_ARC_TO_NV Absolute clockwise - 5 1466 circular arc segment 1467 CIRCULAR_TANGENT_ARC_TO_NV Absolute circular - 5 1468 tangential 1469 arc segment 1470 -------------------------- --------------------- ---------- ---------- 1471 ARC_TO_NV Absolute general 'A' 7 1472 elliptical arc 1473 RELATIVE_ARC_TO_NV Relative general 'a' 7 1474 elliptical arc 1475 -------------------------- --------------------- ---------- ---------- 1476 1477 Table 5.pathEquations provides for each path command, as relevant, 1478 the command's path segment parametric equation, equations for the 1479 updated current point (ncp) and equations for the updated prior 1480 end point (npep). After each command in a path is processed in the 1481 sequence, the new current point, prior end point, and start point 1482 (if changed) update the current point, prior end point, and start 1483 point for the next path command to be processed in the sequence. So: 1484 1485 cp = ncp 1486 pep = npep 1487 1488 Each path segment parametric equation is parameterized by a variable 1489 /t/ ranging from 0.0 to 1.0. So the outline is traced by evaluating 1490 each path command's path segment parametric equation continuously 1491 as /t/ varies from 0.0 to 1.0. 1492 1493 With the exception of the MOVE_TO_NV, RELATIVE_MOVE_TO_NV, 1494 RESTART_PATH_NV, RECT_NV, RELATIVE_RECT_NV, ROUNDED_RECT_NV, 1495 RELATIVE_ROUNDED_RECT_NV, ROUNDED_RECT2_NV, RELATIVE_ROUNDED_RECT2_NV, 1496 ROUNDED_RECT4_NV, RELATIVE_ROUNDED_RECT4_NV, ROUNDED_RECT8_NV, 1497 RELATIVE_ROUNDED_RECT8_NV, CIRCULAR_CCW_ARC_TO_NV, and 1498 CIRCULAR_CW_ARC_TO_NV commands, the commands are specified such that 1499 C0 continuity of the outline is guaranteed at path command segment 1500 end-points. 1501 1502 The MOVE_TO_NV, RELATIVE_MOVE_TO_NV, RESTART_PATH_NV, RECT_NV, 1503 RELATIVE_RECT_NV, ROUNDED_RECT_NV, RELATIVE_ROUNDED_RECT_NV, 1504 ROUNDED_RECT2_NV, RELATIVE_ROUNDED_RECT2_NV, 1505 ROUNDED_RECT4_NV, RELATIVE_ROUNDED_RECT4_NV, ROUNDED_RECT8_NV, 1506 RELATIVE_ROUNDED_RECT8_NV, CIRCULAR_CCW_ARC_TO_NV, and 1507 CIRCULAR_CW_ARC_TO_NV commands update the start position (sp) to 1508 the value of these command's new current point (ncp). 1509 1510 The MOVE_TO_NV, RELATIVE_MOVE_TO_NV, RECT_NV, 1511 RELATIVE_RECT_NV, ROUNDED_RECT_NV, RELATIVE_ROUNDED_RECT_NV, 1512 ROUNDED_RECT2_NV, RELATIVE_ROUNDED_RECT2_NV, 1513 ROUNDED_RECT4_NV, RELATIVE_ROUNDED_RECT4_NV, ROUNDED_RECT8_NV, 1514 RELATIVE_ROUNDED_RECT8_NV, commands unconditionally change the start 1515 position (sp) to value of these command's new current point (ncp) so: 1516 1517 sp = ncp 1518 1519 The CIRCULAR_CCW_ARC_TO_NV and CIRCULAR_CW_ARC_TO_NV commands 1520 conditionally change sp to the command's ncp but only the sp has not 1521 been specified by any prior command other than CLOSE_PATH_NV in the 1522 path's command sequence since the beginning of the path's command 1523 sequence or last RESTART_PATH_NV. When these circular arc commands 1524 change the sp to the command's ncp, it implies the initial implicit 1525 line these commands generate from sp to ncp will be zero length. 1526 (This behavior is to match the semantics of PostScript.) 1527 1528 Moving of the start position creates a discontinuity in the outline 1529 so starts a new subpath within the path. 1530 1531 Table 5.pathEquations: Path Equations 1532 1533 Path segment new current new prior end 1534 Token parametric equation point equation point equation 1535 ========================== ====================================== ================== ======================= 1536 MOVE_TO_NV - ncp.x = c[0] npep.x = c[0] 1537 ncp.y = c[1] npep.y = c[1] 1538 RELATIVE_MOVE_TO_NV - ncp.x = cp.x+c[0] npep.x = cp.x+c[0] 1539 ncp.y = cp.y+c[1] npep.y = cp.y+c[1] 1540 -------------------------- -------------------------------------- ------------------ ----------------------- 1541 CLOSE_PATH_NV x = (1-t)*cp.x + t*sp.x ncp.x = sp.x npep.x = sp.x 1542 y = (1-t)*cp.y + t*sp.y ncp.y = sp.y npep.y = sp.y 1543 RESTART_PATH_NV - ncp.x = 0 npep.x = 0 1544 ncp.y = 0 npep.y = 0 1545 -------------------------- -------------------------------------- ------------------ ----------------------- 1546 LINE_TO_NV x = (1-t)*cp.x + t*c[0] ncp.x = c[0] npep.x = c[0] 1547 y = (1-t)*cp.y + t*c[1] ncp.y = c[1] npep.y = c[1] 1548 RELATIVE_LINE_TO_NV x = (1-t)*cp.x + t*(c[0]+cp.x) ncp.x = cp.x+c[0] npep.x = cp.x+c[0] 1549 y = (1-t)*cp.y + t*(c[1]+cp.y) ncp.y = cp.y+c[1] npep.y = cp.y+c[1] 1550 -------------------------- -------------------------------------- ------------------ ----------------------- 1551 HORIZONTAL_LINE_TO_NV x = (1-t)*cp.x + t*sp.x ncp.x = c[0] npep.x = c[0] 1552 y = cp.y ncp.y = cp.y npep.y = cp.y 1553 RELATIVE_HORIZONTAL- x = (1-t)*cp.x + t*(c[0]+cp.x) ncp.x = cp.x+c[0] npep.x = cp.x+c[0] 1554 _LINE_TO_NV y = cp.y ncp.y = cp.y npep.y = cp.y 1555 VERTICAL_LINE_TO_NV x = cp.x ncp.x = cp.x npep.x = cp.x 1556 y = (1-t)*cp.y + t*sp.y ncp.y = c[0] npep.y = c[0] 1557 RELATIVE_VERTICAL- x = cp.x ncp.x = cp.x npep.x = cp.x 1558 _LINE_TO_NV y = (1-t)*cp.y + t*(c[0]+cp.y) ncp.y = cp.y+c[0] npep.y = cp.y+c[0] 1559 -------------------------- -------------------------------------- ------------------ ----------------------- 1560 QUADRATIC_CURVE_TO_NV x = (1-t)^2*cp.x + ncp.x = c[2] npep.x = c[0] 1561 2*(1-t)*t*c[0] + ncp.y = c[3] npep.y = c[1] 1562 t^2*c[2] 1563 y = (1-t)^2*cp.y + 1564 2*(1-t)*t*c[1] + 1565 t^2*c[3] 1566 RELATIVE- x = (1-t)^2*cp.x + ncp.x = cp.x+c[2] npep.x = cp.x+c[0] 1567 _QUADRATIC_CURVE_TO_NV 2*(1-t)*t*(c[0]+cp.x) + ncp.y = cp.x+c[3] npep.y = cp.y+c[1] 1568 t^2*(c[2]+cp.x) 1569 y = (1-t)^2*cp.y + 1570 2*(1-t)*t*(c[1]+cp.y) + 1571 t^2*(c[3]+cp.y) 1572 -------------------------- -------------------------------------- ------------------ ----------------------- 1573 CUBIC_CURVE_TO_NV x = (1-t)^3*cp.x + ncp.x = c[4] npep.x = c[2] 1574 3*(1-t)^2*t*c[0] + ncp.y = c[5] npep.y = c[3] 1575 3*(1-t)*t^2*c[2] + 1576 t^3*c[4] 1577 y = (1-t)^3*cp.y + 1578 3*(1-t)^2*t*c[1] + 1579 3*(1-t)*t^2*c[3] + 1580 t^3*c[5] 1581 RELATIVE_CUBIC_CURVE_TO_NV x = (1-t)^3*cp.x + ncp.x = cp.x+c[4] npep.x = cp.x+c[2] 1582 3*(1-t)^2*t*(c[0]+cp.x) + ncp.y = cp.y+c[5] npep.y = cp.y+c[3] 1583 3*(1-t)*t^2*(c[2]+cp.x) + 1584 t^3*(c[4]+cp.x) 1585 y = (1-t)^3*cp.y + 1586 3*(1-t)^2*t*(c[1]+cp.y) + 1587 3*(1-t)*t^2*(c[3]+cp.y) + 1588 t^3*(c[5]+cp.y) 1589 -------------------------- -------------------------------------- ------------------ ----------------------- 1590 SMOOTH- x = (1-t)^2*cp.x + ncp.x = c[0] npep.x = 2*cp.x-pep.x 1591 _QUADRATIC_CURVE_TO_NV 2*(1-t)*t*(2*cp.x-pep.x) + ncp.y = c[1] npep.y = 2*cp.y-pep.y 1592 t^2*c[0] 1593 y = (1-t)^2*cp.y + 1594 2*(1-t)*t*(2*cp.y-pep.y) + 1595 t^2*c[1] 1596 RELATIVE_SMOOTH- x = (1-t)^2*cp.x + ncp.x = cp.x+c[0] npep.x = 2*cp.x-pep.x 1597 QUADRATIC_CURVE_TO_NV 2*(1-t)*t*(2*cp.x-pep.x) + ncp.y = cp.y+c[1] npep.y = 2*cp.y-pep.y 1598 t^2*(c[0]+cp.x) 1599 y = (1-t)^2*cp.y + 1600 2*(1-t)*t*(2*cp.y-pep.y) + 1601 t^2*(c[1]+cp.y) 1602 1603 SMOOTH- x = (1-t)^3*cp.x + ncp.x = c[2] npep.x = c[0] 1604 _CUBIC_CURVE_TO_NV 3*(1-t)^2*t*(2*cp.x-pep.x) + ncp.y = c[3] npep.y = c[1] 1605 3*(1-t)*t^2*c[0] + 1606 t^3*c[2] 1607 y = (1-t)^3*cp.y + 1608 3*(1-t)^2*t*(2*cp.y-pep.y) + 1609 3*(1-t)*t^2*c[1] + 1610 t^3*c[3] 1611 RELATIVE_SMOOTH- x = (1-t)^3*cp.x + ncp.x = cp.x+c[2] npep.x = cp.x+c[0] 1612 _CUBIC_CURVE_TO_NV 3*(1-t)^2*t*(2*cp.x-pep.x) + ncp.y = cp.y+c[3] npep.y = cp.y+c[1] 1613 3*(1-t)*t^2*(c[0]+cp.x) + 1614 t^3*(c[2]+cp.x) 1615 y = (1-t)^3*cp.y + 1616 3*(1-t)^2*t*(2*cp.y-pep.y) + 1617 3*(1-t)*t^2*(c[1]+cp.y) + 1618 t^3*(c[3]+cp.y) 1619 -------------------------- -------------------------------------- ------------------ ----------------------- 1620 SMALL_CCW_ARC_TO_NV x = arc_x(c,rv,rh,phi, ncp.x = c[3] npep.x = c[3] 1621 theta1,dtheta,t) ncp.y = c[4] npep.y = c[4] 1622 y = arc_y(c,rv,rh,phi, 1623 theta1,dtheta,t) 1624 RELATIVE- x = arc_x(c,rv,rh,phi, ncp.x = c[3] npep.x = cp.x+c[3] 1625 _SMALL_CCW_ARC_TO_NV theta1,dtheta,t) ncp.y = c[4] npep.y = cp.y+c[4] 1626 y = arc_y(c,rv,rh,phi, 1627 theta1,dtheta,t) 1628 SMALL_CW_ARC_TO_NV x = arc_x(c,rv,rh,phi, ncp.x = c[3] npep.x = c[3] 1629 theta1,dtheta,t) ncp.y = c[4] npep.y = c[4] 1630 y = arc_y(c,rv,rh,phi, 1631 theta1,dtheta,t) 1632 RELATIVE- x = arc_x(c,rv,rh,phi, ncp.x = c[3] npep.x = cp.x+c[3] 1633 _SMALL_CW_ARC_TO_NV theta1,dtheta,t) ncp.y = c[4] npep.y = cp.y+c[4] 1634 y = arc_y(c,rv,rh,phi, 1635 theta1,dtheta,t) 1636 LARGE_CCW_ARC_TO_NV x = arc_x(c,rv,rh,phi, ncp.x = c[3] npep.x = c[3] 1637 theta1,dtheta,t) ncp.y = c[4] npep.y = c[4] 1638 y = arc_y(c,rv,rh,phi, 1639 theta1,dtheta,t) 1640 RELATIVE- x = arc_x(c,rv,rh,phi, ncp.x = c[3] npep.x = cp.x+c[3] 1641 _LARGE_CCW_ARC_TO_NV theta1,dtheta,t) ncp.y = c[4] npep.y = cp.y+c[4] 1642 y = arc_y(c,rv,rh,phi, 1643 theta1,dtheta,t) 1644 LARGE_CW_ARC_TO_NV x = arc_x(c,rv,rh,phi, ncp.x = c[3] npep.x = c[3] 1645 theta1,dtheta,t) ncp.y = c[4] npep.y = c[4] 1646 y = arc_y(c,rv,rh,phi, 1647 theta1,dtheta,t) 1648 RELATIVE- x = arc_x(c,rv,rh,phi, ncp.x = c[3] npep.x = cp.x+c[3] 1649 _SMALL_CW_ARC_TO_NV theta1,dtheta,t) ncp.y = c[4] npep.y = cp.y+c[4] 1650 y = arc_y(c,rv,rh,phi, 1651 theta1,dtheta,t) 1652 -------------------------- -------------------------------------- ------------------ ----------------------- 1653 CONIC_CURVE_TO_NV WHEN c[4] > 0: ncp.x = c[2] npep.x = c[0] 1654 x = ( (1-t)^2*cp.x + ncp.y = c[3] npep.y = c[1] 1655 2*(1-t)*t*c[0]*c[4] + 1656 t^2*c[2] ) / 1657 ( (1-t)^2 + 1658 2*(1-t)*t*c[4] + 1659 t^2*c[2] ) 1660 y = ( 1-t)^2*cp.y + 1661 2*(1-t)*t*c[1]*w + 1662 t^2*c[3] ) / 1663 ( (1-t)^2 + 1664 2*(1-t)*t*c[4] + 1665 t^2*c[2] ), 1666 OTHERWISE: 1667 x = (1-t)*cp.x + t*c[2] 1668 y = (1-t)*cp.y + t*c[3] 1669 RELATIVE- WHEN c[4] > 0: ncp.x = cp.x+c[2] npep.x = cp.x+c[0] 1670 _CONIC_CURVE_TO_NV x = ( (1-t)^2*cp.x + ncp.y = cp.y+c[3] npep.y = cp.y+c[1] 1671 2*(1-t)*t*(c[0]+cp.x)*c[4] + 1672 t^2*(c[2]+cp.x) ) / 1673 ( (1-t)^2 + 1674 2*(1-t)*t*c[4] + 1675 t^2*c[2] ) 1676 y = ( 1-t)^2*cp.y + 1677 2*(1-t)*t*c[1]*w + 1678 t^2*c[3] ) / 1679 ( (1-t)^2 + 1680 2*(1-t)*t*c[4] + 1681 t^2*c[2] ), 1682 OTHERWISE: 1683 x = (1-t)*cp.x + t*(c[2]+cp.x) 1684 y = (1-t)*cp.y + t*(c[3]+cp.y) 1685 -------------------------- -------------------------------------- ------------------ ----------------------- 1686 ROUNDED_RECT_NV x = rrect(c[0], c[1], c[2], c[3], ncp.x = C_ll.x npep.x = C_ll.x 1687 c[4], c[4], c[4], c[4], ncp.y = C_ll.y npep.y = C_ll.y 1688 c[4], c[4], c[4], c[4], t).x 1689 y = rrect(c[0], c[1], c[2], c[3], 1690 c[4], c[4], c[4], c[4], 1691 c[4], c[4], c[4], c[4], t).y 1692 RELATIVE_ROUNDED_RECT_NV x = rrect(c[0]+cp.x, c[1]+cp.y, ncp.x = C_ll.x npep.x = C_ll.x 1693 c[2], c[3], ncp.y = C_ll.y npep.y = C_ll.y 1694 c[4], c[4], c[4], c[4], 1695 c[4], c[4], c[4], c[4], t).x 1696 y = rrect(c[0]+cp.x, c[1]+cp.y, 1697 c[2], c[3], 1698 c[4], c[4], c[4], c[4], 1699 c[4], c[4], c[4], c[4], t).y 1700 ROUNDED_RECT2_NV x = rrect(c[0], c[1], c[2], c[3], ncp.x = C_ll.x npep.x = C_ll.x 1701 c[4], c[5], c[4], c[5], ncp.y = C_ll.y npep.y = C_ll.y 1702 c[4], c[5], c[4], c[5], t).x 1703 y = rrect(c[0], c[1], c[2], c[3], 1704 c[4], c[5], c[4], c[5], 1705 c[4], c[5], c[4], c[5], t).y 1706 RELATIVE_ROUNDED_RECT2_NV x = rrect(c[0]+cp.x, c[1]+cp.y, ncp.x = C_ll.x npep.x = C_ll.x 1707 c[2], c[3], ncp.y = C_ll.y npep.y = C_ll.y 1708 c[4], c[5], c[4], c[5], 1709 c[4], c[5], c[4], c[5], t).x 1710 y = rrect(c[0]+cp.x, c[1]+cp.y, 1711 c[2], c[3], 1712 c[4], c[5], c[4], c[5], 1713 c[4], c[5], c[4], c[5], t).y 1714 ROUNDED_RECT4_NV x = rrect(c[0], c[1], c[2], c[3], ncp.x = C_ll.x npep.x = C_ll.x 1715 c[4], c[4], c[5], c[5], ncp.y = C_ll.y npep.y = C_ll.y 1716 c[6], c[6], c[7], c[7], t).x 1717 y = rrect(c[0], c[1], c[2], c[3], 1718 c[4], c[4], c[5], c[5], 1719 c[6], c[6], c[7], c[7], t).y 1720 RELATIVE_ROUNDED_RECT4_NV x = rrect(c[0]+cp.x, c[1]+cp.y, ncp.x = C_ll.x npep.x = C_ll.x 1721 c[2], c[3], ncp.y = C_ll.y npep.y = C_ll.y 1722 c[4], c[4], c[5], c[5], 1723 c[6], c[6], c[7], c[7], t).x 1724 y = rrect(c[0]+cp.x, c[1]+cp.y, 1725 c[2], c[3], 1726 c[4], c[4], c[5], c[5], 1727 c[6], c[6], c[7], c[7], t).y 1728 ROUNDED_RECT8_NV x = rrect(c[0], c[1], c[2], c[3], ncp.x = C_ll.x npep.x = C_ll.x 1729 c[4], c[5], c[6], c[7], ncp.y = C_ll.y npep.y = C_ll.y 1730 c[8], c[9], 1731 c[10], c[11], t).x 1732 y = rrect(c[0], c[1], c[2], c[3], 1733 c[4], c[5], c[6], c[7], 1734 c[8], c[9], 1735 c[10], c[11], t).y 1736 RELATIVE_ROUNDED_RECT8_NV x = rrect(c[0]+cp.x, c[1]+cp.y, ncp.x = C_ll.x npep.x = C_ll.x 1737 c[2], c[3], ncp.y = C_ll.y npep.y = C_ll.y 1738 c[4], c[5], c[6], c[7], 1739 c[8], c[9], 1740 c[10], c[11], t).x 1741 y = rrect(c[0]+cp.x, c[1]+cp.y, 1742 c[2], c[3], 1743 c[4], c[5], c[6], c[7], 1744 c[8], c[9], 1745 c[10], c[11], t).y 1746 -------------------------- -------------------------------------- ------------------ ----------------------- 1747 DUP_FIRST- x = (1-t)^3*cp.x + ncp.x = c[2] npep.x = c[0] 1748 CUBIC_CURVE_TO_NV 3*(1-t)^2*t*cp.x + ncp.y = c[3] npep.y = c[1] 1749 3*(1-t)*t^2*c[0] + 1750 t^3*c[2] 1751 y = (1-t)^3*cp.y + 1752 3*(1-t)^2*t*cp.y + 1753 3*(1-t)*t^2*c[1] + 1754 t^3*c[3] 1755 DUP_LAST_CUBIC_CURVE_TO_NV x = (1-t)^3*cp.x + ncp.x = c[2] npep.x = c[2] 1756 3*(1-t)^2*t*c[0] + ncp.y = c[3] npep.y = c[3] 1757 3*(1-t)*t^2*c[2] + 1758 t^3*c[2] 1759 y = (1-t)^3*cp.y + 1760 3*(1-t)^2*t*c[1] + 1761 3*(1-t)*t^2*c[3] + 1762 t^3*c[3] 1763 -------------------------- -------------------------------------- ------------------ ----------------------- 1764 RECT_NV / (1-4*t)*c[0] + ncp.x = c[0] npep.x = c[0] 1765 | 4*t*(c[0]+c[2]), t<=0.25 ncp.y = c[1] npep.y = c[1] 1766 x = < c[0]+c[2], 0.25<t<=0.5 1767 | (1-4*t-2)*(c[0]+c[2]) + 1768 | (4*t-2)*c[0], 0.5 <t<=0.75 1769 \ c[0], 0.75<t 1770 / c[1], t<=0.25 1771 | (1-4*t-1)*c[1] + 1772 y = < (4*t-1)*(c[1]+c[3]), 0.25<t<=0.5 1773 | c[1]+c[3], 0.5 <t<=0.75 1774 | (1-4*t-3)*(c[1]+c[3]) + 1775 \ (4*t-3)*c[1], 0.75<t 1776 RELATIVE_RECT_NV / (1-4*t)*(c[0]+cp.x) + ncp.x = cp.x+c[0] npep.x = cp.x+c[0] 1777 | 4*t*(c[0]+c[2]+cp.x), t<=0.25 ncp.y = cp.y+c[1] npep.y = cp.y+c[1] 1778 x = < c[0]+c[2]+cp.x, 0.25<t<=0.5 1779 | (1-4*t-2)*(c[0]+c[2]+cp.x) + 1780 | (4*t-2)*(c[0]+cp.x), 0.5<t<=0.75 1781 \ c[0]+cp.x, 0.75<t 1782 / c[1]+cp.y, t<=0.25 1783 | (1-4*t-1)*(c[1]+cp.y) + 1784 y = < (4*t-1)*(c[1]+c[3]+cp.y), 1785 | 0.25<t<=0.5 1786 | c[1]+c[3]+cp.y, 0.5<t<=0.75 1787 | (1-4*t-3)*(c[1]+c[3]+cp.y) + 1788 \ (4*t-3)*(c[1]+cp.y), 0.75<t 1789 -------------------------- -------------------------------------- ------------------ ----------------------- 1790 CIRCULAR_CCW_ARC_TO_NV / (1-2*t)*cp.x + 2*t*A.x, t<=0.5 ncp.x = B.x npep.x = B.x 1791 x = { ncp.y = B.y npep.x = B.y 1792 \ arc_x(c,rv,rh,phi,theta1, 1793 \ dtheta,t*2-1) t>=0.5 1794 / (1-2*t)*cp.y + 2*t*A.y, t<=0.5 1795 y = { 1796 \ arc_y(c,rv,rh,phi,theta1, 1797 \ dtheta,t*2-1), t>=0.5 1798 CIRCULAR_CW_ARC_TO_NV / (1-2*t)*cp.x + 2*t*A.x, t<=0.5 ncp.x = B.x npep.x = B.x 1799 x = { ncp.y = B.y npep.x = B.y 1800 \ arc_x(c,rv,rh,phi,theta1, 1801 \ dtheta,t*2-1) t>=0.5 1802 / (1-2*t)*cp.y + 2*t*A.y, t<=0.5 1803 y = { 1804 \ arc_y(c,rv,rh,phi,theta1, 1805 \ dtheta,t*2-1), t>=0.5 1806 CIRCULAR_TANGENT_ARC_TO_NV / (1-2*t)*cp.x + 2*t*C.x, t<=0.5 ncp.x = D.x npep.x = D.x 1807 x = { ncp.y = D.y npep.x = D.y 1808 \ arc_x(c,rv,rh,phi,theta1, 1809 \ dtheta,t*2-1), t>=0.5 1810 / (1-2*t)*cp.y + 2*t*C.y, t<=0.5 1811 y = { 1812 \ arc_y(c,rv,rh,phi,theta1, 1813 \ dtheta,t*2-1), t>=0.5 1814 -------------------------- -------------------------------------- ------------------ ----------------------- 1815 ARC_TO_NV x = arc_x(c,rv,rh,phi, ncp.x = c[5] npep.x = c[5] 1816 theta1,dtheta,t) ncp.y = c[6] npep.y = c[6] 1817 y = arc_y(c,rv,rh,phi, 1818 theta1,dtheta,t) 1819 RELATIVE_ARC_TO_NV x = arc_x(c,rv,rh,phi, ncp.x = cp.x+c[5] npep.x = cp.x+c[5] 1820 theta1,dtheta,t) ncp.y = cp.y+c[6] npep.y = cp.y+c[6] 1821 y = arc_y(c,rv,rh,phi, 1822 theta1,dtheta,t) 1823 -------------------------- -------------------------------------- ------------------ ----------------------- 1824 1825 In the equations in Table 5.pathEquations, c[i] is the /i/th (base 1826 zero) coordinate of the coordinate sequence for the command; /cp/ 1827 is the 2D (x,y) current position from the prior command (for the 1828 first command of a path object, /cp/ is (0,0)); /sp/ is the 2D (x,y) 1829 start position for the current contour (for the first command of a 1830 path object, /sp/ is (0,0)); /pep/ is the 2D (x,y) prior end position 1831 from the prior end position (for the first command of a path object, 1832 /pep/ is (0,0)); and /ncp/ is the 2D (x,y) "new" current position 1833 that will become the current position for the subsequent command; 1834 /npep/ is the 2D (x,y) "new" prior end position for the subsequent 1835 command. The values /c/, /theta1/, /dtheta/ are explained in the 1836 discussion of partial elliptical arc commands below. The values 1837 of /rv/, /rh/, /phi/ come from Table 5.arcParameterSpecialization. 1838 The values of /A/, /B/, /C/, and /D/ are discussed in the context 1839 of Table 5.arcParameterSpecialization. /C_ll/ is the lower-left 1840 end-point defined for Equation 5.roundedRectangleContour. 1841 1842 If a value specified for a coordinate (however the coordinate is 1843 specified) or a value computed from these coordinates (as specified 1844 in the discussion that follows) exceeds the implementation's maximum 1845 representable value for a single-precision floating-point number, 1846 the rendering behavior (discussed in section 5.X.2) of the specified 1847 path and the value of said coordinate if queried (section 6.X.2) 1848 is undefined. This is relevant because coordinates can be specified 1849 explicitly but also relatively (by RELATIVE_* path commands) or 1850 encoded in a string of otherwise arbitrary precision and range or 1851 computed by weighting. 1852 1853 ROUNDED RECTANGLE COMMAND DETAILS 1854 1855 In all the rounded-rectangle path commands, the parametric segment 1856 path equations in Table 5.pathEquations are expressed in terms of 1857 the function /rrect/ that returns an (x,y) position on the rounded 1858 rectangle when evaluated over the parametric range t=0..1. /rrect/ 1859 is a spline of alternating rational quadratic Bezier segments and 1860 linear segments that forms a closed contour. 1861 1862 In addition to its parametric variable /t/, /rrect/ has 12 1863 parameters to which geometric properties can be ascribed when these 1864 values are positive. (No restriction precludes these parameters 1865 to be non-positive; negative and zero values are allowed and 1866 supported.) (x,y) is the 2D location of the lower-left corner of the 1867 rectangle tightly bounding the rounded rectangle contour; /w/ and /h/ 1868 are the respective width and height of the same bounding rectangle. 1869 /r_llx/, /r_lrx/, /r_urx/, and /r_ulx/ are the elliptical x-axis 1870 radii corresponding to the lower-left, lower-right, upper-right, 1871 and upper-left corners of the rounded rectangle; likewise /r_lly/, 1872 /r_lry/, /r_ury/, and /r_uly/ are the elliptical y-axis for the 1873 same corners. 1874 1875 Equation 5.roundedRectangleContour 1876 1877 rrect(x,y, / (1-t_0)*C_ll + t_0*A_lr, t=0/8..1/8 1878 w,h, | 1879 r_llx,r_lly, | (1-t_1)^2*A_lr + (1-t_1)*t_1*B_lr*sqrt(2) + t_1^2*C_lr)/ 1880 r_lrx,r_lry, = < ((1-t_1)^2 + (1-t_1)*t_1*sqrt(2) + t_1^2), t=1/8..2/8 1881 r_urx,r_ury, | 1882 r_ulx,r_uly, | (1-t_2)*C_lr + t_2*A_ur, t=2/8..3/8 1883 t) | 1884 | (1-t_3)^2*A_ur + (1-t_3)*t_3*B_ur*sqrt(2) + t_3^2*C_ur)/ 1885 | ((1-t_3)^2 + (1-t_3)*t_3*sqrt(2) + t_3^2), t=3/8..4/8 1886 | 1887 | (1-t_4)*C_ur + t_4*A_ul, t=4/8..5/8 1888 | 1889 | (1-t_5)^2*A_ul + (1-t_5)*t_5*B_ul*sqrt(2) + t_5^2*C_ul)/ 1890 | ((1-t_5)^2 + (1-t_5)*t_5*sqrt(2) + t_5^2), t=5/8..6/8 1891 | 1892 | (1-t_6)*C_ul + t_6*A_ll, t=6/8..7/8 1893 | 1894 | (1-t_7)^2*A_ll + (1-t_7)*t_7*B_ll*sqrt(2) + t_7^2*C_ll)/ 1895 \ ((1-t_7)^2 + (1-t_7)*t_7*sqrt(2) + t_7^2), t=7/8..1 1896 1897 where 1898 1899 t_i = 8*t - i 1900 1901 A_ll = (x,y-r_lly), h<0 1902 (x,y+r_lly), otherwise 1903 B_ll = (x,y) 1904 C_ll = (x-r_llx,y), w<0 1905 (x+r_llx,y), otherwise 1906 1907 A_lr = (x+w+r_lrx,y), w<0 1908 (x+w-r_lrx,y), otherwise 1909 B_lr = (x+w,y) 1910 C_lr = (x+w,y-r_lry), h<0 1911 (x+w,y+r_lry), otherwise 1912 1913 A_ur = (x+w,y+h-r_ury*sign(h)), h<0 1914 (x+w,y+h-r_ury*sign(h)), otherwise 1915 B_ur = (x+w,y+h) 1916 C_ur = (x+w+r_urx,y+h), w<0 1917 (x+w-r_urx,y+h), otherwise 1918 1919 A_ul = (x-r_ulx,y+h), w<0 1920 (x+r_ulx,y+h), otherwise 1921 B_ul = (x,y+h) 1922 C_ul = (x,y+h+r_uly), h<0 1923 (x,y+h-r_uly), otherwise 1924 1925 Consider /t_i/ to be a subparmetric range within /t/ where /t_i/ 1926 ranges over 0..1 for each spline segment of /rrect/. The 2D control 1927 points /A_ll/ through /C_ul/ are shown in Figure 5.roundedRectangle, 1928 where /ll/, /lr/, /ur/, and /ul/ correspond to lower-left, 1929 lower-right, upper-right, and upper-left respectively. 1930 1931 Figure 5.roundedRectangle: Geometric interpretation of Equation 1932 5.roundedRectangleContour parameters. 1933 1934 _ r_ulx _ r_urx 1935 / \ / \ 1936 / \C_ul A_ur / \ 1937 B_ul .-----.-----------------------.-----. B_ur \ 1938 /| |\ | 1939 r_uly < | | > r_ury | 1940 \| |/ | 1941 A_ul . . C_ur | 1942 | | \ 1943 | | > h 1944 | | / 1945 | | | 1946 A_ll . . C_rl | 1947 /| |\ | 1948 r_lly < | | > r_rly | 1949 \| |/ | 1950 B_ll .-----.-----------------------.-----. B_rl / 1951 & (x,y) \ /C_ll A_rl \ / 1952 \_/ \_/ 1953 r_llx r_rlx 1954 \______________ __________________/ 1955 \/ 1956 w 1957 1958 Note that the ROUNDED_RECT*_NV commands degenerate to the RECT_NV 1959 command when all the radii are zero. 1960 1961 PARTIAL ELLIPTICAL ARC COMMAND DETAILS 1962 1963 In all the arc-based path commands, the parametric segment path 1964 equations in Table 5.pathEquations are expressed in terms of the 1965 functions /arc_x/ and /arc_y/. 1966 1967 Equation 5.generalParametricArc 1968 1969 arc_x(c,rv,rh,phi,theta1,dtheta,t) = cos(phi)*rh*cos(theta1+t*dtheta) - 1970 sin(phi)*rv*sin(theta1+t*dtheta) + c.x 1971 arc_y(c,rv,rh,phi,theta1,dtheta,t) = sin(phi)*rh*cos(theta1+t*dtheta) + 1972 cos(phi)*rv*sin(theta1+t*dtheta) + c.y 1973 1974 This general form of a parametric partial elliptical arc computes 1975 (x,y) 2D positions on the arc as /t/ ranges from 0.0 to 1.0 inclusive. 1976 1977 In addition to the varying /t/ parameter, these functions depend on 1978 a 2D (x,y) center position /c/, a horizontal ellipse radius /rh/, 1979 a vertical ellipse radius /rv/, a counterclockwise angle (in radians) 1980 of an ellipse with respect to the x-axis /phi/, /theta1/ is the angle 1981 (in radians) of the initial point on the partial arc, and /dtheta/ 1982 is the difference between the angle (in radians) of the terminal 1983 point on the partial arc and /theta1/. The larger of /rh/ and /rv/ 1984 is the complete ellipse's major axis while the smaller of the two 1985 is the complete ellipse's minor axis. 1986 1987 How these additional dependent parameters for /arc_x/ and /arc_y/ 1988 are determined depends on the specific arc path command as 1989 detailed in Table 5.arcParameterSpecialization. Before explaining 1990 how specific arc commands determine these dependent parameters, 1991 the following discussion develops a general scheme for converting 1992 general end-point representations of arcs to the partial elliptical 1993 arc segment representation of Equation 5.generalParametricArc. 1994 All the arc commands supported are specializations of this general 1995 end-point representation. The general scheme is developed, specific 1996 arc commands are specified as special cases of the general end-point 1997 representation scheme for arcs. 1998 1999 In general, consider seven scalar values (/x1/, /y1/, /x2/, 2000 /y2/, /phi/, /fA/, and /fS/) fully parameterizing a given partial 2001 elliptical arc: 2002 2003 * a 2D position (x1,y1) at the start of a partial elliptical 2004 arc segment 2005 2006 * a 2D position (x2,y2) at the end of a partial elliptical 2007 arc segment 2008 2009 * /phi/ is the angle (in radians) from the x-axis of the path 2010 space coordinate system to the x-axis of the axis-aligned ellipse 2011 2012 * /fA/ is a boolean (the "large arc" flag) that is true when 2013 the arc spans greater than 180 degrees; and otherwise false 2014 if the arc sweeps 180 degrees or less 2015 2016 * /fS/ is a boolean (the "sweep" flag) that is true when the 2017 arc sweeps in a counterclockwise direction in path space 2018 (so sweeps with increasing angles); and otherwise false 2019 when the arc sweeps in a clockwise direction (so sweeps with 2020 decreasing angles) 2021 2022 Given this parameterization, the procedure below computes the /c/, 2023 /rv/, /rh/, /phi/, /theta1/, and /dtheta/ parameters to represent 2024 this same arc in the general parametric form of Equation 2025 5.generalParametricArc. 2026 2027 Step 1: 2028 2029 x1p = cos(phi)*(x1-x2)/2 + sin(phi)*(y1-y2)/2 2030 y1p = -sin(phi)*(x1-x2)/2 + cos(phi)*(y1-y2)/2 2031 2032 If /rh/, /rv/, and /phi/ are such that there is no solution 2033 (basically, the ellipse is not big enough to reach from (x1,y1) 2034 to (x2,y2), then the ellipse is scaled up uniformly until there 2035 is exactly one solution (until the ellipse is just big enough) 2036 in this manner: 2037 2038 lambda = (x1p/rh)^2 + (y1p/rv)^2 2039 2040 / rh, lambda<=1 2041 rp.x = { 2042 \ rh*sqrt(lambda), lambda>1 2043 2044 / rv, lambda<=1 2045 rp.y = { 2046 \ rv*sqrt(lambda), lambda>1 2047 2048 Step 2: 2049 2050 cp.x = fsgn*sqrt((rp.x^2*rp.y^2 - rp.x^2*y1p^2 - rp.y^2*x1p^2) / 2051 (rp.x^2*y1p^2 + rp.y^2*x1p^2) 2052 ) * rp.x*y1p/rp.y 2053 cp.y = fsgn*sqrt((rp.x^2*rp.y^2 - rp.x^2*y1p^2 - rp.y^2*x1p^2) / 2054 (rp.x^2*y1p^2 + rp.y^2*x1p^2) 2055 ) * -rp.y*x1p/rp.x 2056 2057 where 2058 2059 / +1, fA != fS 2060 fsgn = { 2061 \ -1, fA = fS 2062 2063 Step 3: 2064 2065 c.x = cos(phi)*cp.x - sin(phi)*cyp + (x1+x2)/2 2066 c.y = sin(phi)*cp.x + cos(phi)*cyp + (y1+y2)/2 2067 2068 In general, the angle between two vectors (u.x, u.y) and (v.x, v.y) 2069 can be computed as 2070 2071 / arcos(dot(u,v)/sqrt(dot(u,u))*sqrt(dot(v,v))), u.x*v.y-u.y*v.x>=0 2072 angle(u,v) = { 2073 \ -arcos(dot(u,v)/sqrt(dot(u,u))*sqrt(dot(v,v))), u.x*v.y-u.y*v.x<0 2074 2075 Step 4: 2076 2077 theta1 = angle([1,0], 2078 [(x1p-cp.x)/r.x,(y1p-cp.y)/r.y]) 2079 dangle = angle([(x1p-cp.x)/r.x,(y1p-cp.y)/r.y], 2080 [(-x1p-cp.x)/r.x,(-y1p-cp.y)/r.y]) 2081 2082 / dangle - 2*Pi, fS=false AND d>0 2083 / 2084 / dangle, fS=false AND d<=0 2085 dtheta = { 2086 \ dangle, fS=true AND d>=0 2087 \ 2088 \ dangle + 2*Pi, fS=true AND d<0 2089 2090 The arc path commands allow arbitrary numeric values so when these 2091 values result in invalid or out-of-range parameters when the above 2092 steps are applied, the following further steps are taken to ensure 2093 well-defined behavior. 2094 2095 If (x1,y1) and (x2,y2) are identical, then this is equivalent to 2096 omitting the arc segment entirely. 2097 2098 If either of /rh/ or /rv/ is zero, the arc is treated as a straight 2099 line segment from (x1,y1) to (x2,y2). 2100 2101 Table 5.arcParameterSpecialization now maps the coordinate values 2102 for each arc path command to the parameters of the arc end-point 2103 parameterization above from which the arc's parametric representation 2104 can be obtained. 2105 2106 Table 5.arcParameterSpecialization: Arc Path Command 2107 2108 Token (x1,y1) rh rv phi (x2,y2) fA fS 2109 ---------------------------- ---------- --------- --------- ----------- ------------------- --------------- ------- 2110 SMALL_CCW_ARC_TO_NV cp.x,cp.y abs(c[0]) abs(c[1]) c[2]*Pi/180 c[3],c[4] false true 2111 RELATIVE_SMALL_CCW_ARC_TO_NV cp.x,cp.y abs(c[0]) abs(c[1]) c[2]*Pi/180 cp.x+c[3],cp.y+c[4] false true 2112 SMALL_CW_ARC_TO_NV cp.x,cp.y abs(c[0]) abs(c[1]) c[2]*Pi/180 c[3],c[4] false false 2113 RELATIVE_SMALL_CW_ARC_TO_NV cp.x,cp.y abs(c[0]) abs(c[1]) c[2]*Pi/180 cp.x+c[3],cp.y+c[4] false false 2114 LARGE_CCW_ARC_TO_NV cp.x,cp.y abs(c[0]) abs(c[1]) c[2]*Pi/180 c[3],c[4] true true 2115 RELATIVE_LARGE_CCW_ARC_TO_NV cp.x,cp.y abs(c[0]) abs(c[1]) c[2]*Pi/180 cp.x+c[3],cp.y+c[4] true true 2116 LARGE_CW_ARC_TO_NV cp.x,cp.y abs(c[0]) abs(c[1]) c[2]*Pi/180 c[3],c[4] true false 2117 RELATIVE_SMALL_CW_ARC_TO_NV cp.x,cp.y abs(c[0]) abs(c[1]) c[2]*Pi/180 cp.x+c[3],cp.y+c[4] true false 2118 CIRCULAR_CCW_ARC_TO_NV A.x,A.y abs(c[2]) abs(c[2]) 0 B.x,B.y (c[4]-c[3])>180 true 2119 CIRCULAR_CW_ARC_TO_NV A.x,A.y abs(c[2]) abs(c[2]) 0 B.x,B.y (c[4]-c[3])>180 false 2120 CIRCULAR_TANGENT_ARC_TO_NV C.x,C.y abs(c[4]) abs(c[4]) 0 D.x,D.y false num>=0 2121 ARC_TO_NV cp.x,cp.y abs(c[0]) abs(c[1]) c[2]*Pi/180 c[5],c[6] c[3]!=0 c[4]!=0 2122 RELATIVE_ARC_TO_NV cp.x,cp.y abs(c[0]) abs(c[1]) c[2]*Pi/180 cp.x+c[5],cp.y+c[6] c[3]!=0 c[4]!=0 2123 2124 where, for CIRCULAR_CCW_ARC_TO_NV and CIRCULAR_CW_ARC_TO_NV, 2125 2126 A = (c[0]+c[2]*cos(c[3]*Pi/180), 2127 c[1]+c[2]*sin(c[3]*Pi/180)) 2128 2129 B = (c[0]+c[2]*cos(c[4]*Pi/180), 2130 c[1]+c[2]*sin(c[4]*Pi/180)) 2131 2132 and C, D, and num, for CIRCULAR_TANGENT_ARC_TO_NV, are computed 2133 through the following steps: 2134 2135 Step 1: Compute two tangent vectors: 2136 2137 d0.x = cp.x - c[0] 2138 d0.y = cp.y - c[1] 2139 d2.x = c[2] - c[0] 2140 d2.y = c[3] - c[1] 2141 2142 Step 2: Compute scaling factors for tangent vectors: 2143 2144 num = d0.y*d2.x - d2.y*d0.x 2145 denom = sqrt(dot(d0,d0)*dot(d2,d2)) - dot(d0,d2) 2146 2147 dist = abs(c[4] * num/denom) 2148 2149 l0 = dist/sqrt(dot(d0,d0)) * c[4]/abs(c[4]) 2150 l2 = dist/sqrt(dot(d2,d2)) * c[4]/abs(c[4]) 2151 2152 Step 3: Add scaled directions to the tangent vector intersection 2153 point: 2154 2155 / (c[0],c[1]) + d0 * l0, denom!=0 AND c[4]!=0 2156 C = { 2157 \ (c[0],c[1]), denom==0 OR c[4]==0 2158 2159 / (c[0],c[1]) + d2 * l2, denom!=0 AND c[4]!=0 2160 D = { 2161 \ (c[0],c[1]), denom==0 OR c[4]==0 2162 2163 PATH OBJECT SPECIFICATION 2164 2165 Path objects can be specified in one of four ways: 2166 2167 1) explicitly from an array of commands and corresponding 2168 coordinates, 2169 2170 2) from a string conforming to one of two supported grammars to 2171 specify a string, 2172 2173 3) from a glyph within a font face from a system font or font file, 2174 or 2175 2176 4) by linearly combining one or more existing path objects with 2177 mutually consistent command sequences to form a new path. 2178 2179 In any situation where a path object is specified or re-specified, 2180 the command's parameters are re-initialized as discussed in section 2181 5.X.1.5 unless otherwise specified. However modification of path 2182 commands and coordinates (section 5.X.1.4) does not modify path 2183 parameters. 2184 2185 5.X.1.1 Explicit Path Specification 2186 2187 The command 2188 2189 void PathCommandsNV(uint path, 2190 sizei numCommands, const ubyte *commands, 2191 sizei numCoords, enum coordType, 2192 const void *coords); 2193 2194 specifies a new path object named /path/ where /numCommands/ 2195 indicates the number of path commands, read from the array 2196 /commands/, with which to initialize that path's command sequence. 2197 These path commands reference coordinates read sequentially from the 2198 /coords/ array. The type of the coordinates read from the /coords/ 2199 array is determined by the /coordType/ parameter which must be 2200 one of BYTE, UNSIGNED_BYTE, SHORT, UNSIGNED_SHORT, or FLOAT, 2201 otherwise the INVALID_ENUM error is generated. 2202 2203 The /numCommands/ elements of the /commands/ array must be tokens 2204 or character in Table 5.pathCommands. The command sequence matches 2205 the element order of the /commands/ array. Each command references 2206 a number of coordinates specified by "Coordinate count" column of 2207 Table 5.pathCommands, starting with the first (zero) element of 2208 the /coords/ array and advancing by the coordinate count for each 2209 command. If any of these /numCommands/ command values are not 2210 listed in the "Token" or "Character aliases" columns of Table 2211 5.pathCommands, the INVALID_ENUM error is generated. 2212 2213 The INVALID_OPERATION error is generated if /numCoords/ does not 2214 equal the number of coordinates referenced by the command sequence 2215 specified by /numCommands/ and /commands/ (so /numCoords/ provides a 2216 sanity check that the /coords/ array is being interpreted properly). 2217 The error INVALID_VALUE is generated if either /numCommands/ or 2218 /numCoords/ is negative. 2219 2220 If the PathCommandsNV command results in an error, the path object 2221 named /path/ is not changed; if there is no error, the prior contents 2222 of /path/, if /path/ was an existent path object, are lost and the 2223 path object name /path/ becomes used. 2224 2225 5.X.1.2 String Path Specification 2226 2227 The command 2228 2229 void PathStringNV(uint path, enum format, 2230 sizei length, const void *pathString); 2231 2232 specifies a new path object named /path/ where /format/ must be 2233 either PATH_FORMAT_SVG_NV or PATH_FORMAT_PS_NV, in which case the 2234 /length/ and /pathString/ are interpreted according to grammars 2235 specified in sections 5.X.1.2.1 and 5.X.1.2.2 respectively. 2236 The INVALID_VALUE error is generated if /length/ is negative. 2237 2238 If the PathStringNV command results in an error, the path object 2239 named /path/ is not changed; if there is no error, the prior contents 2240 of /path/, if /path/ was an existent path object, are lost and the 2241 path object name /path/ becomes used. 2242 2243 5.X.1.2.1 Scalable Vector Graphics Path Grammar 2244 2245 If the /format/ parameter of PathStringNV is PATH_FORMAT_SVG_NV, 2246 the /pathString/ parameter is interpreted as a string of ubyte ASCII 2247 characters with /length/ elements. 2248 2249 This string must satisfy the "svg-path" production in the path 2250 grammar below. This grammar is taken directly from the Scalable 2251 Vector Graphics (SVG) 1.1 (April 30, 2009) specification. 2252 2253 The following notation is used in the Backus-Naur Form (BNF) 2254 description of the grammar for an SVG path string: 2255 2256 * *: 0 or more 2257 * +: 1 or more 2258 * ?: 0 or 1 2259 * (): grouping 2260 * ()^n: grouping with n repetitions where n is explained subsequently 2261 * |: separates alternatives 2262 * double quotes surround literals 2263 * #x: prefixes an ASCII character value followed by hexadecimal 2264 digits 2265 * ..: means any of an inclusive range of ASCII characters, so 2266 '0'..'9' means any digit character 2267 2268 The following is the grammar for SVG paths. 2269 2270 svg-path: 2271 wsp* moveto-drawto-command-groups? wsp* 2272 moveto-drawto-command-groups: 2273 moveto-drawto-command-group 2274 | moveto-drawto-command-group wsp* moveto-drawto-command-groups 2275 moveto-drawto-command-group: 2276 moveto wsp* drawto-commands? 2277 drawto-commands: 2278 drawto-command 2279 | drawto-command wsp* drawto-commands 2280 drawto-command: 2281 closepath 2282 | lineto 2283 | horizontal-lineto 2284 | vertical-lineto 2285 | curveto 2286 | smooth-curveto 2287 | quadratic-bezier-curveto 2288 | smooth-quadratic-bezier-curveto 2289 | elliptical-arc 2290 moveto: 2291 ( "M" | "m" ) wsp* moveto-argument-sequence 2292 moveto-argument-sequence: 2293 coordinate-pair 2294 | coordinate-pair comma-wsp? lineto-argument-sequence 2295 closepath: 2296 ("Z" | "z") 2297 lineto: 2298 ( "L" | "l" ) wsp* lineto-argument-sequence 2299 lineto-argument-sequence: 2300 coordinate-pair 2301 | coordinate-pair comma-wsp? lineto-argument-sequence 2302 horizontal-lineto: 2303 ( "H" | "h" ) wsp* horizontal-lineto-argument-sequence 2304 horizontal-lineto-argument-sequence: 2305 coordinate 2306 | coordinate comma-wsp? horizontal-lineto-argument-sequence 2307 vertical-lineto: 2308 ( "V" | "v" ) wsp* vertical-lineto-argument-sequence 2309 vertical-lineto-argument-sequence: 2310 coordinate 2311 | coordinate comma-wsp? vertical-lineto-argument-sequence 2312 curveto: 2313 ( "C" | "c" ) wsp* curveto-argument-sequence 2314 curveto-argument-sequence: 2315 curveto-argument 2316 | curveto-argument comma-wsp? curveto-argument-sequence 2317 curveto-argument: 2318 coordinate-pair comma-wsp? coordinate-pair comma-wsp? coordinate-pair 2319 smooth-curveto: 2320 ( "S" | "s" ) wsp* smooth-curveto-argument-sequence 2321 smooth-curveto-argument-sequence: 2322 smooth-curveto-argument 2323 | smooth-curveto-argument comma-wsp? smooth-curveto-argument-sequence 2324 smooth-curveto-argument: 2325 coordinate-pair comma-wsp? coordinate-pair 2326 quadratic-bezier-curveto: 2327 ( "Q" | "q" ) wsp* quadratic-bezier-curveto-argument-sequence 2328 quadratic-bezier-curveto-argument-sequence: 2329 quadratic-bezier-curveto-argument 2330 | quadratic-bezier-curveto-argument comma-wsp? 2331 quadratic-bezier-curveto-argument-sequence 2332 quadratic-bezier-curveto-argument: 2333 coordinate-pair comma-wsp? coordinate-pair 2334 smooth-quadratic-bezier-curveto: 2335 ( "T" | "t" ) wsp* smooth-quadratic-bezier-curveto-argument-sequence 2336 smooth-quadratic-bezier-curveto-argument-sequence: 2337 coordinate-pair 2338 | coordinate-pair comma-wsp? smooth-quadratic-bezier-curveto-argument-sequence 2339 elliptical-arc: 2340 ( "A" | "a" ) wsp* elliptical-arc-argument-sequence 2341 elliptical-arc-argument-sequence: 2342 elliptical-arc-argument 2343 | elliptical-arc-argument comma-wsp? elliptical-arc-argument-sequence 2344 elliptical-arc-argument: 2345 nonnegative-number comma-wsp? nonnegative-number comma-wsp? 2346 number comma-wsp flag comma-wsp flag comma-wsp coordinate-pair 2347 coordinate-pair: 2348 coordinate comma-wsp? coordinate 2349 coordinate: 2350 number 2351 nonnegative-number: 2352 integer-constant 2353 | floating-point-constant 2354 number: 2355 sign? integer-constant 2356 | sign? floating-point-constant 2357 flag: 2358 "0" | "1" 2359 comma-wsp: 2360 (wsp+ comma? wsp*) | (comma wsp*) 2361 comma: 2362 "," 2363 integer-constant: 2364 digit-sequence 2365 floating-point-constant: 2366 fractional-constant exponent? 2367 | digit-sequence exponent 2368 fractional-constant: 2369 digit-sequence? "." digit-sequence 2370 | digit-sequence "." 2371 exponent: 2372 ( "e" | "E" ) sign? digit-sequence 2373 sign: 2374 "+" | "-" 2375 digit-sequence: 2376 digit 2377 | digit digit-sequence 2378 digit: 2379 "0".."9" 2380 wsp: 2381 (#x20 | #x9 | #xD | #xA) 2382 2383 The processing of the BNF must consume as much of a given BNF 2384 production as possible, stopping at the point when a character 2385 is encountered which no longer satisfies the production. Thus, 2386 in the string "M 100-200", the first coordinate for the "moveto" 2387 consumes the characters "100" and stops upon encountering the minus 2388 sign because the minus sign cannot follow a digit in the production 2389 of a "coordinate". The result is that the first coordinate will be 2390 "100" and the second coordinate will be "-200". 2391 2392 Similarly, for the string "M 0.6.5", the first coordinate of the 2393 "moveto" consumes the characters "0.6" and stops upon encountering 2394 the second decimal point because the production of a "coordinate" 2395 only allows one decimal point. The result is that the first coordinate 2396 will be "0.6" and the second coordinate will be ".5". 2397 2398 The grammar allows the string to be empty (zero length). This is 2399 not an error, instead specifies a path with no commands. 2400 2401 Table 5.svgCommands maps productions in the grammar above to the 2402 path commands in Table 5.pathCommands; each such path command, with 2403 its corresponding coordinates, is added to the path command sequence 2404 of the path object. Each production listed in Table 5.svgCommands 2405 consumes a number of coordinates consistent with the path command 2406 token's coordinate count listed in Table 5.pathCommands. The 2407 "coordinate" and "nonnegative-number" productions convert to a numeric 2408 coordinate value in the obvious way. The "flag" production converts 2409 "0" and "1" to numeric coordinate values zero and one respectively. 2410 2411 Table 5.svgCommands: SVG Grammar Commands to Path Command Tokens 2412 2413 Grammar's prior 2414 Production command character Path command token 2415 ------------------------------------------------- ----------------- ------------------------------------- 2416 moveto-argument-sequence "M" MOVE_TO_NV 2417 "m" RELATIVE_MOVE_TO_NV 2418 closepath "Z" or "z" CLOSE_PATH_NV 2419 lineto-argument-sequence "L" LINE_TO_NV 2420 "l" RELATIVE_LINE_TO_NV 2421 horizontal-lineto-argument-sequence "H" HORIZONTAL_LINE_TO_NV 2422 "h" RELATIVE_HORIZONTAL_LINE_TO_NV 2423 vertical-lineto-argument-sequence "V" VERTICAL_LINE_TO_NV 2424 "v" RELATIVE_VERTICAL_LINE_TO_NV 2425 quadratic-bezier-curveto-argument "Q" QUADRATIC_CURVE_TO_NV 2426 "q" RELATIVE_QUADRATIC_CURVE_TO_NV 2427 smooth-quadratic-bezier-curveto-argument-sequence "T" SMOOTH_QUADRATIC_CURVE_TO_NV 2428 "t" RELATIVE_SMOOTH_QUADRATIC_CURVE_TO_NV 2429 curveto-argument "C" CUBIC_CURVE_TO_NV 2430 "c" RELATIVE_CUBIC_CURVE_TO_NV 2431 smooth-curveto-argument "S" SMOOTH_CUBIC_CURVE_TO_NV 2432 "s" RELATIVE_SMOOTH_CUBIC_CURVE_TO_NV 2433 elliptical-arc-argument "A" ARC_TO_NV 2434 "a" RELATIVE_ARC_TO_NV 2435 2436 If the string fails to satisfy the svg-path production, the path 2437 object named /path/ is not changed. The production may not be 2438 satisfied for one of two reasons: either the grammar cannot be not 2439 satisfied by the string, or the grammar is satisfied but there still 2440 remain a non-zero number of characters in the string. Neither 2441 failure to satisfy the production generates an error; instead the 2442 PATH_ERROR_POSITION_NV state is set to the character offset where the 2443 grammar was first not satisfied or where the grammar was exhausted. 2444 If the string was parsed successfully and the command did not generate 2445 an error, the PATH_ERROR_POSITION_NV state is set to negative one 2446 to indicate success. 2447 2448 5.X.1.2.2 PostScript Path Grammar 2449 2450 If the /format/ parameter of PathStringNV is PATH_FORMAT_PS_NV, 2451 the /pathString/ parameter is interpreted as a string of ubyte ASCII 2452 characters with /length/ elements. 2453 2454 This string must satisfy the "ps-path" production in the path 2455 grammar below. This grammar is parses path specified in PostScript's 2456 subgrammar for user paths specified by "PostScript Language Reference 2457 Manual" 3rd edition. 2458 2459 The following is the grammar (using the same notation as section 2460 5.X.1.2.1) for PS paths with special support for binary encoding modes 2461 (as explained below): 2462 2463 ps-path: 2464 ps-wsp* user-path? ps-wsp* 2465 | ps-wsp* encoded-path ps-wsp* 2466 user-path: 2467 user-path-cmd 2468 | user-path-cmd ps-wsp+ user-path 2469 user-path-cmd: 2470 setbbox 2471 | ps-moveto 2472 | rmoveto 2473 | ps-lineto 2474 | rlineto 2475 | ps-curveto 2476 | rcurveto 2477 | arc 2478 | arcn 2479 | arct 2480 | ps-closepath 2481 | ucache 2482 setbbox: 2483 numeric-value numeric-value numeric-value numeric-value setbbox-cmd 2484 setbbox-cmd: 2485 "setbbox" 2486 | #x92 #x8F 2487 ps-moveto: 2488 numeric-value numeric-value moveto-cmd 2489 moveto-cmd: 2490 "moveto" 2491 | #x92 #x6B 2492 rmoveto: 2493 numeric-value numeric-value rmoveto-cmd 2494 rmoveto-cmd: 2495 "rmoveto" 2496 | #x92 #x86 2497 ps-lineto: 2498 numeric-value numeric-value lineto-cmd 2499 lineto-cmd: 2500 "lineto" 2501 | #x92 #x63 2502 rlineto: 2503 numeric-value numeric-value rlineto-cmd 2504 rlineto-cmd: 2505 "rlineto" 2506 | #x92 #x85 2507 ps-curveto: 2508 numeric-value numeric-value numeric-value numeric-value numeric-value numeric-value curveto-cmd 2509 curveto-cmd: 2510 "curveto" 2511 | #x92 #x2B 2512 rcurveto: 2513 numeric-value numeric-value numeric-value numeric-value numeric-value numeric-value rcurveto-cmd 2514 rcurveto-cmd: 2515 "rcurveto" 2516 | #x92 #x7A 2517 arc: 2518 numeric-value numeric-value numeric-value numeric-value numeric-value arc-cmd 2519 arc-cmd: 2520 "arc" 2521 | #x92 #x05 2522 arcn: 2523 numeric-value numeric-value numeric-value numeric-value numeric-value arcn-cmd 2524 arcn-cmd: 2525 "arcn" 2526 | #x92 #x06 2527 arct: 2528 numeric-value numeric-value numeric-value numeric-value numeric-value arct-cmd 2529 arct-cmd: 2530 "arct" 2531 | #x92 #x07 2532 ps-closepath: 2533 "closepath" 2534 | #x92 #x16 2535 ucache: 2536 "ucache" 2537 | #x92 #xB1 2538 encoded-path: 2539 data-array ps-wsp* operator-string 2540 data-array: 2541 "{" ps-wsp* numeric-value-sequence? "}" 2542 | homogeneous-number-array 2543 | ascii85-homogeneous-number-array 2544 operator-string: 2545 hexadecimal-binary-string 2546 | ascii85-string 2547 | short-binary-string 2548 | be-long-binary-string 2549 | le-long-binary-string 2550 hexadecimal-binary-string: 2551 "<" ps-wsp-chars* hexadecimal-sequence ps-wsp-chars* ">" 2552 hexadecimal-sequence: 2553 hexadecimal-digit 2554 | hexadecimal-digit ps-wsp-chars* hexadecimal-sequence 2555 hexadecimal-digit: 2556 digit 2557 | "a".."f" | 2558 | "A".."F" 2559 short-binary-string: 2560 #x8E one-byte ( one-byte )^n 2561 /where n is the value of the one-byte production decoded 2562 as an unsigned integer, 0 through 255/ 2563 be-long-binary-string: 2564 #x8F two-bytes ( one-byte )^n 2565 /where n is the value of the two-bytes production decoded 2566 as an unsigned integer, 0 through 65535, decoded in 2567 big-endian byte order/ 2568 le-long-binary-string: 2569 #x90 two-bytes ( one-byte )^n 2570 /where n is the value of the two-bytes production decoded 2571 as an unsigned integer, 0 through 65535, decoded in 2572 little-endian byte order/ 2573 numeric-value-sequence: 2574 numeric-value: 2575 | numeric-value numeric-value-sequence 2576 numeric-value: 2577 number ps-wsp+ 2578 | radix-number ps-wsp+ 2579 | be-integer-32bit 2580 | le-integer-32bit 2581 | be-integer-16bit 2582 | le-integer-16bit 2583 | le-integer-8bit 2584 | be-fixed-16bit 2585 | le-fixed-16bit 2586 | be-fixed-32bit 2587 | le-fixed-32bit 2588 | be-float-ieee 2589 | le-float-ieee 2590 | native-float-ieee 2591 be-integer-32bit: 2592 #x84 four-bytes 2593 le-integer-32bit: 2594 #x85 four-bytes 2595 be-integer-16bit: 2596 #x86 two-bytes 2597 le-integer-16bit: 2598 #x87 two-bytes 2599 le-integer-8bit: 2600 #x88 one-byte 2601 be-fixed-32bit: 2602 #x89 #x0..#x1F four-bytes 2603 le-fixed-32bit: 2604 #x89 #x80..#x9F four-bytes 2605 be-fixed-16bit: 2606 #x89 #x20..#x2F two-bytes 2607 le-fixed-16bit: 2608 #x89 #xA0..#xAF two-bytes 2609 be-float-ieee: 2610 #x8A four-bytes 2611 le-float-ieee: 2612 #x8B four-bytes 2613 native-float-ieee: 2614 #x8C four-bytes 2615 radix-number: 2616 base "#" base-number 2617 base: 2618 digit-sequence 2619 base-number: 2620 base-digit-sequence 2621 base-digit-sequence: 2622 base-digit 2623 | base-digit base-digit-sequence 2624 base-digit: 2625 digit 2626 | "a".."z" 2627 | "A".."Z" 2628 homogeneous-number-array: 2629 be-fixed-32bit-array 2630 | be-fixed-16bit-array 2631 | be-float-ieee-array 2632 | native-float-ieee-array 2633 | le-fixed-32bit-array 2634 | le-fixed-16bit-array 2635 | le-float-ieee-array 2636 be-fixed-32bit-array: 2637 #x95 #x0..#x1F two-bytes ( four-bytes )^n 2638 /where n is the value of the two-bytes production decoded 2639 as an unsigned integer, 0 through 65535, decoded in 2640 big-endian byte order/ 2641 be-fixed-16bit-array: 2642 #x95 #x20..#x2F two-bytes ( two-bytes )^n 2643 /where n is the value of the two-bytes production decoded 2644 as an unsigned integer, 0 through 65535, decoded in 2645 big-endian byte order/ 2646 be-float-ieee-array: 2647 #x95 #x30 two-bytes ( four-bytes )^n 2648 /where n is the value of the two-bytes production decoded 2649 as an unsigned integer, 0 through 65535, decoded in 2650 big-endian byte order/ 2651 le-fixed-32bit-array: 2652 #x95 #x80..#x9F two-bytes ( four-bytes )^n 2653 /where n is the value of the two-bytes production decoded 2654 as an unsigned integer, 0 through 65535, decoded in 2655 little-endian byte order/ 2656 le-fixed-16bit-array: 2657 #x95 #xA0..#xAF two-bytes ( two-bytes )^n 2658 /where n is the value of the two-bytes production decoded 2659 as an unsigned integer, 0 through 65535, decoded in 2660 little-endian byte order/ 2661 le-float-ieee-array: 2662 #x95 #xB0 two-bytes ( four-bytes )^n 2663 /where n is the value of the two-bytes production decoded 2664 as an unsigned integer, 0 through 65535, decoded in 2665 little-endian byte order/ 2666 native-float-ieee-array: 2667 #x95 ( #x31 | #xB1 ) two-bytes ( four-bytes )^n 2668 /where n is the value of the two-bytes production decoded 2669 as an unsigned integer, 0 through 65535, decoded in 2670 the native byte order/ 2671 ascii85-string: 2672 "<~" (#x21..#x75 | "z" | psp-wsp )* "~>" 2673 ascii85-homogeneous-number-array: 2674 "<~" (#x21..#x75 | "z" | psp-wsp )* "~>" 2675 one-byte: 2676 #x0..#xFF 2677 two-bytes: 2678 #x0..#xFF #x0..#xFF 2679 four-bytes: 2680 #x0..#xFF #x0..#xFF #x0..#xFF #x0..#xFF 2681 ps-wsp: 2682 ps-wsp-chars 2683 | ps-comment 2684 ps-wsp-chars: 2685 ( #x20 | #x9 | #xA | #xC | #xD | #x0 ) 2686 ps-comment: 2687 "%" ( #0..#9 | #xB..#xC | #xE..#xFF )* ( #xD | #xA ) 2688 2689 This grammar is not technically a pure BNF because it uses binary 2690 encoded data to encode how many characters should be as part of 2691 several productions (short-binary-string, native-float-ieee-array, 2692 etc.). 2693 2694 The processing of the BNF must consume as much of a given BNF 2695 production as possible, stopping at the point when a character 2696 is encountered which no longer satisfies the production. 2697 2698 The grammar allows the string to be empty (zero length). This 2699 is not an error, instead specifies a path with no commands. 2700 2701 Table 5.psCommands maps productions in the grammar above to the path 2702 commands in Table 5.pathCommands; each such path command, with its 2703 corresponding coordinates, is added to the path command sequence 2704 of the path object. Each production listed in Table 5.svgCommands 2705 consumes a quantity of values, matched by the "number" production, 2706 consistent with the path command token's coordinate count listed 2707 in Table 5.pathCommands. The "setbbox" and "ucache" products are 2708 matched but do not result in path commands. 2709 2710 Table 5.psCommands: PS Grammar Commands to Path Command Tokens 2711 2712 Production Path command token 2713 ------------ -------------------------- 2714 arc CIRCULAR_CCW_ARC_TO_NV 2715 arcn CIRCULAR_CW_ARC_TO_NV 2716 arct CIRCULAR_TANGENT_ARC_TO_NV 2717 ps-closepath CLOSE_PATH_NV 2718 ps-curveto CUBIC_CURVE_TO_NV 2719 ps-lineto LINE_TO_NV 2720 ps-moveto MOVE_TO_NV 2721 rcurveto RELATIVE_CUBIC_CURVE_TO_NV 2722 rlineto RELATIVE_LINE_TO_NV 2723 rmoveto RELATIVE_MOVE_TO_NV 2724 setbbox - 2725 ucache - 2726 2727 The "number" production converts to a numeric coordinate value 2728 in the obvious way. The "radix-number" production converts the 2729 base-n integer conversion of its "base-number" production using 2730 the base indicated by the base-10 integer conversion of its "base" 2731 production where the base /n/ must be within the range 2 to 26. 2732 The "base-number" is interpreted in base /n/; the "base-number" 2733 production must contain digits ranging from 0 to /n/-1; digits greater 2734 than 9 are represented by the letters A through Z (or a through z) 2735 for the values 10 through 35 respectively. 2736 2737 The "encoded-path" production provides a compact and precise way 2738 to encode paths with the commands and coordinates decoupled. 2739 2740 The "data-array" subproductions provide a sequence of coordinate 2741 values for the encoded path's commands. The "data-array" 2742 subproduction provides a sequence of numbers that is used by the 2743 following "operator-string" production. 2744 2745 The "operator-string" subproduction is interpreted as a sequence 2746 of encoded path commands, one command per byte generated by 2747 "operator-string"'s "binary-string" production. 2748 2749 Each hexadecimal character in the "hexadecimal-binary-string" 2750 production is a nibble (a 4-bit quantity). Each pair of characters 2751 is two nibbles and they form a byte with the first nibble 2752 representing the most signification bits of the byte. If the 2753 "hexadecimal-binary-string" production contains an odd number of 2754 hexadecimal characters, "0" is assumed to be suffixed to make an 2755 even number of characters (so "A7C" would encode the bytes 167 for 2756 "A7" followed by 192 for "C" which is treated as "C0" for 192). 2757 Table 5.encodedPathOpcodes maps the values contained in the operator 2758 string to path commands. Each command consumes from the coordinate 2759 array supplied by the "data-array" production a number of values 2760 for the command's coordinates equal to the path command token's 2761 coordinate count listed in Table 5.pathCommands. If the value for 2762 an element of the operator string is between 12 and 32 inclusive, 2763 the grammar fails to parse at this point. If the value /n/ of an 2764 element of the operator string is between 32 and 255, then this value 2765 /n/-32 is treated as a repetition count and is treated as if /n/-32 2766 repetitions of the next command are contained in the operator string 2767 instead and the appropriate number of coordinates are consumed from 2768 the associated sequence of coordinate values. 2769 2770 Table 5.encodedPathOpcodes 2771 2772 Opcode Name 2773 ------ --------- 2774 0 setbbox 2775 1 moveto 2776 2 rmoveto 2777 3 lineto 2778 4 rlineto 2779 5 curveto 2780 6 rcurveto 2781 7 arc 2782 8 arcn 2783 9 arct 2784 10 closepath 2785 11 ucache 2786 2787 The ASCII characters in the "ascii85-binary-string" production 2788 consists of a sequence of printable ASCII characters between the "<~" 2789 and "~>" delimiters. This represents arbitrary binary data using 2790 an encoding technique that products a 4:5 expansion as opposed to 2791 the 1:2 expansion for the "hexadecimal-binary-string" production. 2792 This encoding is known as ASCII base-85. 2793 2794 Binary data in the ASCII base-85 encoding are encoded in 4-tuples 2795 (groups of 4) each 4-tuple is used to produce a 5-type of ASCII 2796 characters. If the binary 4-tuple is (b1,b2,b3,b4) and the encoded 2797 5-tuple is (c1,c2,c3,c4,c5), then the relation between them is: 2798 2799 (b1 * 256^3) + (b2 * 256^2) + (b3 * 256^1) + b4 = 2800 (c1 * 256^4) + (c2 * 256^3) + (c3 * 256^2) + (c4 * 256^3) + c5 2801 2802 The four bytes of binary data are interpreted as a base-256 number and 2803 then converted into a base-85 number. The five "digits" of this number, 2804 (c1,c2,c3,c4,c5), are then converted into ASCII characters by adding 33, 2805 which is the ASCII code for '!', to each. ASCII characters in the 2806 range '!' to 'u' are used, where '!' represented the value 0 and 'u' 2807 represents the value 84. As a special case, if all five digits are 2808 zero, they must be represented by either a single 'z' instead of by 2809 '!!!!'. 2810 2811 If the encoded sequence ends with a sequence of characters that is 2812 not an even multiple of 4, the last 1, 2, or 3 characters to produce 2813 a special final partial 5-tuple. Given n (1, 2, or 3) bytes of final 2814 binary data, an encoder must first append 4-n zero bytes to make 2815 a complete 4-tuple. Then, the encoder must encode the 4-tuple in 2816 the usual way, but without applying the 'z' special case. Finally, 2817 the encoder must write the first n+1 bytes of the resulting 5-tuple. 2818 Those bytes are immediately followed by the "~>" terminal marker. 2819 2820 This encoding scheme is reversible and the GL is responsible for 2821 converting the ASCII base-85 string into its corresponding binary 2822 data. White space within an ASCII base-85 encoded string is ignored. 2823 2824 The following conditions constitute encoding violations of the ASCII 2825 base-85 scheme: 2826 2827 * The value represented by a 5-tuple is greater than 2^32-1 2828 2829 * The 'z' value occurs in the middle of a 5-tuple. 2830 2831 * A final partial 5-tuple contains only one character. 2832 2833 Any such encoding violation is a parsing error. 2834 2835 Once the ASCII base-85 string is decoded, this sequence of bytes 2836 is treated as operator elements in the identical manner as the 2837 elements for the "hexadecimal-string" subproduction. This means 2838 invalid opcodes are possible and are treated as parsing errors, and 2839 Valid opcodes and counts consume coordinates from the "data-array" 2840 production to generate path commands with associated coordinates. 2841 2842 The "short-binary-string", "be-long-binary-string", and 2843 "le-long-binary-string" subproductions of "operator-string" are 2844 binary encodings of a sequence of operator string elements. 2845 2846 The "short-binary-string" has a count from 0 to 255 supplied by its 2847 "one-byte" subproduction which indicates how many bytes follow. 2848 These remaining (unsigned) bytes generate the sequence of operator 2849 string elements. 2850 2851 The "be-long-binary-string" has a count from 0 to 65535 supplied by 2852 its "two-byte" subproduction which indicates how many bytes follow. 2853 These remaining (unsigned) bytes generate the sequence of operator 2854 string elements. The "two-byte" subproduction is converted to a 2855 count by multiplying the first unsigned byte by 256 and adding it 2856 to the second unsigned byte. 2857 2858 The "le-long-binary-string" has a count from 0 to 65535 supplied by 2859 its "two-byte" subproduction which indicates how many bytes follow. 2860 These remaining (unsigned) bytes generate the sequence of operator 2861 string elements. The "two-byte" subproduction is converted to a 2862 count by multiplying the second unsigned byte by 256 and adding it 2863 to the first unsigned byte. 2864 2865 The "encoded-path" fails to parse if invalid opcodes are detected 2866 in the operator string or the sequence of numbers for coordinates 2867 is exhausted prematurely. 2868 2869 If the string fails to satisfy the ps-path production, the path 2870 object named /path/ is not changed. The production may not be 2871 satisfied for one of three reasons: the grammar cannot be not 2872 satisfied by the string, the string has invalid sequences (such 2873 as ASCII base-85 violations, exhausting the coordinate data in the 2874 "data-array" production, or invalid opcodes encountered in the 2875 "operator-string" production), or the grammar is satisfied but 2876 there still remain a non-zero number of characters in the string. 2877 None of these failures to satisfy the grammar generates an error; 2878 instead the PATH_ERROR_POSITION_NV state is set to the character 2879 offset where the grammar was first not satisfied, violated 2880 semantically, or where the grammar was exhausted. If the string 2881 was parsed successfully and the command did not generate an error, 2882 the PATH_ERROR_POSITION_NV state is set to negative one to indicate 2883 success. 2884 2885 If a parsing error occurs, the exact value assigned to the 2886 PATH_ERROR_POSITION_NV state variable is implementation-dependent 2887 (because the specifics of error position determination is difficult 2888 to specify) though the determined error location should be nearby 2889 the first error. 2890 2891 5.X.1.3 Font Glyph Path Specification 2892 2893 PATH GLYPHS FROM CHARACTER CODE SEQUENCE 2894 2895 The command 2896 2897 void PathGlyphsNV(uint firstPathName, 2898 enum fontTarget, 2899 const void *fontName, 2900 bitfield fontStyle, 2901 sizei numGlyphs, enum type, 2902 const void *charcodes, 2903 enum handleMissingGlyphs, 2904 uint pathParameterTemplate, 2905 float emScale); 2906 2907 creates, if no error occurs, a range of path objects named from 2908 /firstPathName/ to /firstPathName/+/numGlyphs/-1 based on the 2909 font face indicated by /fontTarget/, /fontName/, and /fontStyle/ 2910 and the sequence of /numGlyphs/ character codes listed in the 2911 /charcodes/ array, as interpreted based by the /type/ parameter. 2912 However each particular name in the range /firstPathName/ to 2913 /firstPathName/+/numGlyphs/-1 is specified as a new path object only 2914 if that name is not already in use as a path object; if a name is 2915 already in use, that named path object is silently left undisturbed. 2916 A path object name is also left undisturbed if the 2917 /handleMissingGlyphs/ parameter is SKIP_MISSING_GLYPH_NV and the 2918 character code for a given glyph corresponds to the font's missing 2919 glyph or the character code is otherwise not available. 2920 2921 The error INVALID_VALUE is generated if /numGlyphs/ or /emScale/ 2922 is negative. 2923 2924 The /fontTarget/ parameter must be one of STANDARD_FONT_NAME_NV, 2925 SYSTEM_FONT_NAME_NV, or FILE_NAME_NV; otherwise the INVALID_ENUM 2926 error is generated. 2927 2928 The /handleMissingGlyphs/ parameter must be one of 2929 SKIP_MISSING_GLYPH_NV or USE_MISSING_GLYPH_NV; otherwise the 2930 INVALID_ENUM error is generated. 2931 2932 If /fontTarget/ is STANDARD_FONT_NAME_NV, then /fontName/ is 2933 interpreted as a nul-terminated 8-bit ASCII character string that 2934 must be one of the following strings: "Serif", "Sans", "Mono", 2935 or "Missing"; otherwise the INVALID_VALUE error is generated. 2936 These "Serif", "Sans", and "Mono" names respectively correspond to 2937 serif, sans-serif, and sans monospaced font faces with the intent 2938 that the font face matches the appearance, metrics, and kerning 2939 of the DejaVu fonts of the same names. All implementations /must/ 2940 support these font names for the STANDARD_FONT_NAME_NV target. 2941 2942 For the STANDARD_FONT_NAME_NV targets with "Serif", "Sans", and 2943 "Mono", all implementations /must/ support the first 256 character 2944 codes defined by Unicode and the ISO/IEC 8859-1 (Latin-1 Western 2945 European) character encoding though implementations are strongly 2946 encouraged to support as much of the Unicode character codes as the 2947 system's underlying font and language support provides. 2948 2949 For the STANDARD_FONT_NAME_NV targets with "Missing", the entire 2950 sequence of path objects must be populated with an identical box 2951 outline with metrics matching this box. 2952 2953 If /fontTarget/ is SYSTEM_FONT_NAME_NV, then /fontName/ is interpreted 2954 as a nul-terminated 8-bit ASCII character string that corresponds to a 2955 system-specific font name. These names are intended to correspond to 2956 the fonts names typically used in web content (e.g. Arial, Georgia, 2957 Times Roman, Helvetica). The mapping of the system font character 2958 string to a system font is assumed to be performed by the GL server. 2959 2960 If /fontTarget/ is FILE_NAME_NV, then /fontName/ is interpreted as 2961 a nul-terminated 8-bit ASCII character string that corresponds to 2962 a system-specific file name in a standard outline font format. 2963 The specific interpretation of this name depends on the system 2964 conventions for identifying files by name. This name can be an 2965 absolute or relative path. The name is expected to include the 2966 font name's extension. The mapping of the font file name to a 2967 font is assumed to be performed by the GL client. What font file 2968 formats are supported is system dependent but implementations are 2969 encouraged to support outline font formats standard to the system 2970 (e.g. TrueType for Windows systems, etc.). 2971 2972 If the /fontTarget/ and /fontName/ combination can not be loaded for 2973 any reason (including the file name could not be opened, the font 2974 name is not available on the system, the font file format is not 2975 supported, the font file format is corrupted, etc.) and there is no 2976 other error generated, the command succeeds silently (so no error 2977 is generated) and the range of named path objects is not modified. 2978 If the named path objects did not exist previously, they continue 2979 to not exist. 2980 2981 The /fontStyle/ parameter is a bitfield allowed to have the 2982 bits BOLD_BIT_NV or ITALIC_BIT_NV set; if other bits are set, the 2983 INVALID_VALUE error is generated. The font style is used as a hint to 2984 indicate the style of the font face. Glyphs are generated with the 2985 font's bold or italic style respectively (or combination thereof) 2986 if the BOLD_BIT_NV or ITALIC_BIT_NV bits are set; otherwise, the 2987 value 0 or NONE indicates the default font face style should be used 2988 to generate the requested glyphs. In situations where the bold or 2989 italic style of the font is encoded in the font name or file name, 2990 the /fontStyle/ parameter is ignored. 2991 2992 The generated glyphs for the path objects named /firstPathName/ 2993 to /firstPathName/+/numGlyphs/-1 are specified by the /numGlyphs/ 2994 character codes listed in the /charcodes/ array where each element of 2995 the array is determined by the /type/ parameter that must be one of 2996 UNSIGNED_BYTE, UNSIGNED_SHORT, UNSIGNED_INT, UTF8_NV, UTF16_NV, 2997 2_BYTES, 3_BYTES, and 4_BYTES with the array accessed in the same 2998 manner as the CallLists command's /type/ and /lists/ parameters 2999 (though not offset by the display list base), but indicating character 3000 codes instead of display list names. 3001 3002 The character codes from the /charcodes/ array are Unicode character 3003 codes if the font in question can map from the Unicode character 3004 set to the font's glyphs. If the font has no meaningful mapping 3005 from Unicode, the font's standard character set is used instead 3006 of Unicode (e.g. a font filled with non-standard symbols). For a 3007 font supporting a character set that can be mapped to the Unicode 3008 character set, a best effort should be made to map the specified 3009 character code from its Unicode character code interpretation to 3010 the closest appropriate glyph in the specified font. 3011 3012 Path objects created from glyphs by PathGlyphsNV have their path 3013 object metric state initialized from the metrics of the glyph from 3014 which they were specified. Section 6.X.3. ("Path Object Glyph 3015 Typographic Queries") explains how these metrics are queried and 3016 what their values mean. While the per-glyph metrics are expected to 3017 vary from glyph to glyph within a font face, the per-font metrics 3018 are expected to be identical for every path object created from a 3019 given font name and font style combination. 3020 3021 Metrics in font space of glyphs are scaled by a value /s/ that is the 3022 ratio of the /emScale/ parameter divided by the font's units per Em; 3023 if the /emScale/ parameter equals zero, treat /emScale/ as if it was 3024 identical to the font's units per Em such that /s/ is exactly 1.0. 3025 Each glyph's outline are also scaled by /s/. The metric values /not/ 3026 scaled by /s/ are GLYPH_HAS_KERNING_BIT_NV, FONT_UNITS_PER_EM_BIT_NV, 3027 FONT_HAS_KERNING_BIT_NV, and FONT_NUM_GLYPH_INDICES_BIT_NV (since 3028 these metric values are not specified in font units). 3029 3030 The FONT_NUM_GLYPH_INDICES_BIT_NV metric value returns -1 for path 3031 objects created with the STANDARD_FONT_NAME_NV (as such fonts are 3032 not accessed by glyph index, only character point); otherwise, the 3033 value is number of glyphs indices for the font, whether or not the 3034 path object is created from a character point or glyph index. 3035 3036 When unknown or missing character codes in a font face are specified 3037 and the /handleMissingGlyph/ parameter is USE_MISSING_GLYPHS_NV, 3038 this situation should be handled in a manner appropriate to the 3039 character code, font face, and implementation. Typically this 3040 involves using the font's missing glyph for the unknown or missing 3041 character code. 3042 3043 If the /pathParameterTemplate/ parameter names an existing path 3044 object, that path object's current parameters listed in Table 3045 5.pathParameters (excepting PATH_FILL_MODE_NV as explained in 3046 the following paragraph) are used to initialize the respective 3047 parameters of path objects specified by this command; otherwise 3048 if the /pathParameterTemplate/ path object name does not exist, 3049 the initial path parameters are used as specified by table 6.Y 3050 (without generating an error). 3051 3052 Path objects created from glyphs by PathGlyphsNV have their 3053 PATH_FILL_MODE_NV parameter, as explained in Section 5.X.1.5 ("Path 3054 Parameter Specification"), initialized according to the fill 3055 conventions of the font outlines within the font (instead of the 3056 COUNT_UP_NV default for paths specified by means other than glyphs). 3057 This may be one of: COUNT_UP_NV if the font's outline winding 3058 convention is counterclockwise and its outline filling assumes the 3059 non-zero winding rule; COUNT_DOWN_NV if the font's outline winding 3060 convention is clockwise and its outline filling assumes the non-zero 3061 winding rule; or INVERT if the font's outline filling assumes the 3062 even-odd winding rule. 3063 3064 PATH GLYPHS FROM CHARACTER CODE RANGE 3065 3066 The command 3067 3068 void PathGlyphRangeNV(uint firstPathName, 3069 enum fontTarget, 3070 const void *fontName, 3071 bitfield fontStyle, 3072 uint firstGlyph, 3073 sizei numGlyphs, 3074 enum handleMissingGlyphs, 3075 uint pathParameterTemplate, 3076 float emScale); 3077 3078 allows a sequence of character codes in a font face to specify a 3079 sequence of path objects and is equivalent to 3080 3081 int *array = malloc(sizeof(int)*numGlyphs); 3082 if (array) { 3083 for (int i=0; i<numGlyphs; i++) { 3084 array[i] = i + firstGlyph; 3085 } 3086 PathGlyphsNV(firstPathName, fontTarget, fontName, fontStyle, 3087 numGlyphs, INT, array, 3088 handleMissingGlyphs, pathParameterTemplate, emScale); 3089 free(array); 3090 } else { 3091 // generate OUT_OF_MEMORY error 3092 } 3093 3094 PATH GLYPHS FROM GLYPH INDEX RANGE 3095 3096 Advanced shaping of text renders glyphs by per-font glyph indices 3097 (rather than Unicode code point). The commands 3098 3099 enum PathGlyphIndexArrayNV(uint firstPathName, 3100 enum fontTarget, 3101 const void *fontName, 3102 bitfield fontStyle, 3103 uint firstGlyphIndex, 3104 sizei numGlyphs, 3105 uint pathParameterTemplate, 3106 float emScale); 3107 3108 enum PathMemoryGlyphIndexArrayNV(uint firstPathName, 3109 enum fontTarget, 3110 sizeiptr fontSize, 3111 const void *fontData, 3112 sizei faceIndex, 3113 uint firstGlyphIndex, 3114 sizei numGlyphs, 3115 uint pathParameterTemplate, 3116 float emScale); 3117 3118 create, if successful and no error occurs, a range of path objects 3119 that correspond to an array of glyphs as ordered by glyph index in 3120 a font face. PathGlyphIndexArrayNV loads the font data from a file 3121 name or system font name while PathMemoryGlyphIndexArrayNV loads 3122 the font data from a standard font format in system memory. 3123 3124 The commands return the value FONT_GLYPHS_AVAILABLE_NV when 3125 successful; otherwise one of the following values is returned 3126 depending on the nature of the failure. The unsuccessful command 3127 returns the value FONT_TARGET_UNAVAILABLE_NV if the implementation 3128 does not support a valid /fontTarget/, FONT_UNAVAILABLE_NV if 3129 the font is not available (e.g. does not exist on the system), or 3130 FONT_UNINTELLIGIBLE_NV if the font is available but cannot be loaded 3131 for some implementation-dependent reason. FONT_UNAVAILABLE_NV will 3132 not be returned by PathMemoryGlyphIndexArrayNV because the font 3133 data is read from system memory. If the command generates an error, 3134 that error's enum value will be returned. For example, an invalid 3135 value for /fontTarget/ will return INVALID_ENUM. While the return 3136 value indicates the error, the error will /also/ be generated in the 3137 conventional way so GetError will return it and error callbacks are 3138 generated normally. 3139 3140 When successful, path names /firstPathName/ through 3141 /firstPathName+numGlyphs-1/ now are specified as path objects 3142 corresponding to the sequence of glyphs in the font indicated 3143 by /fontTarget/, /fontSize/, and /fontData/ for glyph indices 3144 from /firstGlyphIndex/ to /firstGlyphIndex+numGlyphs-1/ where 3145 /firstPathName/ corresponds to the glyph index /firstGlyphIndex/ 3146 and onward sequentially. If a glyph index does not correspond to an 3147 actual glyph index in the font format, the respective path object is 3148 left undisturbed. (It is the application's responsibility to know 3149 the valid range of glyph indices for the font.) When unsuccessful 3150 other than due to an OUT_OF_MEMORY error, no path objects are 3151 specified or otherwise modified. 3152 3153 The path objects are created in the same manner described for 3154 PathGlyphsNV in section 5.X.1.3 (Font Glyph Path Specification) 3155 except the GLYPH_HAS_KERNING_BIT_NV and FONT_HAS_KERNING_BIT_NV 3156 metrics are always false (because GetPathSpacingNV applies to 3157 glyphs specified from Unicode code points). In particular, the 3158 /pathParameterTemplate/ and /emScale/ parameters have the same 3159 interpretation as the PathGlyphsNV command. 3160 3161 For the PathGlyphIndexArrayNV command, the /fontTarget/ parameter 3162 must be either SYSTEM_FONT_NAME_NV or FILE_NAME_NV; otherwise the 3163 INVALID_ENUM error is generated. The /fontStyle/ parameter is 3164 a bitfield allowed to have the bits BOLD_BIT_NV or ITALIC_BIT_NV 3165 set; if other bits are set, the INVALID_VALUE error is generated. 3166 The interpretation of the /fontTarget/, /fontName/, and /fontStyle/ 3167 parameters is identical to the interpretation described in section 3168 5.X.1.3 (Font Glyph Path Specification). 3169 3170 For the PathMemoryGlyphIndexArrayNV command, /fontTarget/ must 3171 be STANDARD_FONT_FORMAT_NV; otherwise INVALID_ENUM is generated 3172 (and returned). STANDARD_FONT_FORMAT_NV implies: /fontSize/ is 3173 the size of the memory storing the font data in memory; /fontData/ 3174 is a pointer to the beginning of the font data; and /faceIndex/ is 3175 the index of the face within the font, typically specified as zero. 3176 3177 The specific standard font formats supported by 3178 STANDARD_FONT_FORMAT_NV are implementation-dependent, but the TrueType 3179 format should be supported. Magic numbers if the font memory data 3180 are expected to be used to identify the specific font format. 3181 3182 The INVALID_VALUE error is generated if any of /fontSize/ or 3183 /faceIndex/ or /emScale/ are negative. 3184 3185 [NOTE: PathGlyphIndexRangeNV is deprecated in favor of 3186 PathGlyphIndexArrayNV and PathMemoryGlyphIndexArrayNV.] 3187 3188 The command 3189 3190 enum PathGlyphIndexRangeNV(enum fontTarget, 3191 const void *fontName, 3192 bitfield fontStyle, 3193 uint pathParameterTemplate, 3194 float emScale, 3195 uint baseAndCount[2]); 3196 3197 creates, if successful and no error occurs, a range of path objects 3198 that correspond to the complete range of glyphs as ordered by glyph 3199 index in a font face. 3200 3201 The command returns the value FONT_GLYPHS_AVAILABLE_NV when 3202 successful; otherwise one of the following values is returned 3203 depending on the nature of the failure. The unsuccessful command 3204 returns the value FONT_TARGET_UNAVAILABLE_NV if the implementation 3205 does not support a valid /fontTarget/, FONT_UNAVAILABLE_NV if 3206 the font is not available (e.g. does not exist on the system), or 3207 FONT_UNINTELLIGIBLE_NV if the font is available but cannot be loaded 3208 for some implementation-dependent reason. If the command generates 3209 an error, that error's enum value will be returned. For example, an 3210 invalid value for /fontTarget/ will return INVALID_ENUM. While the 3211 return value indicates the error, the error will /also/ be generated 3212 in the conventional way so GetError will return it and error callbacks 3213 are generated normally. 3214 3215 The /fontTarget/ parameter must be either SYSTEM_FONT_NAME_NV 3216 or FILE_NAME_NV; otherwise the INVALID_ENUM error is generated. 3217 The interpretation of the /fontTarget/ and /fontName/ parameters 3218 is identical to the interpretation described in section 5.X.1.3 3219 (Font Glyph Path Specification). 3220 3221 The error INVALID_VALUE is generated if /emScale/ is negative. 3222 3223 The /fontStyle/ parameter is a bitfield allowed to have the 3224 bits BOLD_BIT_NV or ITALIC_BIT_NV set; if other bits are set, the 3225 INVALID_VALUE error is generated. 3226 3227 When successful, elements 0 and 1 of the /baseAndCount/ array 3228 parameter are written values /B/ and /N/ respectively where the 3229 path names /B/ through /B+N-1/ are previously unused (i.e. there 3230 are /N/ previously unused path object names starting at /B/) but 3231 now are specified as path objects corresponding to the complete set 3232 of glyphs in the font indicated by /fontTarget/ and /fontName/. 3233 When unsuccessful (including when any error, even OUT_OF_MEMORY, 3234 is generated by the command), elements 0 and 1 of the /baseAndCount/ 3235 array parameter are both written to zero. 3236 3237 The path objects are created in the same manner described for 3238 PathGlyphsNV in section 5.X.1.3 (Font Glyph Path Specification) 3239 except the GLYPH_HAS_KERNING_BIT_NV and FONT_HAS_KERNING_BIT_NV 3240 metrics are always false (because GetPathSpacingNV applies to 3241 glyphs specified from Unicode code points). In particular, the 3242 /pathParameterTemplate/ and /emScale/ parameters have the same 3243 interpretation as the PathGlyphsNV command. 3244 3245 5.X.1.4 Path Modification 3246 3247 Several commands allow the commands and/or coordinates of an existing 3248 path object to be modified. 3249 3250 The command 3251 3252 void PathCoordsNV(uint path, 3253 sizei numCoords, enum coordType, 3254 const void *coords); 3255 3256 replaces all the coordinates of an existing path object with a new 3257 set of coordinates. /path/ names the path object to modify; the 3258 error INVALID_OPERATION is generated if /path/ is not an existing 3259 path object. 3260 3261 The new path coordinates are read sequentially from the 3262 /coords/ array. The type of the coordinates read from the /coords/ 3263 array is determined by the /coordType/ parameter which must be 3264 one of BYTE, UNSIGNED_BYTE, SHORT, UNSIGNED_SHORT, or FLOAT, 3265 otherwise the INVALID_ENUM error is generated. 3266 3267 The INVALID_OPERATION error is generated if /numCoords/ does not 3268 equal the number of coordinates referenced by the path object's 3269 existing command sequence (so /numCoords/ provides a sanity check 3270 that the /coords/ array is being interpreted properly). The error 3271 INVALID_VALUE is generated if /numCoords/ is negative. 3272 3273 If the PathCoordsNV command results in an error, the path object named 3274 /path/ is not changed; if there is no error, the prior coordinates of 3275 /path/ are lost. If there is no error, the commands and parameters 3276 of the path object are not changed. 3277 3278 The command 3279 3280 void PathSubCoordsNV(uint path, 3281 sizei coordStart, 3282 sizei numCoords, enum coordType, 3283 const void *coords); 3284 3285 replaces a range of the coordinates of an existing path object with 3286 a new set of coordinates. /path/ names the path object to modify; 3287 the error INVALID_OPERATION is generated if /path/ is not an existing 3288 path object. 3289 3290 The new path coordinates are read sequentially from the 3291 /coords/ array. The type of the coordinates read from the /coords/ 3292 array is determined by the /coordType/ parameter which must be 3293 one of BYTE, UNSIGNED_BYTE, SHORT, UNSIGNED_SHORT, or FLOAT, 3294 otherwise the INVALID_ENUM error is generated. 3295 3296 The coordinates from the /coords/ array replace the coordinates 3297 starting at coordinate index (zero-based) /coordStart/ through 3298 /coordStart/+/numCoords/-1 inclusive in the existing path object's 3299 coordinate array. If /numCoords/ is zero, no coordinates are changed. 3300 If /coordStart/+/numCoords/ is greater than the number of coordinates 3301 in the existing path object, the INVALID_OPERATION error is generated. 3302 If either /coordStart/ or /numCoords/ is negative, the INVALID_VALUE 3303 error is generated. 3304 3305 If the PathCoordsNV command results in an error, the path object named 3306 /path/ is not changed; if there is no error, the prior coordinates 3307 within the updated range of /path/ are lost. If there is no error, 3308 the commands, coordinates outside the updated range, and parameters 3309 of the path object are not changed. 3310 3311 The command 3312 3313 void PathSubCommandsNV(uint path, 3314 sizei commandStart, sizei commandsToDelete, 3315 sizei numCommands, const ubyte *commands, 3316 sizei numCoords, enum coordType, 3317 const void *coords); 3318 3319 replaces a range of existing commands and their associated coordinates 3320 with a new sequence of commands and associated coordinates. /path/ 3321 names the path object to modify; the error INVALID_OPERATION is 3322 generated if /path/ is not an existing path object. 3323 3324 The error INVALID_OPERATION is generated if any of /commandStart/, 3325 /commandsToDelete/, /numCommands/, or /numCoords/ is negative. 3326 3327 The PathSubCommandsNV command works in two steps. 3328 First, deleting commands in the range /commandStart/ to 3329 /commandStart/+/commandsToDelete/-1 inclusive from the existing 3330 path object. If /commandsToDelete/ exceeds the number of commands 3331 from /commandStart/ to the end of the path command sequence, 3332 all the commands from /commandsToDelete/ on are deleted. This 3333 includes deleting the coordinates associated with these commands. 3334 If /commandsToDelete/ is zero, zero commands and zero coordinates are 3335 deleted. Second, /numCommands/ read sequentially from the /commands/ 3336 array are inserted into the existing path object immediately before 3337 index /commandStart/. This includes inserting a corresponding number 3338 of coordinates from the /coords/ array. If the index /commandStart/ 3339 is greater than the largest valid command index of the path object, 3340 the commands are simply appended to the end of the path objects 3341 command and coordinate sequences. 3342 3343 Each of the /numCommands/ commands in the /command/ array references 3344 a number of coordinates specified by "Coordinate count" column of 3345 Table 5.pathCommands, starting with the first (zero) element of 3346 the /coords/ array and advancing by the coordinate count for each 3347 command. If any of these /numCommands/ commands are not listed 3348 in the "Token" or "Character aliases" columns of Table 5.pathCommands, 3349 the INVALID_ENUM error is generated. 3350 3351 The INVALID_OPERATION error is generated if /numCoords/ does not equal 3352 the number of coordinates referenced by the command sequence to insert 3353 as specified by /numCommands/ and /commands/ (so /numCoords/ provides 3354 a sanity check that the /coords/ array is being interpreted properly). 3355 The error INVALID_VALUE is generated if any of /commandStart/, 3356 /commandsToDelete/, /numCommands/ or /numCoords/ are negative. 3357 3358 The type of the coordinates in the /coords/ array is specified 3359 by /coordType/ and must be one of BYTE, UNSIGNED_BYTE, SHORT, 3360 UNSIGNED_SHORT, or FLOAT; otherwise the INVALID_ENUM error is 3361 generated. 3362 3363 If the PathSubCommandsNV command results in an error, the path 3364 object named /path/ is not changed; if there is no error, the prior 3365 (now deleted) commands and coordinates within the updated range of 3366 /path/ are lost. If there is no error, the commands, coordinates 3367 outside the deleted range, and parameters of the path object are not 3368 changed though commands and coordinates indexed beyond /commandStart/ 3369 are shifted in their sequence within the path object to make room 3370 in the command and coordinate arrays for the newly inserted commands 3371 and coordinates. 3372 3373 5.X.1.5 Path Parameter Specification 3374 3375 Each path object has its own set of path parameters that control 3376 how the path object is filled and stroked when stenciled and covered. 3377 3378 Table 5.pathParameters 3379 3380 Name Type Required Values or Range 3381 ------------------------------- ------- ----------------------------------------------- 3382 PATH_STROKE_WIDTH_NV float non-negative 3383 PATH_INITIAL_END_CAP_NV enum FLAT, SQUARE_NV, ROUND_NV, TRIANGULAR_NV 3384 PATH_TERMINAL_END_CAP_NV enum FLAT, SQUARE_NV, ROUND_NV, TRIANGULAR_NV 3385 PATH_INITIAL_DASH_CAP_NV enum FLAT, SQUARE_NV, ROUND_NV, TRIANGULAR_NV 3386 PATH_TERMINAL_DASH_CAP_NV enum FLAT, SQUARE_NV, ROUND_NV, TRIANGULAR_NV 3387 PATH_JOIN_STYLE_NV enum MITER_REVERT_NV, MITER_TRUNCATE_NV, BEVEL_NV, ROUND_NV, NONE 3388 PATH_MITER_LIMIT_NV float non-negative 3389 PATH_DASH_OFFSET_NV float any value 3390 PATH_DASH_OFFSET_RESET_NV enum MOVE_TO_RESET_NV, MOVE_TO_CONTINUES_NV 3391 PATH_CLIENT_LENGTH_NV float non-negative 3392 PATH_FILL_MODE_NV enum COUNT_UP_NV, COUNT_DOWN_NV, INVERT 3393 PATH_FILL_MASK_NV integer any value 3394 PATH_FILL_COVER_MODE_NV enum CONVEX_HULL_NV, BOUNDING_BOX_NV 3395 PATH_STROKE_COVER_MODE_NV enum CONVEX_HULL_NV, BOUNDING_BOX_NV 3396 PATH_STROKE_MASK_NV integer any value 3397 PATH_STROKE_BOUND_NV float any value in [0.0,1.0] 3398 3399 The commands 3400 3401 void PathParameterivNV(uint path, enum pname, const int *value); 3402 void PathParameteriNV(uint path, enum pname, int value); 3403 void PathParameterfvNV(uint path, enum pname, const float *value); 3404 void PathParameterfNV(uint path, enum pname, float value); 3405 3406 specify the value of path parameters for the specified path object 3407 named /path/. The error INVALID_OPERATION is generated if /path/ 3408 is not an existing path object. 3409 3410 Each parameter has a single (scalar) value. 3411 3412 /pname/ must be one of the tokens in the "Name" column of 3413 Table 5.pathParameters, PATH_END_CAPS_NV, or PATH_DASH_CAPS_NV. 3414 The required values or range of each allowed parameter name token 3415 is listed in Table 5.pathParameter's "Required Values/Range" column. 3416 3417 For values of /pname/ listed in Table 5.pathsParameters, the specified 3418 parameter is specified by /value/ when /value/ is a float or int, 3419 or if /value/ is a pointer to a float or int, accessed through that 3420 pointer. The error INVALID_VALUE is generated if the specified 3421 value is negative for parameters required to be non-negative in 3422 Table 5.pathParameters. Values specified to be clamped to the [0,1] range 3423 in Table 5.pathParameters are so clamped prior to setting the 3424 specified path parameter to that clamped value. 3425 3426 The /pname/ of PATH_END_CAPS_NV is handled specially and updates 3427 /both/ the PATH_INITIAL_END_CAP_NV and PATH_TERMINAL_END_CAP_NV 3428 parameters of the path with the specified value. The /pname/ 3429 of PATH_DASH_CAPS_NV is handled specially and updates /both/ the 3430 PATH_INITIAL_DASH_CAP_NV and PATH_TERMINAL_DASH_CAP_NV parameters 3431 of the path with the specified value. 3432 3433 The error INVALID_VALUE is generated if the specified parameter value 3434 is not within the require range for parameters typed float or integer. 3435 The error INVALID_ENUM is generated if the specified parameter value 3436 is not one of the listed tokens for parameters typed enum. 3437 3438 The dash pattern of a path object consists of a sequence of path-space 3439 lengths of alternating "on" and "off" dash segments. The first 3440 value of the dash array defines the length, in path space, of the 3441 first "on" dash segment. The second value defines the length of the 3442 following "off" segment. Each subsequent pair of values defines one 3443 "on" and one "off" segment. 3444 3445 Parameters to control the dash pattern of a stroked path are specified 3446 by the command 3447 3448 void PathDashArrayNV(uint path, 3449 sizei dashCount, const float *dashArray); 3450 3451 where /path/ is the name of an existing path object. The error 3452 INVALID_OPERATION is generated if /path/ is not an existing path 3453 object. 3454 3455 A /dashCount/ of zero indicates the path object is not dashed; in 3456 this case, the /dashArray/ is not accessed. Otherwise, /dashCount/ 3457 provides a count of how many float values to read from the /dashArray/ 3458 array. If any of the /dashCount/ elements of /dashArray/ are 3459 negative, the INVALID_VALUE error is generated. 3460 3461 If /dashCount/ is negative, the INVALID_VALUE error is generated. 3462 3463 If an error occurs, the path object's existing dash pattern state 3464 is not changed. 3465 3466 The path parameters of a newly specified path object are initialized 3467 as specified in Table 6.Y. 3468 3469 5.X.1.6 Path Weighting, Interpolation, and Copying 3470 3471 The command 3472 3473 void WeightPathsNV(uint resultPath, 3474 sizei numPaths, 3475 const uint paths[], const float weights[]); 3476 3477 linearly combines, as appropriate, the /numPaths/ path objects in 3478 the array paths based on each path object's respective weight from 3479 the weights array. The resulting path creates or replaces the 3480 path object /resultPath/. The INVALID_VALUE error is generated if 3481 /numPaths/ is less than one. 3482 3483 If the /resultPath/ name also names one of the paths in the /paths/ 3484 array, the path resulting from the linear combination of paths 3485 replaces the source path also named /resultPath/ but not until after 3486 the linear combination path has been determined. 3487 3488 This command requires all the paths in the paths array to 3489 be /consistent/; otherwise the INVALID_OPERATION error is 3490 generated. For all the paths to be /consistent/, all /numPaths/ paths 3491 in the /paths/ array must have the identical count of commands and 3492 each corresponding /i/th command in each path must have the identical 3493 command type. 3494 3495 However the arc commands (specifically SMALL_CCW_ARC_TO_NV, 3496 RELATIVE_SMALL_CCW_ARC_TO_NV, SMALL_CW_ARC_TO_NV, 3497 RELATIVE_SMALL_CW_ARC_TO_NV, LARGE_CCW_ARC_TO_NV, 3498 RELATIVE_LARGE_CCW_ARC_TO_NV, LARGE_CW_ARC_TO_NV, 3499 RELATIVE_LARGE_CW_ARC_TO_NV, CIRCULAR_CCW_ARC_TO_NV, 3500 CIRCULAR_CW_ARC_TO_NV, CIRCULAR_TANGENT_ARC_TO_NV, ARC_TO_NV, and 3501 RELATIVE_ARC_TO_NV) can not be weighted because the linear combination 3502 of the curves these arc commands generate do not generally result in 3503 a command of the same form; so if any of these arc commands appears 3504 in a path object passed to WeightPathsNV the INVALID_OPERATION error 3505 is generated. 3506 3507 The weighted path has a command sequence identical to any of the 3508 input path objects to be weighted (since all the input path command 3509 sequences are required to be identical). 3510 3511 The weighted path has a coordinate sequence constructed by weighting 3512 each correspondingly indexed coordinate /i/ for all paths indexed by 3513 /j/ from zero to /numPaths/-1 in the /paths/ array. Each coordinate 3514 /i/ from path /j/ is weighted by the weight in /weights/ indexed 3515 by /j/. 3516 3517 The path parameters for the weighted path are copied from the path 3518 named by the first (0th) element of the /paths/ array. The path 3519 metric values (as queried by GetPathMetricsNV in section 6.X.3) 3520 are all specified to be -1 for the newly specified path object 3521 (ignoring the path metrics for all the input path objects). 3522 Kerning information (as queriable by GetPathSpacingNV in section 3523 6.X.3) is also not copied. 3524 3525 The command 3526 3527 void InterpolatePathsNV(uint resultPath, 3528 uint pathA, uint pathB, 3529 float weight); 3530 3531 is equivalent to 3532 3533 uint paths[2] = { pathA, pathB }; 3534 float weights[2] = { 1-weight, weight }; 3535 WeightPathsNV(resultPath, 2, paths, weights); 3536 3537 The command 3538 3539 void CopyPathNV(uint resultPath, uint srcPath); 3540 3541 copies the path object named /srcPath/ to the path object named 3542 /resultPath/. The error INVALID_OPERATION is generated if /srcPath/ 3543 does not exist. The outline (commands and coordinates), parameters, 3544 and glyph metrics and kerning information (if they exist) are all 3545 copied without change. 3546 3547 5.X.1.7 Path Transformation 3548 3549 The command 3550 3551 void TransformPathNV(uint resultPath, 3552 uint srcPath, 3553 enum transformType, 3554 const float *transformValues); 3555 3556 transforms the path object named /srcPath/ by the transform specified 3557 by the /transformType/ and its associated /transformValues/. 3558 The resulting path creates or replaces the path object /resultPath/. 3559 3560 If the /resultPath/ and /srcPath/ names are identical, the path resulting 3561 from the transform replaces the name after the source path is transformed. 3562 3563 The /transformType/ must be one of NONE, TRANSLATE_X_NV, 3564 TRANSLATE_Y_NV, TRANSLATE_2D_NV, TRANSLATE_3D_NV, AFFINE_2D_NV, 3565 AFFINE_3D_NV, TRANSPOSE_AFFINE_2D_NV, or TRANSPOSE_AFFINE_3D_NV. 3566 3567 transformType Matrix 3568 -------------------------- ------------------------- 3569 NONE [ 1 0 0 0 ] 3570 [ 0 1 0 0 ] 3571 [ 0 0 1 0 ] 3572 [ 0 0 0 1 ] 3573 3574 TRANSLATE_X_NV [ 1 0 0 v0 ] 3575 [ 0 1 0 0 ] 3576 [ 0 0 1 0 ] 3577 [ 0 0 0 1 ] 3578 3579 TRANSLATE_Y_NV [ 1 0 0 0 ] 3580 [ 0 1 0 v0 ] 3581 [ 0 0 1 0 ] 3582 [ 0 0 0 1 ] 3583 3584 TRANSLATE_2D_NV [ 1 0 0 v0 ] 3585 [ 0 1 0 v1 ] 3586 [ 0 0 1 0 ] 3587 [ 0 0 0 1 ] 3588 3589 TRANSLATE_3D_NV [ 1 0 0 v0 ] 3590 [ 0 1 0 v1 ] 3591 [ 0 0 1 v2 ] 3592 [ 0 0 0 1 ] 3593 3594 AFFINE_2D_NV [ v0 v2 0 v4 ] 3595 [ v1 v3 0 v5 ] 3596 [ 0 0 1 0 ] 3597 [ 0 0 0 1 ] 3598 3599 TRANSPOSE_AFFINE_2D_NV [ v0 v1 0 v2 ] 3600 [ v3 v4 0 v5 ] 3601 [ 0 0 1 0 ] 3602 [ 0 0 0 1 ] 3603 3604 AFFINE_3D_NV [ v0 v3 v6 v9 ] 3605 [ v1 v4 v7 v10 ] 3606 [ v2 v5 v8 v11 ] 3607 [ 0 0 0 1 ] 3608 3609 TRANSPOSE_AFFINE_3D_NV [ v0 v1 v2 v3 ] 3610 [ v4 v5 v6 v7 ] 3611 [ v8 v9 v10 v11 ] 3612 [ 0 0 0 1 ] 3613 3614 Table 5.transformType: Mapping from /transformType/ to a 4x4 3615 transform matrix where v/i/ is the ith (base 0) element of the 3616 /transformValues/ array. 3617 3618 The transformation of a path proceeds path command by path command. 3619 Each path command results in a transformed path command equivalent 3620 to what would happen if every point on the path command segment were 3621 transformed by the transform from Table 5.transformType and had a 3622 projective normalization applied. 3623 3624 Commands with absolute control points have their control points 3625 transformed by the effective 4x4 projective matrix, and the resulting 3626 x & y coordinates serve as the transformed command's respective 3627 control point. 3628 3629 Control points of relative commands are first made into absolute 3630 coordinates given the command's current control point, transformed 3631 in the same manner as an absolute control point, and then adjusted 3632 back to relative to their transformed current control point. 3633 3634 Horizontal and vertical line to commands are promoted to corresponding 3635 "line to" commands if the transformed command is not an exactly 3636 horizontal or vertical command respectively after transformation; 3637 otherwise, these commands are not promoted but may transition from 3638 horizontal to vertical or vice versa as the case may be. 3639 3640 Commands for partial elliptical arcs generate an equivalent new 3641 transformed arc. 3642 3643 XXX more detail/math about arcs? 3644 3645 The CIRCULAR_CCW_ARC_TO_NV and CIRCULAR_CW_ARC_TO_NV commands are 3646 converted to transformed *_ARC_TO_NV commands if the transformed 3647 circular arc is itself not a circular arc. 3648 3649 The CIRCULAR_TANGENT_ARC_TO_NV command is converted into a LINE_TO_NV 3650 command and *_ARC_TO_NV command if the transformed circular arc is 3651 itself not a circular arc. 3652 3653 The CLOSE_PATH_NV and RESTART_PATH_NV (having no control points) 3654 are undisturbed by path transformation. The order of path commands 3655 is invariant under path transformation. 3656 3657 5.X.1.8 Path Name Management 3658 3659 The command 3660 3661 uint GenPathsNV(sizei range); 3662 3663 returns an integer /n/ such that names /n/, ..., /n+range-1/ are 3664 previously unused (i.e. there are /range/ previously unused path object 3665 names starting at /n/). These names are marked as used, for the 3666 purposes of subsequent GenPathsNV only, but they do not acquire 3667 path object state until each particular name is used to specify 3668 a path object. 3669 3670 Path objects are deleted by calling 3671 3672 void DeletePathsNV(uint path, sizei range); 3673 3674 where /path/ contains /range/ names of path objects to be delete. 3675 After a path object is deleted, its name is again unused. Unused 3676 names in /paths/ are silently ignored. 3677 3678 The query 3679 3680 boolean IsPathNV(uint path); 3681 3682 returns TRUE if /path/ is the name of a path object. If path is 3683 not the name of a path object, or if an error condition occurs, 3684 IsPathNV returns FALSE. A name retuned by GenPathsNV, but without 3685 a path specified for it yet, is not the name of a path object. 3686 3687 5.X.2 Path Rendering 3688 3689 Path objects update the framebuffer through one of two processes: 3690 "stenciling" that updates /just/ the stencil buffer with the path's 3691 coverage information, and "covering" that rasterizes fragments into 3692 the framebuffer for a region guaranteed to cover the region of path 3693 coverage updated by stenciling, assuming the same path object, 3694 fill mode or stroking parameters, transformation state, and set of 3695 accessible samples (as will be explained). 3696 3697 5.X.2.1 Path Stenciling 3698 3699 STENCILING FILLED PATHS 3700 3701 The command 3702 3703 void PathStencilFuncNV(enum func, int ref, uint mask); 3704 3705 configures the stencil function, stencil reference value, and stencil 3706 read mask to be used by the StencilFillPathNV and StencilStrokePathNV 3707 commands described subsequently. The parameters accept the same 3708 values allowed by the StencilFunc command. 3709 3710 The command 3711 3712 void PathStencilDepthOffsetNV(float factor, float units); 3713 3714 configures the depth offset factor and units state (see section 3.6.4) 3715 to be used by the StencilFillPathNV and StencilStrokePathNV commands 3716 described subsequently. 3717 3718 The command 3719 3720 void StencilFillPathNV(uint path, 3721 enum fillMode, uint mask); 3722 3723 transforms into window space the outline of the path object named 3724 /path/ based on the current modelview, projection, viewport, 3725 and depth range transforms (ignoring any vertex and/or geometry 3726 shader or program that might be active/enabled) and then updates 3727 the stencil values of all /accessible samples/ (explained below) in 3728 the framebuffer. Each sample's stencil buffer value is updated based 3729 on the winding number of that sample with respect to the transformed 3730 outline of the path object with any non-closed subpath forced closed 3731 and the specified /fillMode/. 3732 3733 If /path/ does not name an existing path object, the command does 3734 nothing (and no error is generated). 3735 3736 If the path's command sequence specifies unclosed subpaths (so not 3737 contours) due to MOVE_TO_NV commands, such subpaths are trivially 3738 closed by connecting with a line segment the initial and terminal 3739 control points of each such path command subsequence. 3740 3741 Transformation of a path's outline works by taking all positions 3742 on the path's outline in 2D path space (x,y) and constructing an 3743 object space position (x,y,0,1) that is then used as the (xo,yo,zo,wo) 3744 position in section 2.12 ("Fixed-Function Vertex Transformation") 3745 to compute corresponding eye-space coordinates (xe,ye,ze,we) and 3746 clip-space coordinates (xc,yc,zc,wc). A path outline's clip-space 3747 coordinates are further transformed into window space as described in 3748 section 2.16 ("Coordinate Transformations"). This process provides a 3749 mapping 2D path coordinates to 2D window coordinates and depth values. 3750 The resulting 2D window coordinates are undefined if any of the 3751 transformations involved are singular or may be inaccurate if any 3752 of the transformations (or their combination) are ill-conditioned. 3753 3754 The winding number for a sample with respect to the path outline, 3755 transformed into window space, is computed by counting the (signed) 3756 number of revolutions around the sample point when traversing each 3757 (trivially closed if necessary) contour once in the transformed path. 3758 This traversal is performed in the order of the path's command 3759 sequence. Starting from an initially zero winding count, each 3760 counterclockwise revolution when the front face mode is CCW (or 3761 clockwise revolution when the front face mode is CW) around the sample 3762 point increments the winding count by one; while each clockwise 3763 revolution when the front face mode is CCW (or counterclockwise 3764 revolution when the front face mode is CW) around the sample point 3765 decrements the winding count by one. 3766 3767 The /mask/ parameter controls what subset of stencil bits are affected 3768 by the command. If the /mask/ parameter is zero, the path object's 3769 fill mask parameter (PATH_FILL_MASK_NV) is considered the effective 3770 value of /mask/. 3771 3772 The /fillMode/ parameter must be one of INVERT, COUNT_UP_NV, 3773 COUNT_DOWN_NV, or PATH_FILL_MODE_NV; otherwise the INVALID_ENUM error 3774 is generated. INVERT inverts the bits set in the effective /mask/ 3775 value for each sample's stencil value if the winding number for the 3776 given sample is odd. COUNT_UP_NV adds with modulo n arithmetic the 3777 winding number of each sample with the sample's prior stencil buffer 3778 value; the result of this addition is written into the sample's 3779 stencil value but the bits of the stencil value not set in the 3780 effective /mask/ value are left unchanged. COUNT_DOWN_NV subtracts 3781 with modulo /n/ arithmetic the winding number of each sample with the 3782 sample's prior stencil buffer value; the result of this subtraction is 3783 written into the sample's stencil value but the bits of the stencil 3784 value not set in the effective /mask/ value are left unchanged. 3785 PATH_FILL_MODE_NV uses the path object's counting mode parameter 3786 (one of INVERT, COUNT_UP_NV, or COUNT_DOWN_NV). 3787 3788 The value of /n/ for the modulo /n/ arithmetic used by COUNT_UP_NV 3789 and COUNT_DOWN_NV is the effective /mask/+1. The error INVALID_VALUE 3790 is generated if the specified /fillMode/ is COUNT_UP_NV or 3791 COUNT_DOWN_NV and the specified /mask/+1 is not an integer power 3792 of two. If the /fillMode/ is PATH_FILL_MODE_NV; the path object's 3793 counting mode parameter is COUNT_UP_NV or COUNT_DOWN_NV; and the 3794 effective mask+1 value is not an integer power of two, treat the 3795 mask as zero (effectively meaning no stencil bits will be modified). 3796 3797 ACCESSIBLE SAMPLES WITH RESPECT TO A TRANSFORMED PATH 3798 3799 The accessible samples of a transformed path that are updated are 3800 the samples that remain after discarding the following samples: 3801 3802 * Any sample that would be clipped as specified in section 2.22 3803 ("Primitive Clipping") because its corresponding position in 3804 clip space (xc,yc,zc,wc) or (xe,ye,ze,we) would be clipped 3805 by the clip volume or enabled client-defined clip planes. 3806 3807 * Any sample that would not be updated during polygon rendering 3808 due to polygon stipple (section 3.6.2) if POLYGON_STIPPLE 3809 is enabled. 3810 3811 * Any sample that would fail the pixel ownership test (section 3812 4.1.1) if rasterized. 3813 3814 * Any sample that would fail the scissor test (section 4.1.2) 3815 if SCISSOR_TEST is enabled. 3816 3817 * Any sample that would fail the depth test (section 4.1.6) 3818 if DEPTH_TEST is enabled where the fragment depth for the 3819 depth test comes from the depth plane of the path when 3820 transformed by the modelview, projection, viewport, and 3821 depth range transforms and depth offset (section 3.6.4) 3822 has been applied based on the slope of this plane operating 3823 as if POLYGON_OFFSET_FILL is forced enabled and using the 3824 factor and units parameters set by PathStencilDepthOffsetNV 3825 (rather than the state set by PolygonOffset). 3826 3827 * Any sample that would fail the depth bounds test (section 3828 4.1.X in EXT_depth_bounds_test specification) if 3829 DEPTH_BOUNDS_TEST_EXT is enabled. 3830 3831 And for the StencilFillPathNV and StencilStrokePathNV commands (so 3832 not applicable to the CoverFillPathNV and CoverStrokePathNV commands): 3833 3834 * Any sample that would fail the (implicitly enabled) stencil 3835 test (section 4.1.5) with the stencil function configured 3836 based on the path stencil function state configured by 3837 PathStencilFuncNV. In the case of the StencilFillPathNV 3838 and StencilStrokePathNV commands and their instanced 3839 versions (section 5.X.2.3), the effective stencil read 3840 mask for the stencil mask is treated as the value of 3841 PATH_STENCIL_VALUE_MASK bit-wise ANDed with the bit-invert 3842 of the effective /mask/ parameter value; otherwise, for the 3843 cover commands, the stencil test operates normally. In the 3844 case the stencil test fails during a path stencil operation, 3845 the stencil fail operation is ignored and the pixel's stencil 3846 value is left undisturbed (as if the stencil operation was 3847 KEEP). 3848 3849 * The state of the face culling (CULL_FACE) enable is ignored. 3850 3851 STENCILING STROKED PATHS 3852 3853 The command 3854 3855 void StencilStrokePathNV(uint path, 3856 int reference, uint mask); 3857 3858 transforms into window space the stroked region of the path object 3859 named /path/ based on the current modelview, projection, viewport, 3860 and depth range transforms (ignoring any vertex and/or geometry 3861 shader or program that might be active/enabled) and then updates 3862 the stencil values of a subset of the accessible samples (see above) 3863 in the framebuffer. 3864 3865 If /path/ does not name an existing path object, the command does 3866 nothing (and no error is generated). 3867 3868 The path object's stroke width parameter (PATH_STROKE_WIDTH_NV) in 3869 path space units determines the width of the path's stroked region. 3870 3871 When the dash array count of a path object is zero (dashing is 3872 considered subsequently), the stroke of a transformed path's outline 3873 is the region of window space defined by the union of: 3874 3875 * Sweeping an orthogonal centered line segment of the (above 3876 determined) effective stroke width along each path segment 3877 in the path's transformed outline. 3878 3879 * End cap regions (explained below) appended to the initial 3880 and terminal control points of non-closed command sequences 3881 in the path. For a sequence of commands that form a closed 3882 contour, the end cap regions are ignored. 3883 3884 * Join style regions (explained below) between connected path 3885 segments meet. 3886 3887 Any accessible samples within the union of these three regions are 3888 considered within the path object's stroke. 3889 3890 The /mask/ parameter controls what subset of stencil bits are affected 3891 by the command. If the /mask/ parameter is zero, the path object's 3892 stroke mask parameter (PATH_STROKE_MASK_NV) is considered the effective 3893 value of /mask/. 3894 3895 A sample's stencil bits that are set in the effective /mask/ value 3896 are updated with the specified stencil /reference/ value if the 3897 sample is accessible (as specified above) and within the stroke of 3898 the transformed path's outline. 3899 3900 Every path object has an initial and terminal end cap parameter 3901 (PATH_INITIAL_END_CAP_NV and PATH_TERMINAL_END_CAP_NV) that is 3902 one of FLAT, SQUARE_NV, ROUND_NV, or TRIANGULAR_NV. There are no 3903 samples within a FLAT end cap. The SQUARE_NV cap extends centered 3904 and tangent to the given end (initial or terminal) of the subpath 3905 for half the effective stroke width; in other words, a square cap 3906 is a half-square that kisses watertightly the end of a subpath. 3907 The ROUND_NV cap appends a semi-circle, centered and tangent, 3908 with the diameter of the effective stroke width to the given end 3909 (initial or terminal) of the subpath; in other words, a round cap 3910 is a semi-circle that kisses watertightly the end of a subpath. 3911 The TRIANGULAR_NV cap appends a right triangle, centered and tangent, 3912 with its hypotenuse flush to the given end of the subpath; in other 3913 words, a triangular cap is a right triangle that kisses watertightly 3914 the end of a subpath with the triangle's longest side. 3915 3916 Every path object has a join style parameter (PATH_JOIN_STYLE_NV) 3917 that is one of BEVEL_NV, ROUND_NV, MITER_REVERT_NV, MITER_TRUNCATE_NV, 3918 or NONE; each path object also has a miter limit value. The BEVEL_NV 3919 join style inserts a triangle with two vertices at the outside 3920 corners where two connected path segments join and a third vertex at 3921 the common end point shared by the two path segments. The ROUND_NV 3922 join style inserts a wedge-shaped portion of a circle centered at 3923 the common end point shared by the two path segments; the radius of 3924 the circle is half the effective stroke width. There are no samples 3925 within a NONE join style. The MITER_REVERT_NV join style inserts a 3926 quadrilateral with two opposite vertices at the outside corners where 3927 the two connected path segments join and two opposite vertices with 3928 one on the path's junction between the two joining path segments and 3929 the other at the common end point shared by the two path segments. 3930 However, the MITER_REVERT_NV join style behaves as the BEVEL_NV 3931 style if the sine of half the angle between the two joined segments 3932 is less than the path object's PATH_STROKE_WIDTH value divided by 3933 the path's PATH_MITER_LIMIT_NV value. The MITER_TRUNCATE_NV join 3934 style is similar to MITER_REVERT_NV but rather than reverting to a 3935 bevel when the miter limit is exceeded, instead the tip of the miter 3936 quadrilateral is truncated such that the miter does not extend beyond 3937 the miter limit. 3938 3939 When the dash array count of a path object is /not/ zero, the path is 3940 broken up into a sequence of paths based on the path object's dash 3941 array count, dash array, dash offset, and dash cap parameters (see 3942 section 5.X.1.5). This sequence of paths are handled as if their 3943 dash count array is zero so their stroked region can be determined 3944 for this stroking case that has already been explained. 3945 3946 The dash pattern defined by the dash array is a sequence of lengths of 3947 alternating "on" and "off" dash segments. The first (0th) element of 3948 the dash array defines the length, in path space, of the first "on" 3949 dash segment. The second value defines the length of the following 3950 "off" segment. Each subsequent pair of values defines on "on" 3951 and one "off" segment. 3952 3953 The initial cap of the first dash segment uses the path's initial 3954 dash cap style state (PATH_INITIAL_END_CAP_NV) as the effective 3955 initial end cap for this first dash segment; the terminal cap 3956 of the last dash segment uses the path's terminal dash cap style 3957 state (PATH_TERMINAL_END_CAP_NV) as the effective terminal cap for 3958 this last dash segment; all other caps of dash segments use the 3959 PATH_INITIAL_DASH_CAP_NV for the initial cap of the segment and the 3960 PATH_TERMINAL_DASH_CAP_NV for the terminal cap of the segment. 3961 3962 The MOVE_TO_RESETS_NV value for a path's dash offset reset parameter 3963 (PATH_DASH_OFFSET_RESET_NV) means that the dash offset resets to the 3964 path's dash offset parameter upon a MOVE_TO_NV, RELATIVE_MOVE_TO_NV, 3965 RESTART_PATH_NV, or RECT_NV command (an command that does an implicit 3966 or explicit move-to) while dashing the path's command sequence. 3967 The MOVE_TO_CONTINUES_NV value means that the dash pattern 3968 progresses normally (without reset) when dashing a MOVE_TO_NV or 3969 RELATIVE_MOVE_TO_NV command. 3970 3971 Every path object has a stroke approximation bound parameter 3972 (PATH_STROKE_BOUND_NV) that is a floating-point value /sab/ clamped 3973 between 0.0 and 1.0 and set and queried with the PATH_STROKE_BOUND_NV 3974 path parameter. Exact determination of samples swept an orthogonal 3975 centered line segment along cubic Bezier segments and rational 3976 quadratic Bezier curves (so non-circular partial elliptical arcs) is 3977 intractable for real-time rendering so an approximation is required; 3978 /sab/ intuitively bounds the approximation error as a percentage of 3979 the path object's stroke width. Specifically, this path parameter 3980 requests the implementation to stencil any samples within /sweep/ 3981 object space units of the exact sweep of the path's cubic Bezier 3982 segments or partial elliptical arcs to be sampled by the stroke where 3983 3984 sweep = ((1-sab)*sw)/2 3985 3986 where /sw/ is the path object's stroke width. The initial value 3987 of /sab/ when a path is created is 0.2. In practical terms, this 3988 initial value means the stencil sample positions coverage within 80% 3989 (100%-20%) of the stroke width of cubic and rational quadratic stroke 3990 segments should be sampled. 3991 3992 If the path object's client length parameter (PATH_CLIENT_LENGTH_NV) 3993 value /clen/ is non-zero, prior to generating the dashed segments, the 3994 dash pattern and dash offset lengths should be scaled by (multiplied 3995 by) the clen/plen where /plen/ is the path object's computed length 3996 (PATH_COMPUTED_LENGTH_NV). 3997 3998 5.X.2.2 Path Covering 3999 4000 COVERING FILLED PATHS 4001 4002 The command 4003 4004 void PathCoverDepthFuncNV(enum zfunc); 4005 4006 configures the depth function to be used by the CoverFillPathNV and 4007 CoverStrokePathNV commands described subsequently. The /zfunc/ parameter 4008 accepts the same values allowed by the DepthFunc command. 4009 4010 The command 4011 4012 void CoverFillPathNV(uint path, enum coverMode); 4013 4014 transforms into window space the outline of the path object named 4015 /path/ based on the current modelview, projection, viewport, 4016 and depth range transforms (ignoring any vertex and/or geometry 4017 shader or program that might be active/enabled) and rasterizes a 4018 subset of the accessible samples in the framebuffer guaranteed to 4019 include all samples that would be have a net stencil value change if 4020 StencilFillPathNV were issued with the same modelview, projection, 4021 and viewport state. During this rasterization, the stencil test 4022 operates normally and as configured; the expectation is the stencil 4023 test will be used to discard samples not determined "covered" by a 4024 prior StencilFillPathNV command. The depth function, if DEPTH_TEST is 4025 enabled, during this rasterization uses the function specified by 4026 PathCoverDepthFuncNV (instead of the state specified by DepthFunc). 4027 4028 If /path/ does not name an existing path object, the command does 4029 nothing (and no error is generated). 4030 4031 /coverMode/ must be one of CONVEX_HULL_NV, BOUNDING_BOX_NV, or 4032 PATH_FILL_COVER_MODE_NV. The PATH_FILL_COVER_MODE_NV uses the path 4033 object's PATH_FILL_COVER_MODE_NV parameter value as the effective 4034 fill cover mode of the cover command. 4035 4036 When /coverMode/ is CONVEX_HULL_NV or BOUNDING_BOX_NV, the subset 4037 of accessible pixels that are rasterized are within a convex 4038 hull or bounding box respectively (each expected to be reasonably 4039 tight) surrounding all the samples guaranteed to be rasterized by 4040 CoverFillPathNV. The bounding box must be orthogonally aligned 4041 to the path space coordinate system. (The area of the bounding 4042 box in path space is guaranteed to be greater than or equal the 4043 area of the convex hull in path space.) Each rasterized sample 4044 will be rasterized once and exactly once when CONVEX_HULL_NV or 4045 BOUNDING_BOX_NV is specified. 4046 4047 While samples with a net stencil change /must/ be rasterized, 4048 implementations are explicitly allowed to vary in the rasterization 4049 of samples for which StencilFillPathNV would /not/ change sample's 4050 net stencil value. This means implementations are allowed to (and, 4051 in fact, are expected to) conservatively "exceed" the region strictly 4052 stenciled by the path object. 4053 4054 CoverFillPathNV /requires/ the following rasterization invariance: 4055 calling CoverFillPathNV for the same (unchanged) path object with 4056 fixed (unchanged) modelview, projection, and viewport transform state 4057 with the same (unchanged) set of accessible samples will rasterize 4058 the exact same set of samples with identical interpolated values 4059 for respective fragment/sample locations. 4060 4061 COVERING STROKED PATHS 4062 4063 The command 4064 4065 void CoverStrokePathNV(uint path, enum coverMode); 4066 4067 operates in the same manner as CoverFillPathNV except the region 4068 guaranteed to be rasterized is, rather than the region within /path/'s 4069 filled outline, instead the region within the /path/'s stroked region 4070 as determined by StencilStrokePathNV. During this rasterization, 4071 the stencil test operates normally and as configured; the expectation 4072 is the stencil test will be used to discard samples not determined 4073 "covered" by a prior StencilStrokePathNV command. As with CoverFillPathNV, 4074 the depth function, if DEPTH_TEST is enabled, uses the function specified 4075 by PathCoverDepthFuncNV. 4076 4077 /coverMode/ must be one of CONVEX_HULL_NV, BOUNDING_BOX_NV, or 4078 PATH_STROKE_COVER_MODE_NV. The PATH_STROKE_COVER_MODE_NV uses 4079 the path object's PATH_STROKE_COVER_MODE_NV parameter value as the 4080 effective stroke cover mode of the cover command. 4081 4082 If /path/ does not name an existing path object, the command does 4083 nothing (and no error is generated). 4084 4085 Analogous to the rasterization guarantee of CoverFillPathNV with 4086 respect to StencilFillPathNV, CoverStrokePathNV guarantees that all 4087 samples rasterized by StencilStrokePathNV, given the same transforms 4088 and accessible pixels and stroke width, will also be rasterized by 4089 the corresponding CoverStrokePathNV. 4090 4091 CoverStrokePathNV /requires/ the following rasterization invariance: 4092 calling CoverStrokePathNV for the same (unchanged) path object with 4093 fixed (unchanged) modelview, projection, and viewport transform 4094 state and with the same (unchanged) set of accessible samples will 4095 rasterize the exact same set of samples with identical interpolated 4096 values for respective fragment/sample locations. 4097 4098 PATH COVERING RASTERIZATION DETAILS 4099 4100 The GL processes fragments rasterized by path cover commands in 4101 much the same manner as fragments generated by conventional polygon 4102 rasterization. However path rendering /ignores/ the following 4103 operations: 4104 4105 * Interpolation of per-vertex data (section 3.6.1). Path 4106 primitives have neither conventional vertices nor per-vertex 4107 data. Instead fragments generate interpolated per-fragment 4108 colors, texture coordinate sets, and fog coordinates as a 4109 linear function of object-space or eye-space path coordinate's 4110 or using the current color, texture coordinate set, or fog 4111 coordinate state directly. 4112 4113 * Polygon smooth (section 3.6.3). 4114 4115 * Polygon mode (section 3.6.4). Fragments generated by path 4116 covering never result from point or line rasterizations. 4117 4118 Polygon stippling (section 3.6.2), depth offset (section 3.6.5), and 4119 polygon multisample rasterization (3.6.6) do apply to path covering. 4120 4121 Front and back face determination (explained in section 3.6.1 for 4122 polygons) operates somewhat differently for transformed paths than 4123 polygons. The path's convex hull, bounding box, or multiple hulls 4124 (depending on the /coverMode/) are specified to wind counterclockwise 4125 in object space though the transformation of the convex hull into 4126 window space could reverse this winding. Whether the GL's front face 4127 state is CCW or CCW (as set by the FrontFace command) determines 4128 if the path is front facing or not. Because the specific vertices 4129 that belong to the covering geometry are implementation-dependent, 4130 when the signed area of the covering geometry (computed with equation 4131 3.8) is sufficiently near zero, the facingness of the path in such 4132 situations is ill-defined. 4133 4134 The determination of whether a path transformed into window space is 4135 front facing or not affects face culling if enabled (section 3.6.1), 4136 the gl_FrontFacing built-in variable (section 3.12.22), and separate 4137 (two-sided) stencil testing (section 4.1.5). 4138 4139 Once fragments have been generated by path covering, the fragments 4140 are shaded in the same manner as fragments generated by polygon 4141 rasterization with the following exception: If a GLSL program is 4142 in use, any vertex or geometry shader linked into the GLSL program 4143 is ignored. The fragment shader operates normally except that 4144 user-defined inputs to the fragment shader behave as specified by 4145 ProgramPathFragmentInputGenNV. When supported, the fragment shader 4146 could also use the built-in varying inputs: gl_Texcoord[i], 4147 gl_Color, gl_SecondaryColor, and gl_FogFragCoord. 4148 4149 COLOR GENERATION FOR PATH COVER COMMANDS 4150 4151 The command 4152 4153 void PathColorGenNV(enum color, 4154 enum genMode, 4155 enum colorFormat, const float *coeffs); 4156 4157 controls how the primary and secondary interpolated colors are 4158 computed for fragment shading operations that occur as a result of 4159 CoverFillPathNV or CoverStrokePathNV. 4160 4161 /color/ must be one of PRIMARY_COLOR, 4162 PRIMARY_COLOR_NV, SECONDARY_COLOR_NV to specify the indicated color 4163 generation state for the primary, primary, and secondary color 4164 respectively; otherwise INVALID_ENUM is generated. 4165 4166 /genMode/ must be one of NONE, OBJECT_LINEAR, 4167 PATH_OBJECT_BOUNDING_BOX_NV, EYE_LINEAR, or CONSTANT; otherwise 4168 INVALID_ENUM is generated. 4169 4170 NONE means the color is not generated but rather uses the 4171 corresponding color's current color state. OBJECT_LINEAR means that 4172 the specified color is generated from a linear combination of the 2D 4173 path coordinates (x,y). EYE_LINEAR means the specified color 4174 is generated from a linear combination of path's 2D coordinates 4175 transformed in eye space, so (xe, ye, ze, we) from section 2.12 4176 ("Fixed-Function Vertex Transformation"). CONSTANT means the specified 4177 color is generated from the specified constant coefficients. 4178 4179 When covering single paths with CoverFillPathNV or CoverStrokePathNV, 4180 PATH_OBJECT_BOUNDING_BOX_NV means the specified color is generated 4181 as a function of object-space (x,y) coordinate normalized to the 4182 [0..1]x[0..1] range where (0,0) is the corner of the path object's 4183 bounding box with the minimum x and minimum y coordinates and (1,1) 4184 is the corner of the path object's bounding box with the maximum x and 4185 maximum y coordinates. Using PATH_OBJECT_BOUND_BOX_NV for /genMode/ 4186 means generated colors are undefined if either the width or height 4187 of the path's bounding box is zero. 4188 4189 When covering instanced paths with CoverFillPathInstancedNV or 4190 CoverStrokePathInstancedNV using the BOUNDING_BOX_OF_BOUNDING_BOXES_NV 4191 cover mode (see section 5.X.2.3), the specified color is generated 4192 as a function of object-space (x,y) coordinate normalized to the 4193 [0..1]x[0..1] range where (0,0) is the corner of the bounding box of 4194 the union of bounding boxes of the set of instanced path objects and 4195 (1,1) is the corner of the same union bounding box with the maximum 4196 x and maximum y coordinates. 4197 4198 When /genMode/ is NONE, then /colorFormat/ must be NONE; 4199 otherwise INVALID_ENUM is generated. When /genMode/ is not NONE, 4200 then /colorFormat/ must be one of LUMINANCE, ALPHA, INTENSITY, 4201 LUMINANCE_ALPHA, RGB, or RGBA; otherwise INVALID_ENUM is generated. 4202 4203 In the following equations used for path color generation, coeffs[i] 4204 is the /i/th element (base zero) of the /coeffs/ array; Rc, Gc, 4205 Bc, and Aa are the red, green, blue, and alpha colors of the current 4206 primary or secondary color (depending on the color parameter) when the 4207 path is covered; and x, y, z, and w are determined by the /genMode/. 4208 4209 When /genMode/ is EYE_LINEAR, xcoeffs[i] is the /i/th element (base 4210 zero) of a /xcoeffs/ array generated by multiplying each respective 4211 vector of four elements of coeffs by the current inverse modelview 4212 matrix when PathColorGenNV is called. 4213 4214 xcoeffs[0..3] = coeffs[0..3] * MV^-1 4215 xcoeffs[4..7] = coeffs[4..7] * MV^-1 4216 xcoeffs[8..11] = coeffs[8..11] * MV^-1 4217 xcoeffs[12..15] = coeffs[12..12] * MV^-1 4218 4219 [[ NOTATION: 4220 4221 xxx[0..3] is a vector form from xxx[0], xxx[1], xxx[2], and xxx[3] 4222 4223 MV^-1 is the inverse of the current modelview matrix when PathColorGenNV happens. 4224 4225 ]] 4226 4227 If the /genMode/ is NONE, no values from the /coeffs/ array are 4228 accessed and the R, G, B, and A components of a covered fragment's 4229 varying color (be it primary or secondary depending on color) 4230 are computed: 4231 4232 R = Rc 4233 G = Gc 4234 B = Bc 4235 A = Ac 4236 4237 If /colorFormat/ is LUMINANCE and /genMode/ is either OBJECT_LINEAR 4238 or PATH_OBJECT_BOUNDING_BOX_NV, then 3 values are accessed from the 4239 /coeffs/ array and the R, G, B, and A components of a covered 4240 fragment's varying color are computed: 4241 4242 R = coeffs[0] * x + coeffs[1] * y + coeffs[2] 4243 G = coeffs[0] * x + coeffs[1] * y + coeffs[2] 4244 B = coeffs[0] * x + coeffs[1] * y + coeffs[2] 4245 A = Ac 4246 4247 Alternatively if the /genMode/ is EYE_LINEAR, then 4 values are 4248 accessed and the varying color components are computed: 4249 4250 R = xcoeffs[0] * xe + xcoeffs[1] * ye + xcoeffs[2] * ze + xcoeffs[3] * we 4251 G = xcoeffs[0] * xe + xcoeffs[1] * ye + xcoeffs[2] * ze + xcoeffs[3] * we 4252 B = xcoeffs[0] * xe + xcoeffs[1] * ye + xcoeffs[2] * ze + xcoeffs[3] * we 4253 A = Ac 4254 4255 Alternatively if the /genMode/ is CONSTANT, then: 4256 4257 R = xcoeffs[0] 4258 G = xcoeffs[0] 4259 B = xcoeffs[0] 4260 A = Ac 4261 4262 If /colorFormat/ is INTENSITY and /genMode/ is either OBJECT_LINEAR 4263 or PATH_OBJECT_BOUNDING_BOX_NV, then 3 values are accessed from 4264 the /coeffs/ array and the R, G, B, and A components of a covered 4265 fragment's varying color are computed: 4266 4267 R = coeffs[0] * x + coeffs[1] * y + coeffs[2] 4268 G = coeffs[0] * x + coeffs[1] * y + coeffs[2] 4269 B = coeffs[0] * x + coeffs[1] * y + coeffs[2] 4270 A = coeffs[0] * x + coeffs[1] * y + coeffs[2] 4271 4272 Alternatively if the /genMode/ is EYE_LINEAR, then 4 values are 4273 accessed and the varying color components are computed: 4274 4275 R = xcoeffs[0] * xe + xcoeffs[1] * ye + xcoeffs[2] * ze + xcoeffs[3] * we 4276 G = xcoeffs[0] * xe + xcoeffs[1] * ye + xcoeffs[2] * ze + xcoeffs[3] * we 4277 B = xcoeffs[0] * xe + xcoeffs[1] * ye + xcoeffs[2] * ze + xcoeffs[3] * we 4278 A = xcoeffs[0] * xe + xcoeffs[1] * ye + xcoeffs[2] * ze + xcoeffs[3] * we 4279 4280 Alternatively if the /genMode/ is CONSTANT, then: 4281 4282 R = xcoeffs[0] 4283 G = xcoeffs[0] 4284 B = xcoeffs[0] 4285 A = xcoeffs[0] 4286 4287 If /colorFormat/ is ALPHA and /genMode/ is either OBJECT_LINEAR 4288 or PATH_OBJECT_BOUNDING_BOX_NV, then 3 values are accessed from 4289 the /coeffs/ array and the R, G, B, and A components of a covered 4290 fragment's varying color are computed: 4291 4292 R = Rc 4293 G = Gc 4294 B = Bc 4295 A = coeffs[0] * x + coeffs[1] * y + coeffs[2] 4296 4297 Alternatively if the /genMode/ is EYE_LINEAR, then 4 values are 4298 accessed and the varying color components are computed: 4299 4300 R = Rc 4301 G = Gc 4302 B = Bc 4303 A = xcoeffs[0] * xe + xcoeffs[1] * ye + xcoeffs[2] * ze + xcoeffs[3] * we 4304 4305 Alternatively if the /genMode/ is CONSTANT, then: 4306 4307 R = Rc 4308 G = Gc 4309 B = Bc 4310 A = xcoeffs[0] 4311 4312 If /colorFormat/ is RGB and /genMode/ is either OBJECT_LINEAR or 4313 PATH_OBJECT_BOUNDING_BOX_NV, then 9 values are accessed from the 4314 /coeffs/ array and the R, G, B, and A components of a covered 4315 fragment's varying color are computed: 4316 4317 R = coeffs[0] * x + coeffs[1] * y + coeffs[2] 4318 G = coeffs[3] * x + coeffs[4] * y + coeffs[5] 4319 B = coeffs[6] * x + coeffs[7] * y + coeffs[8] 4320 A = Ac 4321 4322 Alternatively if the /genMode/ is EYE_LINEAR, then 12 values are 4323 accessed and the varying color components are computed: 4324 4325 R = xcoeffs[0] * xe + xcoeffs[1] * ye + xcoeffs[2] * ze + xcoeffs[3] * we 4326 G = xcoeffs[4] * xe + xcoeffs[5] * ye + xcoeffs[6] * ze + xcoeffs[7] * we 4327 B = xcoeffs[8] * xe + xcoeffs[9] * ye + xcoeffs[10] * ze + xcoeffs[11] * we 4328 A = Ac 4329 4330 Alternatively if the /genMode/ is CONSTANT, then: 4331 4332 R = xcoeffs[0] 4333 G = xcoeffs[1] 4334 B = xcoeffs[2] 4335 A = Ac 4336 4337 If /colorFormat/ is RGBA and /genMode/ is either OBJECT_LINEAR 4338 or PATH_OBJECT_BOUNDING_BOX_NV, then 12 values are accessed from 4339 the /coeffs/ array and the R, G, B, and A components of a covered 4340 fragment's varying color are computed: 4341 4342 R = coeffs[0] * x + coeffs[1] * y + coeffs[2] 4343 G = coeffs[3] * x + coeffs[4] * y + coeffs[5] 4344 B = coeffs[6] * x + coeffs[7] * y + coeffs[8] 4345 A = coeffs[9] * x + coeffs[10] * y + coeffs[11] 4346 4347 Alternatively if the /genMode/ is EYE_LINEAR, then 12 values are 4348 accessed and the varying color components are computed: 4349 4350 R = xcoeffs[0] * xe + xcoeffs[1] * ye + xcoeffs[2] * ze + xcoeffs[3] * we 4351 G = xcoeffs[4] * xe + xcoeffs[5] * ye + xcoeffs[6] * ze + xcoeffs[7] * we 4352 B = xcoeffs[8] * xe + xcoeffs[9] * ye + xcoeffs[10] * ze + xcoeffs[11] * we 4353 A = xcoeffs[12] * xe + xcoeffs[13] * ye + xcoeffs[14] * ze + xcoeffs[15] * we 4354 4355 Alternatively if the /genMode/ is CONSTANT, then: 4356 4357 R = xcoeffs[0] 4358 G = xcoeffs[1] 4359 B = xcoeffs[2] 4360 A = xcoeffs[3] 4361 4362 The state required for path color generation for each color (primary 4363 and secondary) is a four-valued integer for the path color generation 4364 mode and 16 floating-point coefficients. The initial mode is NONE 4365 and the coefficients are all initially zero. 4366 4367 As many coefficients are copied by the PathColorGenNV command 4368 to the 16 floating-point coefficient state as are referenced by 4369 the respective generation expression involving /colorFormat/ and 4370 /genMode/; unreferenced coefficients in the array of 16 coefficients 4371 are set to zero. 4372 4373 TEXTURE COORDINATE SET GENERATION FOR PATH COVER COMMANDS 4374 4375 The command 4376 4377 void PathTexGenNV(enum texCoordSet, 4378 enum genMode, 4379 int components, const float *coeffs); 4380 4381 controls how texture coordinate sets are computed for fragment 4382 shading operations that occur as a result of CoverFillPathNV or 4383 CoverStrokePathNV. 4384 4385 /texCoordSet/ must be one of TEXTURE0 through 4386 TEXTUREn where /n/ is one less than the implementation-dependent 4387 value of MAX_TEXTURE_COORDS; otherwise INVALID_ENUM is generated. 4388 4389 /genMode/ must be one of NONE, OBJECT_LINEAR, 4390 PATH_OBJECT_BOUNDING_BOX_NV, or EYE_LINEAR; otherwise INVALID_ENUM 4391 is generated. 4392 4393 /components/ must be 0 if /genMode/ is NONE or for other allowed 4394 /genMode/ values must be one of 1, 2, 3, or 4; otherwise INVALID_VALUE 4395 is generated. /components/ determines how many texture coordinate 4396 components of the texture coordinate set, how many coefficients read 4397 from the /coeffs/ array, and the linear equations used to generate the 4398 s, t, r, and q texture coordinates of the varying texture coordinate 4399 set specified by /texCoordSet/. 4400 4401 In the following equations, coeffs[i] is the /i/th element (base 4402 zero) of the /coeffs/ array; sc, tc, rc, and qa are the s, t, r, 4403 and q texture coordinates of the texture coordinate set indicated 4404 by /texCoordSet/ when the path is covered; and x, y, z, and w are 4405 determined by the /genMode/ in the same manner as PathColorGenNV's 4406 /genMode/. 4407 4408 When /genMode/ is EYE_LINEAR, xcoeffs[i] is the /i/th element (base 4409 zero) of a /xcoeffs/ array generated by multiplying each respective 4410 vector of four elements of coeffs by the current inverse modelview 4411 matrix when PathColorGenNV is called. 4412 4413 xcoeffs[0..3] = coeffs[0..3] * MV^-1 4414 xcoeffs[4..7] = coeffs[4..7] * MV^-1 4415 xcoeffs[8..11] = coeffs[8..11] * MV^-1 4416 xcoeffs[12..15] = coeffs[12..12] * MV^-1 4417 4418 [[ NOTATION: 4419 4420 xxx[0..3] is a vector form from xxx[0], xxx[1], xxx[2], and xxx[3] 4421 4422 MV^-1 is the inverse of the current modelview matrix when PathColorGenNV happens. 4423 4424 ]] 4425 4426 If the /components/ is 0, no values from the /coeffs/ array are 4427 accessed and the s, t, r, and q coordinates of a covered fragment's 4428 varying texture coordinate set for /texCoordSet/ are computed: 4429 4430 s = sc 4431 t = tc 4432 r = rc 4433 q = qc 4434 4435 If the /components/ is 1 and /genMode/ is either OBJECT_LINEAR or 4436 PATH_OBJECT_BOUNDING_BOX_NV, 3 values from the /coeffs/ array are 4437 accessed and the s, t, r, and q coordinates of a covered fragment's 4438 varying texture coordinate set for /texCoordSet/ are computed: 4439 4440 s = coeffs[0] * x + coeffs[1] * y + coeffs[2] 4441 t = tc 4442 r = rc 4443 q = qc 4444 4445 Alternatively if the /genMode/ is EYE_LINEAR, then 4 values are 4446 accessed and the varying texture coordinate set for /texunit/ are 4447 computed: 4448 4449 s = xcoeffs[0] * xe + xcoeffs[1] * ye + xcoeffs[2] * ze + xcoeffs[3] * we 4450 t = tc 4451 r = rc 4452 q = qc 4453 4454 Alternatively if the /genMode/ is CONSTANT, then: 4455 4456 s = xcoeffs[0] 4457 t = tc 4458 r = rc 4459 q = qc 4460 4461 If the /components/ is 2 and /genMode/ is either OBJECT_LINEAR or 4462 PATH_OBJECT_BOUNDING_BOX_NV, 6 values from the /coeffs/ array are accessed and the 4463 s, t, r, and q coordinates of a covered fragment's varying texture 4464 coordinate set for /texCoordSet/ are computed: 4465 4466 s = coeffs[0] * x + coeffs[1] * y + coeffs[2] 4467 t = coeffs[3] * x + coeffs[4] * y + coeffs[5] 4468 r = rc 4469 q = qc 4470 4471 Alternatively if the /genMode/ is EYE_LINEAR, then 8 values are 4472 accessed and the varying texture coordinate set for /texunit/ are 4473 computed: 4474 4475 s = xcoeffs[0] * xe + xcoeffs[1] * ye + xcoeffs[2] * ze + xcoeffs[3] * we 4476 t = xcoeffs[4] * xe + xcoeffs[5] * ye + xcoeffs[6] * ze + xcoeffs[7] * we 4477 r = rc 4478 q = qc 4479 4480 Alternatively if the /genMode/ is CONSTANT, then: 4481 4482 s = xcoeffs[0] 4483 t = xcoeffs[1] 4484 r = rc 4485 q = qc 4486 4487 If the /components/ is 3 and /genMode/ is either OBJECT_LINEAR or 4488 PATH_OBJECT_BOUNDING_BOX_NV, 9 values from the /coeffs/ array are accessed and the 4489 s, t, r, and q coordinates of a covered fragment's varying texture 4490 coordinate set for /texCoordSet/ are computed: 4491 4492 s = coeffs[0] * x + coeffs[1] * y + coeffs[2] 4493 t = coeffs[3] * x + coeffs[4] * y + coeffs[5] 4494 r = coeffs[6] * x + coeffs[7] * y + coeffs[8] 4495 q = qc 4496 4497 Alternatively if the /genMode/ is CONSTANT, then: 4498 4499 s = xcoeffs[0] 4500 t = xcoeffs[1] 4501 r = xcoeffs[2] 4502 q = qc 4503 4504 Alternatively if the /genMode/ is EYE_LINEAR, then 12 values are 4505 accessed and the varying texture coordinate set for /texunit/ are 4506 computed: 4507 4508 s = xcoeffs[0] * xe + xcoeffs[1] * ye + xcoeffs[2] * ze + xcoeffs[3] * we 4509 t = xcoeffs[4] * xe + xcoeffs[5] * ye + xcoeffs[6] * ze + xcoeffs[7] * we 4510 r = xcoeffs[8] * xe + xcoeffs[9] * ye + xcoeffs[10] * ze + xcoeffs[11] * we 4511 q = qc 4512 4513 If the /components/ is 4 and /genMode/ is either OBJECT_LINEAR or 4514 PATH_OBJECT_BOUNDING_BOX_NV, 12 values from the /coeffs/ array are accessed and the 4515 s, t, r, and q coordinates of a covered fragment's varying texture 4516 coordinate set for /texCoordSet/ are computed: 4517 4518 s = coeffs[0] * x + coeffs[1] * y + coeffs[2] 4519 t = coeffs[3] * x + coeffs[4] * y + coeffs[5] 4520 r = coeffs[6] * x + coeffs[7] * y + coeffs[8] 4521 q = coeffs[9] * x + coeffs[10] * y + coeffs[11] 4522 4523 Alternatively if the /genMode/ is EYE_LINEAR, then 16 values are 4524 accessed and the varying texture coordinate set for /texunit/ are 4525 computed: 4526 4527 s = xcoeffs[0] * xe + xcoeffs[1] * ye + xcoeffs[2] * ze + xcoeffs[3] * we 4528 t = xcoeffs[4] * xe + xcoeffs[5] * ye + xcoeffs[6] * ze + xcoeffs[7] * we 4529 r = xcoeffs[8] * xe + xcoeffs[9] * ye + xcoeffs[10] * ze + xcoeffs[11] * we 4530 q = xcoeffs[12] * xe + xcoeffs[13] * ye + xcoeffs[14] * ze + xcoeffs[15] * we 4531 4532 Alternatively if the /genMode/ is CONSTANT, then: 4533 4534 s = xcoeffs[0] 4535 t = xcoeffs[1] 4536 r = xcoeffs[2] 4537 q = xcoeffs[3] 4538 4539 The state required for path color generation for each texture 4540 coordinate set is a four-valued integer for the path texture 4541 coordinate set generation mode and 16 floating-point coefficients. 4542 The initial mode is NONE and the coefficients are all initially zero. 4543 4544 As many coefficients are copied by the PathTexGenNV command to 4545 the 16 floating-point coefficient state as are referenced by the 4546 respective generation expression involving /components/ and /genMode/; 4547 unreferenced coefficients in the array of 16 coefficients are set 4548 to zero. 4549 4550 FOG COORDINATE GENERATION FOR PATH COVER COMMANDS 4551 4552 The command 4553 4554 void PathFogGenNV(enum genMode); 4555 4556 controls how the fog coordinate is computed for fragment 4557 shading operations that occur as a result of CoverFillPathNV or 4558 CoverStrokePathNV. 4559 4560 /genMode/ must be either FOG_COORDINATE or FRAGMENT_DEPTH; otherwise 4561 INVALID_ENUM is generated. 4562 4563 If the /genMode/ is FOG_COORDINATE, then current fog coordinate is 4564 used (without varying) for all fragment generated by covering the 4565 filled or stroked path. 4566 4567 If the /genMode/ is FRAGMENT_DEPTH, then the current fog coordinate 4568 is -ze, the interpolated negated (non-perspective-divided) eye-space 4569 Z coordinate from transforming of path's 2D coordinates transformed 4570 in eye space, so (xe, ye, ze, we) from section 2.12 ("Fixed-Function 4571 Vertex Transformation"). 4572 4573 The state required for path fog generation is a two-valued integer for 4574 the path fog generation mode; the mode is initially FRAGMENT_DEPTH. 4575 4576 5.X.2.3 Instanced Path Stenciling and Covering 4577 4578 Path rendering often depends on rendering a collection of paths at 4579 once. The most common case of this is rendering text as a set of 4580 glyphs corresponding to each character of text. To support this 4581 usage efficiently, GL includes commands for instanced path stenciling 4582 and covering. 4583 4584 The command 4585 4586 void StencilFillPathInstancedNV(sizei numPaths, 4587 enum pathNameType, const void *paths, 4588 uint pathBase, 4589 enum fillMode, uint mask, 4590 enum transformType, 4591 const float *transformValues); 4592 4593 stencils a sequence of filled paths. 4594 4595 The /pathBase/ is an offset added to the /numPaths/ path names read 4596 from the /paths/ array (interpreted based on /pathNameType/). 4597 4598 The /pathNameType/ determines the type of elements of the /paths/ 4599 array and must be one of BYTE, UNSIGNED_BYTE, SHORT, UNSIGNED_SHORT, 4600 INT, UNSIGNED_INT, FLOAT, UTF8_NV, UTF16_NV, 2_BYTES, 3_BYTES, 4601 or 4_BYTES; otherwise the INVALID_ENUM error is generated. 4602 4603 The /transformType/ must be one of NONE, TRANSLATE_X_NV, 4604 TRANSLATE_Y_NV, TRANSLATE_2D_NV, TRANSLATE_3D_NV, AFFINE_2D_NV, 4605 AFFINE_3D_NV, TRANSPOSE_AFFINE_2D_NV, or TRANSPOSE_AFFINE_3D_NV; 4606 otherwise the INVALID_ENUM error is generated. 4607 4608 The /fillMode/ and /mask/ are validated identically to the same-named 4609 parameters of StencilFillPathNV. 4610 4611 The StencilFillPathInstancedNV command is equivalent to: 4612 4613 const float *v = transformValues; 4614 for (int i = 0; i<numPaths; i++) { 4615 double m[16]; 4616 4617 GetDoublev(MODELVIEW_MATRIX, m); // save matrix 4618 v = applyTransformType(transformType, v); 4619 uint pathName; 4620 bool ok = getPathName(pathNameType, paths, pathBase, pathName); 4621 if (!ok) 4622 return; // stop early 4623 if (IsPathNV(pathName)) { 4624 StencilFillPathNV(pathName, fillMode, mask); 4625 } 4626 MatrixLoaddEXT(MODELVIEW, m); // restore matrix 4627 } 4628 4629 assuming these helper functions for applyTransformType and 4630 getPathName: 4631 4632 const float *applyTransformType(enum transformType, const float *v) 4633 { 4634 float m[16]; 4635 switch (transformType) { 4636 case NONE: 4637 break; 4638 case TRANSLATE_X_NV: 4639 MatrixTranslateEXT(MODELVIEW, *v++, 0, 0); 4640 break; 4641 case TRANSLATE_Y_NV: 4642 MatrixTranslateEXT(MODELVIEW, 0, *v++, 0); 4643 break; 4644 case TRANSLATE_2D_NV: 4645 MatrixTranslateEXT(MODELVIEW, *v++, *v++, 0); 4646 break; 4647 case TRANSLATE_3D_NV: 4648 MatrixTranslateEXT(MODELVIEW, *v++, *v++, *v++); 4649 break; 4650 case AFFINE_2D_NV: 4651 m[0] =v[0]; m[4] =v[2]; m[8] =0; m[12]=v[4]; 4652 m[1] =v[1]; m[5] =v[3]; m[9] =0; m[13]=v[5]; 4653 m[2] =0; m[6] =0; m[10]=1; m[14]=0; 4654 m[3] =0; m[7] =0; m[11]=0; m[15]=1; 4655 v += 6; 4656 MatrixMultfEXT(MODELVIEW, m); 4657 break; 4658 case TRANSPOSE_AFFINE_2D_NV: 4659 m[0] =v[0]; m[4] =v[1]; m[8] =0; m[12]=v[2]; 4660 m[1] =v[3]; m[5] =v[4]; m[9] =0; m[13]=v[5]; 4661 m[2] =0; m[6] =0; m[10]=1; m[14]=0; 4662 m[3] =0; m[7] =0; m[11]=0; m[15]=1; 4663 v += 6; 4664 MatrixMultfEXT(MODELVIEW, m); 4665 break; 4666 case AFFINE_3D_NV: 4667 m[0] =v[0]; m[4] =v[3]; m[8] =v[6]; m[12]=v[9]; 4668 m[1] =v[1]; m[5] =v[4]; m[9] =v[7]; m[13]=v[10]; 4669 m[2] =v[2]; m[6] =v[5]; m[10]=v[8]; m[14]=v[11]; 4670 m[3] =0; m[7] =0; m[11]=1; m[15]=0; 4671 v += 12; 4672 MatrixMultfEXT(MODELVIEW, m); 4673 break; 4674 case TRANSPOSE_AFFINE_3D_NV: 4675 m[0] =v[0]; m[4] =v[1]; m[8] =v[2]; m[12]=v[3]; 4676 m[1] =v[4]; m[5] =v[5]; m[9] =v[6]; m[13]=v[7]; 4677 m[2] =v[8]; m[6] =v[9]; m[10]=v[10]; m[14]=v[11]; 4678 m[3] =0; m[7] =0; m[11]=1; m[15]=0; 4679 v += 12; 4680 MatrixMultfEXT(MODELVIEW, m); 4681 break; 4682 default: // generate INVALID_ENUM 4683 } 4684 return v; 4685 } 4686 4687 bool getPathName(enum pathNameType, const void *&paths, 4688 uint pathBase, uint &pathName) 4689 { 4690 switch (pathNameType) { 4691 case BYTE: 4692 { 4693 const byte *p = (const byte*)paths; 4694 pathName = pathBase + p[0]; 4695 paths = p+1; 4696 return true; 4697 } 4698 case UNSIGNED_BYTE: 4699 { 4700 const ubyte *p = (const ubyte*)paths; 4701 pathName = pathBase + p[0]; 4702 paths = p+1; 4703 return true; 4704 } 4705 case SHORT: 4706 { 4707 const short *p = (const short*)paths; 4708 pathName = pathBase + p[0]; 4709 paths = p+1; 4710 return true; 4711 } 4712 case UNSIGNED_SHORT: 4713 { 4714 const ushort *p = (const ushort*)paths; 4715 pathName = pathBase + p[0]; 4716 paths = p+1; 4717 return true; 4718 } 4719 case INT: 4720 { 4721 const int *p = (const int*)paths; 4722 pathName = pathBase + p[0]; 4723 paths = p+1; 4724 return true; 4725 } 4726 case UNSIGNED_INT: 4727 { 4728 const uint *p = (const uint*)paths; 4729 pathName = pathBase + p[0]; 4730 paths = p+1; 4731 return true; 4732 } 4733 case FLOAT: 4734 { 4735 const float *p = (const float*)paths; 4736 pathName = pathBase + p[0]; 4737 paths = p+1; 4738 return true; 4739 } 4740 case 2_BYTES: 4741 { 4742 const ubyte *p = (const ubyte*)paths; 4743 pathName = pathBase + (p[0]<<8 | p[1]); 4744 paths = p+2; 4745 return true; 4746 } 4747 case 3_BYTES: 4748 { 4749 const ubyte *p = (const ubyte*)paths; 4750 pathName = pathBase + (p[0]<<16 | p[1]<<8 | p[0]); 4751 paths = p+3; 4752 return true; 4753 } 4754 case 4_BYTES: 4755 { 4756 const ubyte *p = (const ubyte*)paths; 4757 pathName = pathBase + (p[0]<<24 | p[1]<<16 | p[2]<<8 | p[3]); 4758 paths = p+4; 4759 return true; 4760 } 4761 case UTF8_NV: 4762 { 4763 const ubyte *p = (const ubyte*)paths; 4764 ubyte c0 = p[0]; 4765 if ((c0 & 0x80) == 0x00) { 4766 // Zero continuation (0 to 127) 4767 pathName = pathBase + c0; 4768 p += 1; 4769 } else { 4770 ubyte c1 = p[1]; 4771 if ((c1 & 0xC0) != 0x80) { 4772 // Stop processing the UTF byte sequence early. 4773 return false; 4774 } 4775 if ((c0 & 0xE0) == 0xC0) { 4776 // One contination (128 to 2047) 4777 pathName = pathBase + ((c1 & 0x3F) | (c0 & 0x1F) << 6); 4778 if (pathName < 128) { 4779 return false; 4780 } 4781 p += 2; 4782 } else { 4783 ubyte c2 = p[2]; 4784 if ((c2 & 0xC0) != 0x80) { 4785 // Stop processing the UTF byte sequence early. 4786 return false; 4787 } 4788 if ((c0 & 0xF0) == 0xE0) { 4789 // Two continuation (2048 to 55295 and 57344 to 65535) 4790 pathName = pathBase + ((c2 & 0x3F) | (c1 & 0x3F) << 6 | 4791 (c0 & 0xF) << 12); 4792 if ((pathName >= 55296) && (pathName <= 57343)) { 4793 // Stop processing the UTF byte sequence early. 4794 return false; 4795 } 4796 if (pathName < 2048) { 4797 return false; 4798 } 4799 p += 3; 4800 } else { 4801 ubyte c3 = p[3]; 4802 if ((c3 & 0xC0) != 0x80) { 4803 // Stop processing the UTF byte sequence early. 4804 return false; 4805 } 4806 if ((c0 & 0xF8) == 0xF0) { 4807 // Three continuation (65536 to 1114111) 4808 pathName = pathBase + ((c3 & 0x3F) | (c2 & 0x3F) << 6 | 4809 (c1 & 0x3F) << 12 | (c0 & 0x7) << 18); 4810 if (pathName < 65536 && pathName > 1114111) { 4811 return false; 4812 } 4813 p += 4; 4814 } else { 4815 // Skip invalid or restricted encodings. 4816 // Stop processing the UTF byte sequence early. 4817 return false; 4818 } 4819 } 4820 } 4821 } 4822 paths = p; 4823 return true; 4824 } 4825 case UTF16_NV: 4826 { 4827 const ushort *p = (const ushort*)paths; 4828 4829 ushort s0 = p[0]; 4830 if ((s0 < 0xDB00) || (s0 > 0xDFFF)) { 4831 pathName = pathBase + s0; 4832 p += 1; 4833 } else { 4834 if ((s0 >= 0xDB00) && (s0 <= 0xDBFF)) { 4835 ushort s1 = p[1]; 4836 if ((s1 >= 0xDC00) && (s1 <= 0xDFFF)) { 4837 pathName = pathBase + (((s0 & 0x3FF) << 10 | 4838 (s1 & 0x3FF)) + 0x10000); 4839 p += 2; 4840 } else { 4841 // Stop processing the UTF byte sequence early. 4842 return false; 4843 } 4844 } else { 4845 return false; 4846 } 4847 } 4848 paths = p; 4849 return true; 4850 } 4851 default: 4852 << generate INVALID_ENUM >> 4853 return false; 4854 } 4855 } 4856 4857 The command 4858 4859 void StencilStrokePathInstancedNV(sizei numPaths, 4860 enum pathNameType, const void *paths, 4861 uint pathBase, 4862 int reference, uint mask, 4863 enum transformType, 4864 const float *transformValues); 4865 4866 stencils a sequence of stroked paths and is equivalent to: 4867 4868 const float *v = transformValues; 4869 for (int i = 0; i<numPaths; i++) { 4870 double m[16]; 4871 4872 GetDoublev(MODELVIEW_MATRIX, m); // save matrix 4873 v = applyTransformType(transformType, v); 4874 uint pathName; 4875 bool ok = getPathName(pathNameType, paths, pathBase, pathName); 4876 if (!ok) 4877 return; // stop early 4878 if (IsPathNV(pathName)) { 4879 StencilStrokePathNV(pathName, reference, mask); 4880 } 4881 MatrixLoaddEXT(MODELVIEW, m); // restore matrix 4882 } 4883 4884 assume the helper functions for applyTransformType and 4885 getPathName defined above. 4886 4887 The command 4888 4889 void CoverFillPathInstancedNV(sizei numPaths, 4890 enum pathNameType, const void *paths, 4891 uint pathBase, 4892 enum coverMode, 4893 enum transformType, 4894 const float *transformValues); 4895 4896 covers a sequence of filled paths and is equivalent to: 4897 4898 if (coverMode == BOUNDING_BOX_OF_BOUNDING_BOXES_NV) { 4899 renderBoundingBox(PATH_FILL_BOUNDING_BOX_NV, 4900 numPaths, 4901 pathNameType, paths, 4902 pathBase, 4903 transformType, transformValues); 4904 } else { 4905 const float *v = transformValues; 4906 for (int i = 0; i<numPaths; i++) { 4907 double m[16]; 4908 uint path; 4909 4910 GetDoublev(MODELVIEW_MATRIX, m); // save matrix 4911 v = applyTransformType(transformType, v); 4912 uint pathName; 4913 bool ok = getPathName(pathNameType, paths, pathBase, pathName); 4914 if (!ok) 4915 return; // stop early 4916 if (IsPathNV(pathName)) { 4917 << set fragment shader instance ID to i >> 4918 CoverFillPathNV(pathName, cover); 4919 } 4920 MatrixLoaddEXT(MODELVIEW, m); // restore matrix 4921 } 4922 } 4923 4924 assuming these helper functions for applyTransformType and 4925 getPathName defined above as well as: 4926 4927 void renderBoundingBox(enum boundingBoxType, 4928 sizei numPaths, 4929 enum pathNameType, 4930 const void *paths, 4931 uint pathBase, 4932 enum transformType, 4933 const float *transformValues) 4934 { 4935 boolean hasBounds = FALSE; 4936 float boundsUnion[4], bounds[4]; 4937 4938 const float *v = transformValues; 4939 for (int i = 0; i<numPaths; i++) { 4940 uint pathName; 4941 bool ok = getPathName(pathNameType, paths, pathBase, pathName); 4942 if (!ok) 4943 return; // stop early 4944 if (IsPathNV(pathName)) { 4945 GetPathParameterfvNV(pathName, boundingBoxType, bounds); 4946 switch (transformType) { 4947 case NONE: 4948 break; 4949 case TRANSLATE_X_NV: 4950 bounds[0] += v[0]; 4951 bounds[2] += v[0]; 4952 v += 1; 4953 break; 4954 case TRANSLATE_Y_NV: 4955 bounds[1] += v[0]; 4956 bounds[3] += v[0]; 4957 v += 1; 4958 break; 4959 case TRANSLATE_2D_NV: 4960 bounds[0] += v[0]; 4961 bounds[1] += v[1]; 4962 bounds[2] += v[0]; 4963 bounds[3] += v[1]; 4964 v += 2; 4965 break; 4966 case TRANSLATE_3D_NV: // ignores v[2] 4967 bounds[0] += v[0]; 4968 bounds[1] += v[1]; 4969 bounds[2] += v[0]; 4970 bounds[3] += v[1]; 4971 v += 3; 4972 break; 4973 case AFFINE_2D_NV: 4974 bounds[0] = bounds[0]*v[0] + bounds[0]*v[2] + v[4]; 4975 bounds[1] = bounds[1]*v[1] + bounds[1]*v[3] + v[5]; 4976 bounds[2] = bounds[2]*v[0] + bounds[2]*v[2] + v[4]; 4977 bounds[3] = bounds[3]*v[1] + bounds[3]*v[3] + v[5]; 4978 v += 6; 4979 break; 4980 case TRANSPOSE_AFFINE_2D_NV: 4981 bounds[0] = bounds[0]*v[0] + bounds[0]*v[1] + v[2]; 4982 bounds[1] = bounds[1]*v[3] + bounds[1]*v[4] + v[5]; 4983 bounds[2] = bounds[2]*v[0] + bounds[2]*v[1] + v[2]; 4984 bounds[3] = bounds[3]*v[3] + bounds[3]*v[4] + v[5]; 4985 v += 6; 4986 break; 4987 case AFFINE_3D_NV: // ignores v[2], v[5], v[6..8], v[11] 4988 bounds[0] = bounds[0]*v[0] + bounds[0]*v[3] + v[9]; 4989 bounds[1] = bounds[1]*v[1] + bounds[1]*v[4] + v[10]; 4990 bounds[2] = bounds[2]*v[0] + bounds[2]*v[3] + v[9]; 4991 bounds[3] = bounds[3]*v[1] + bounds[3]*v[4] + v[10]; 4992 v += 12; 4993 break; 4994 case TRANSPOSE_AFFINE_3D_NV: // ignores v[2], v[6], v[8..11] 4995 bounds[0] = bounds[0]*v[0] + bounds[0]*v[1] + v[3]; 4996 bounds[1] = bounds[1]*v[4] + bounds[1]*v[5] + v[7]; 4997 bounds[2] = bounds[2]*v[0] + bounds[2]*v[1] + v[3]; 4998 bounds[3] = bounds[3]*v[4] + bounds[3]*v[5] + v[7]; 4999 v += 12; 5000 break; 5001 default: // generate INVALID_ENUM 5002 } 5003 if (bounds[0] > bounds[2]) { 5004 float t = bounds[2]; 5005 bounds[2] = bounds[0]; 5006 bounds[0] = t; 5007 } 5008 if (bounds[1] > bounds[3]) { 5009 float t = bounds[3]; 5010 bounds[3] = bounds[1]; 5011 bounds[1] = t; 5012 } 5013 if (hasBounds) { 5014 if (bounds[0] < boundsUnion[0]) { 5015 boundsUnion[0] = bounds[0]; 5016 } 5017 if (bounds[1] < boundsUnion[1]) { 5018 boundsUnion[1] = bounds[1]; 5019 } 5020 if (bounds[2] > boundsUnion[2]) { 5021 boundsUnion[2] = bounds[2]; 5022 } 5023 if (bounds[3] > boundsUnion[3]) { 5024 boundsUnion[3] = bounds[3]; 5025 } 5026 } else { 5027 for (int i=0; i<4; i++) { 5028 boundsUnion[i] = bounds[i]; 5029 } 5030 hasBounds = TRUE; 5031 } 5032 } 5033 } 5034 if (hasBounds) { 5035 boolean polygonSmoothEnable = IsEnabled(POLYGON_SMOOTH); 5036 int polygonModes[2]; 5037 GetIntegerv(POLYGON_MODE, polygonModes); 5038 PolygonMode(GL_FRONT_AND_BACK, GL_FILL); 5039 Disable(GL_POLYGON_SMOOTH); 5040 Rectf(boundsUnion[0], boundsUnion[1], boundsUnion[2], boundsUnion[3]); 5041 PolygonMode(FRONT, polygonModes[0]); 5042 PolygonMode(BACK, polygonModes[1]); 5043 if (polygonSmoothEnable) { 5044 Enable(POLYGON_SMOOTH); 5045 } else { 5046 Disable(POLYGON_SMOOTH); 5047 } 5048 } 5049 } 5050 5051 The GetPathParameterfvNV query, used in the code above, is introduced 5052 in section 6.X.1 ("Path Object Parameter Queries"). 5053 5054 The command 5055 5056 void CoverStrokePathInstancedNV(sizei numPaths, 5057 enum pathNameType, const void *paths, 5058 uint pathBase, 5059 enum coverMode, 5060 enum transformType, 5061 const float *transformValues); 5062 5063 covers a sequence of stroked paths and is equivalent to: 5064 5065 if (coverage == BOUNDING_BOX_OF_BOUNDING_BOXES_NV) { 5066 renderBoundingBox(PATH_STROKE_BOUNDING_BOX_NV, 5067 numPaths, 5068 pathNameType, paths, 5069 pathBase, 5070 transformType, transformValues); 5071 } else { 5072 const float *v = transformValues; 5073 for (int i = 0; i<numPaths; i++) { 5074 double m[16]; 5075 5076 GetDoublev(MODELVIEW_MATRIX, m); // save matrix 5077 v = applyTransformType(transformType, v); 5078 uint pathName; 5079 bool ok = getPathName(pathNameType, paths, pathBase, pathName); 5080 if (!ok) 5081 return; // stop early 5082 if (IsPathNV(pathName)) { 5083 << set fragment shader instance ID to i >> 5084 CoverStrokePathNV(pathName, cover); 5085 } 5086 MatrixLoaddEXT(MODELVIEW, m); // restore matrix 5087 } 5088 } 5089 5090 assuming these helper functions for applyTransformType, 5091 getPathName, and renderBoundingBox defined above. 5092 5093 5.X.2.4 Path Stenciling Then Covering 5094 5095 The following command combine the stencil and cover operations on 5096 paths into a single command. 5097 5098 The command 5099 5100 void StencilThenCoverFillPathNV(uint path, enum fillMode, uint mask, enum coverMode); 5101 5102 is equivalent to the two commands 5103 5104 StencilFillPathNV(path, fillMode, mask); 5105 CoverFillPathNV(path, coverMode); 5106 5107 unless either command would generate an error; for any such error 5108 other than OUT_OF_MEMORY, only that error is generated. 5109 5110 The command 5111 5112 void StencilThenCoverStrokePathNV(uint path, int reference, uint mask, enum coverMode); 5113 5114 is equivalent to the two commands 5115 5116 StencilStrokePathNV(uint path, int reference, uint mask); 5117 CoverStrokePathNV(uint path, enum coverMode); 5118 5119 unless either command would generate an error; for any such error 5120 other than OUT_OF_MEMORY, only that error is generated. 5121 5122 The command 5123 5124 void StencilThenCoverFillPathInstancedNV(sizei numPaths, 5125 enum pathNameType, const void *paths, 5126 uint pathBase, 5127 enum fillMode, uint mask, 5128 enum coverMode, 5129 enum transformType, 5130 const float *transformValues); 5131 5132 is equivalent to the two commands 5133 5134 StencilFillPathInstancedNV(sizei numPaths, 5135 enum pathNameType, const void *paths, 5136 uint pathBase, 5137 enum fillMode, uint mask, 5138 enum coverMode, 5139 enum transformType, 5140 const float *transformValues); 5141 CoverFillPathInstancedNV(sizei numPaths, 5142 enum pathNameType, const void *paths, 5143 uint pathBase, 5144 enum fillMode, uint mask, 5145 enum coverMode, 5146 enum transformType, 5147 const float *transformValues); 5148 5149 unless either command would generate an error; for any such error 5150 other than OUT_OF_MEMORY, only that error is generated. 5151 5152 The command 5153 5154 void StencilThenCoverStrokePathInstancedNV(sizei numPaths, 5155 enum pathNameType, const void *paths, 5156 uint pathBase, 5157 int reference, uint mask, 5158 enum coverMode, 5159 enum transformType, 5160 const float *transformValues); 5161 5162 is equivalent to the two commands 5163 5164 StencilStrokePathInstancedNV(sizei numPaths, 5165 enum pathNameType, const void *paths, 5166 uint pathBase, 5167 int reference, uint mask, 5168 enum transformType, 5169 const float *transformValues); 5170 CoverStrokePathInstancedNV(sizei numPaths, 5171 enum pathNameType, const void *paths, 5172 uint pathBase, 5173 enum coverMode, 5174 enum transformType, 5175 const float *transformValues); 5176 5177 unless either command would generate an error; for any such error 5178 other than OUT_OF_MEMORY, only that error is generated. 5179 5180 -- Section 5.4 "Display Lists" 5181 5182 Add to the list of commands not compiled into display lists: 5183 5184 "Path objects: GenPathsNV, DeletePathsNV." 5185 5186Additions to Chapter 6 of the OpenGL 3.2 (unabridged) Specification (State and 5187State Requests) 5188 5189 -- Insert section 6.X "Path Object Queries" after 6.1.18 "Renderbuffer 5190 Object Queries" 5191 5192 6.X. Path Rendering Queries 5193 5194 6.X.1. Path Object Parameter Queries 5195 5196 The queries 5197 5198 void GetPathParameterivNV(uint path, enum pname, int *value); 5199 void GetPathParameterfvNV(uint path, enum pname, float *value); 5200 5201 obtains the current value of the /param/ path parameter of the path 5202 object named /name/; the error INVALID_OPERATION is generated if 5203 /name/ is not an existing path object. /value/ is a pointer to a 5204 scalar or array of the appropriate type, int for GetPathParameterivNV 5205 and float for GetPathParameterfvNV, in which to place the returned 5206 data. 5207 5208 Table 6.readOnlyPathParameters 5209 5210 Name Type Description 5211 --------------------------- ------- ---------------------------- 5212 PATH_COMMAND_COUNT_NV int Length of the path's 5213 command sequence 5214 PATH_COORD_COUNT_NV int Length of the path's 5215 coordinate sequence 5216 PATH_DASH_ARRAY_COUNT_NV int Length of the path's 5217 dash array 5218 PATH_COMPUTED_LENGTH_NV float Computed path-space 5219 length of all the 5220 segments in the path 5221 (see section 6.X.4) 5222 PATH_OBJECT_BOUNDING_BOX_NV 4*float tight path-space bounding 5223 box around the path's 5224 covered fill region 5225 PATH_FILL_BOUNDING_BOX_NV 4*float Conservative path-space 5226 bounding box around the 5227 path's covered fill region 5228 PATH_STROKE_BOUNDING_BOX_NV 4*float Conservative path-space 5229 bounding box around the 5230 path's covered stroke region 5231 5232 /param/ must be one of the tokens listed in Table 5.pathParameters 5233 or Table 6.readOnlyPathParameters; otherwise the INVALID_ENUM 5234 error is generated. The parameters from Table 5.pathParameters 5235 always return a single (scalar) value. The parameters from 5236 Table 6.readOnlyPathParameters a single (scalar) value for all the 5237 parameters but the PATH_*_BOUNDING_BOX_NV parameters; these bounding 5238 box parameters return a vector of 4 values. These four values are 5239 the minimum (x1,y1) corner of the respective path-space bounding 5240 box and the maximum (x2,y2) corner of the respective path-space 5241 orthogonally aligned bounding box, returned in (x1,y1,x2,y2) order. 5242 (This guarantees x1<=x2 and y1<=y2.) Float parameters queried by 5243 GetPathParameterivNV are rounded to the nearest integer (where values 5244 with a floating-point fraction of 0.5 round up). 5245 5246 The PATH_OBJECT_BOUNDING_BOX_NV bounding box is intended to bound 5247 tightly the region of path space containing the path's outline. 5248 The PATH_FILL_BOUNDING_BOX_NV bounding box matches the rectangle 5249 region covered by the CoverFillPathNV command with the BOUNDING_BOX_NV 5250 /coverMode/. With either the PATH_OBJECT_BOUNDING_BOX_NV or 5251 PATH_FILL_BOUNDING_BOX_NV bounding boxes of a path object, a point at 5252 (x,y) such that x<x1 or x>x2 or y<y1 or y>y2 is guaranteed to /not/ 5253 be within the filled outline of the path. 5254 5255 The PATH_STROKE_BOUNDING_BOX_NV bounding box matches the rectangle 5256 region covered by the CoverFillPathNV command with the BOUNDING_BOX_NV 5257 /coverMode/. With the PATH_STROKE_BOUNDING_BOX_NV bounding box of 5258 a path object, a point at (x,y) such that x<x1 or x>x2 or y<y1 or 5259 y>y2 is guaranteed to /not/ be within the stroked region of the path. 5260 5261 6.X.2. Path Object Varying Arrays Queries 5262 5263 Path objects support a variable number of commands, coordinates, 5264 and dash lengths. 5265 5266 The query 5267 5268 void GetPathCommandsNV(uint path, ubyte *commands); 5269 5270 returns the sequence of commands within the path object named /name/ 5271 into the array named /commands/; the error INVALID_OPERATION is 5272 generated if /name/ is not an existing path object. The number of 5273 commands returned is identical to the value of the path object's 5274 PATH_COMMAND_COUNT_NV parameter. The application is responsible 5275 for ensuring /commands/ array has sufficient space. 5276 5277 Any path commands specified with a character alias value (from Table 5278 5.pathCommands) is returned as the command's token value instead. 5279 5280 The query 5281 5282 void GetPathCoordsNV(uint path, float *coords); 5283 5284 returns the sequence of coordinates within the path object named 5285 /name/ into the array named /coords/; the error INVALID_OPERATION 5286 is generated if /name/ is not an existing path object. The number 5287 of commands returned is identical to the value of the path object's 5288 PATH_COORD_COUNT_NV parameter. The application is responsible for 5289 ensuring /coords/ array has sufficient space. 5290 5291 Boolean coordinates such as the large/small and sweep flags for arcs 5292 are always returned as 1.0 or 0.0 for true and false respectively. 5293 Other coordinates are returned as they were specified. 5294 5295 The query 5296 5297 void GetPathDashArrayNV(uint path, float *dashArray); 5298 5299 returns the sequence of dash lengths within the path object named 5300 /name/ into the array named /coords/; the error INVALID_OPERATION is 5301 generated if /name/ is not an existing path object. The number of 5302 dash lengths returned is identical to the value of the path object's 5303 PATH_DASH_ARRAY_COUNT_NV parameter. The application is responsible 5304 for ensuring /dashArray/ has sufficient space. 5305 5306 6.X.3. Path Object Glyph Typographic Queries 5307 5308 GLYPH METRIC QUERIES 5309 5310 To facilitate proper text layout, the command 5311 5312 void GetPathMetricsNV(bitfield metricQueryMask, 5313 sizei numPaths, 5314 enum pathNameType, const void *paths, 5315 uint pathBase, 5316 sizei stride, 5317 float *metrics); 5318 5319 queries glyph metrics associated with a sequence of path objects 5320 specified by the /glyphBase/, /count/, /pathNameType/, and /paths/ 5321 parameters. Metrics are associated with path objects specified by 5322 PathGlyphsNV or PathGlyphRangeNV (see section 5.X.1.3). 5323 5324 There are two kinds of metrics: 5325 5326 * Per-glyph metrics that are typically different for each glyph. 5327 5328 * Per-font face metrics that are identical for all glyphs belonging 5329 to a given font face. 5330 5331 Per-font face metrics are aggregate metrics such as the maximum 5332 ascender or descender for all the glyphs in the font face. 5333 5334 /metricQueryMask/ is a bitfield constructed from the bits listed 5335 in Table 6.perGlyphMetrics and Table 6.perFontFaceMetrics. If a bit 5336 is set in /metricQueryMask/ not listed in these tables, the error 5337 INVALID_VALUE is generated. 5338 5339 /stride/ is the byte (machine units) offset separating each group of 5340 returned metrics for a given path object. If /stride/ is negative 5341 or /stride/ is not a multiple of the size of float in bytes (machine 5342 units), the INVALID_VALUE error is generated. The INVALID_OPERATION 5343 error is generated if /stride/ divided by the size of float in bytes 5344 is not either zero or else greater than or equal to the number of 5345 metrics specified for querying in the metricQueryMask (based on the 5346 number of specified bits specified in the mask) times the size of 5347 float in bytes. A /stride/ of zero is specially handled; the value 5348 zero is interpreted to indicate the number of bytes (machine units) 5349 such that the all the metrics are written in a tightly packed array, 5350 so the size of float in bytes times the number of specified bits in 5351 the /metricQueryMask/ bitfield. 5352 5353 For path objects not created with either PathGlyphsNV or 5354 PathGlyphRangeNV or non-existent, all glyph metrics return -1. 5355 5356 This metric information for a path object is /not/ updated if 5357 the commands or coordinates or parameters of that path object are 5358 changed. 5359 5360 Figure 6.horizontalGlyphMetrics: Horizontal Glyph Metrics 5361 5362 ^ 5363 | xMin xMax 5364 | | | 5365 | | width | 5366 | |<---------->| 5367 | | | 5368 | +============+ - - - - - - - - - - - yMax 5369 | I I ^ ^ 5370 | I I | hBearingY | 5371 | I I | | 5372 hBearingX |---->I GLYPH I | height | 5373 | I OUTLINE I | | 5374 ----O-----I------------I------*---> | 5375 /| I HERE I | | 5376 / | I I | v 5377 origin | +============+ - - -|- - - - - - - - yMin 5378 | | 5379 |------------------------>| 5380 | hAdvance | 5381 5382 Figure 6.verticalGlyphMetrics: Vertical Glyph Metrics 5383 5384 vBearingX 5385 |<---------| origin 5386 | | / 5387 | |/ 5388 ---------------------O-----------------------------> 5389 | | | | 5390 | | vBearingY | | 5391 | | v | 5392 yMax - - +================+ - - - - - - - - | 5393 I | I ^ | 5394 I | I | | 5395 I GLYPH | I | | 5396 I OUTLINE I | height | 5397 I HERE| I | | 5398 I | I | | 5399 I | I | | 5400 I | I v | vAdvance 5401 yMin - - +================+ - - - | 5402 | | | v 5403 | * - - - - - - - - - - - - 5404 | | | 5405 xMin v xMax 5406 5407 Table 6.perGlyphMetrics 5408 5409 Bit number 5410 Glyph from LSB 5411 Bit field name metric tag in bitmask Description (units in path space) 5412 --------------------------------------- ---------- ---------- ------------------------------------------- 5413 GLYPH_WIDTH_BIT_NV width 0 Glyph's width 5414 GLYPH_HEIGHT_BIT_NV height 1 Glyph's height 5415 GLYPH_HORIZONTAL_BEARING_X_BIT_NV hBearingX 2 Left side bearing for horizontal layout 5416 GLYPH_HORIZONTAL_BEARING_Y_BIT_NV hBearingY 3 Top side bearing for horizontal layout 5417 GLYPH_HORIZONTAL_BEARING_ADVANCE_BIT_NV hAdvance 4 Advance width for horizontal layout 5418 GLYPH_VERTICAL_BEARING_X_BIT_NV vBearingX 5 Left side bearing for vertical layout 5419 GLYPH_VERTICAL_BEARING_Y_BIT_NV vBearingY 6 Top side bearing for vertical layout 5420 GLYPH_VERTICAL_BEARING_ADVANCE_BIT_NV vAdvance 7 Advance height for vertical layout 5421 GLYPH_HAS_KERNING_BIT_NV - 8 True if glyph has a kerning table. 5422 5423 Table 6.perFontFaceMetrics 5424 5425 Bit number 5426 from LSB 5427 Bit field name in bitmask Description (units in path space) 5428 --------------------------------------- ---------- --------------------------------------------------- 5429 FONT_X_MIN_BOUNDS_BIT_NV 16 Horizontal minimum (left-most) of the font bounding 5430 box. The font bounding box (this metric and the 5431 next 3) is large enough to contain any glyph from 5432 the font face. 5433 FONT_Y_MIN_BOUNDS_BIT_NV 17 Vertical minimum (bottom-most) of the font bounding 5434 box. 5435 FONT_X_MAX_BOUNDS_BIT_NV 18 Horizontal maximum (right-most) of the font 5436 bounding box. 5437 FONT_Y_MAX_BOUNDS_BIT_NV 19 Vertical maximum (top-most) of the font bounding 5438 box. 5439 FONT_UNITS_PER_EM_BIT_NV 20 Number of units in path space (font units) per 5440 Em square for this font face. This is typically 5441 2048 for TrueType fonts, and 1000 for PostScript 5442 fonts. 5443 FONT_ASCENDER_BIT_NV 21 Typographic ascender of the font face. For font 5444 formats not supplying this information, this value 5445 is the same as FONT_Y_MAX_BOUNDS_BIT_NV. 5446 FONT_DESCENDER_BIT_NV 22 Typographic descender of the font face (always a 5447 positive value). For font formats not supplying 5448 this information, this value is the same as 5449 FONT_Y_MIN_BOUNDS_BIT_NV. 5450 FONT_HEIGHT_BIT_NV 23 Vertical distance between two consecutive baselines 5451 in the font face (always a positive value). 5452 FONT_MAX_ADVANCE_WIDTH_BIT_NV 24 Maximal advance width for all glyphs in this font 5453 face. (Intended to make word wrapping computations 5454 easier.) 5455 FONT_MAX_ADVANCE_HEIGHT_BIT_NV 25 Maximal advance height for all glyphs in this 5456 font face for vertical layout. For font formats 5457 not supplying this information, this value is the 5458 same as FONT_HEIGHT_BIT_NV. 5459 FONT_UNDERLINE_POSITION_BIT_NV 26 Position of the underline line for this font face. 5460 This position is the center of the underling stem. 5461 FONT_UNDERLINE_THICKNESS_BIT_NV 27 Thickness of the underline of this font face. 5462 FONT_HAS_KERNING_BIT_NV 28 True if font face provides a kerning table 5463 FONT_NUM_GLYPH_INDICES_BIT_NV 29 Number of glyph indices for this font. 5464 5465 consulted by the GetPathSpacingNV command discussed below 5466 ("GLYPH SPACING QUERIES"). 5467 5468 The query 5469 5470 void GetPathMetricRangeNV(bitfield metricQueryMask, 5471 uint firstPathName, 5472 sizei numPaths, 5473 sizei stride, 5474 float *metrics); 5475 5476 is equivalent to 5477 5478 int *array = malloc(sizeof(int)*numGlyphs); 5479 if (array) { 5480 for (int i=0; i<numGlyphs; i++) { 5481 array[i] = i + firstPathName; 5482 } 5483 GetPathMetricsNV(metricQueryMask, 5484 numPaths, 5485 INT, array, 5486 pathBase, 5487 stride, metrics); 5488 free(array); 5489 } else { 5490 // generate OUT_OF_MEMORY error 5491 } 5492 5493 GLYPH SPACING QUERIES 5494 5495 The query 5496 5497 void GetPathSpacingNV(enum pathListMode, 5498 sizei numPaths, 5499 enum pathNameType, const void *paths, 5500 uint pathBase, 5501 float advanceScale, 5502 float kerningScale, 5503 enum transformType, 5504 float *returnedSpacing); 5505 5506 returns a sequence of /numPaths/-1 glyph spacing vectors in path 5507 space for spacing the specified sequence of path object pairs. 5508 The returned vectors are written into the /returnedSpacing/ array. 5509 5510 /pathListMode/ must be one of ADJACENT_PAIRS_NV, 5511 ACCUM_ADJACENT_PAIRS_NV, or FIRST_TO_REST_NV; otherwise the 5512 INVALID_ENUM error is generated. 5513 5514 If /numPaths/ is negative, the error INVALID_VALUE is generated 5515 5516 /pathNameType/ determines the type of elements of the /paths/ array 5517 and must be one of BYTE, UNSIGNED_BYTE, SHORT, UNSIGNED_SHORT, INT, 5518 UNSIGNED_INT, FLOAT, UTF8_NV, UTF16_NV, 2_BYTES, 3_BYTES, or 4_BYTES; 5519 otherwise the INVALID_ENUM error is generated. 5520 5521 /transformType/ must be either TRANSLATE_X_NV or TRANSLATE_2D_NV; 5522 otherwise the INVALID_ENUM error is generated. 5523 5524 In the absence of parameter errors, the following pseudo-code 5525 implements this query: 5526 5527 double accumX = 0, 5528 accumY = 0; 5529 float returnX = 0, 5530 returnY = 0; 5531 uint firstPath; 5532 bool ok = getPathName(pathNameType, paths, pathBase, firstPath); 5533 if (!ok) 5534 return; // stop early 5535 for (int i = 0; i<numPaths-1; i++) { 5536 uint secondPath; 5537 bool ok = getPathName(pathNameType, paths, pathBase, secondPath); 5538 if (!ok) 5539 return; // stop early 5540 if (transformType == TRANSLATE_X_NV) { 5541 returnedSpacing[i] = returnX; 5542 } else { 5543 // transformType == TRANSLATE_2D_NV 5544 returnedSpacing[2*i ] = returnX; 5545 returnedSpacing[2*i+1] = returnY; 5546 } 5547 float x = advanceScale * advanceX(firstPath) + 5548 kerningScale * kerningX(firstPath,secondPath); 5549 float y = kerningScale * kerningY(firstPath,secondPath); 5550 if (pathListMode == ACCUM_ADJACENT_PAIRS_NV) { 5551 returnX = accumX; 5552 returnY = accumY; 5553 accumX += x; 5554 accumY += y; 5555 } else { 5556 returnX = x; 5557 returnY = y; 5558 } 5559 if (pathListMode != FIRST_TO_REST_NV) { 5560 firstPath = secondPath; 5561 } 5562 } 5563 5564 The getPathName function is found in section 5.X.2.3 (Instanced Path 5565 Stenciling and Covering). 5566 5567 The advance, kerningX, and kerningY functions operate as follows: 5568 5569 The advance function returns the hAdvance metric of path object 5570 name passed to the function, but if the path object lacks glyph 5571 metrics, the difference between the horizontal bounds of the path 5572 object's bounding box (determined by PATH_OBJECT_BOUNDING_BOX_NV) 5573 are returned instead. If the named path object passed to advance 5574 does not exist, zero is returned. 5575 5576 The kerningX and kerningY functions return the X and Y kerning 5577 distances respectively between the character codes of the first 5578 (typically left) and second (typically right) path objects if they 5579 belong to the same font face; otherwise, zero is returned. If the 5580 vertical kerning metrics are unavailable for the font face or either 5581 named path object does not exist, zero is returned for kerningY. 5582 (When the FONT_HAS_KERNING_BIT_NV or GLYPH_HAS_KERNING_BIT_NV glyph 5583 metrics are false for the first path object name, kerningX and 5584 kerningY must return zero.) 5585 5586 Spacing information (horizontal advance or kerning) in a path object 5587 is not changed if the path's commands, coordinates, or parameters 5588 change--except in the case where the horizontal kerning value is 5589 determined by the first path's object bounding box. 5590 5591 6.X.4. Path Object Geometric Queries 5592 5593 The query 5594 5595 boolean IsPointInFillPathNV(uint path, 5596 uint mask, float x, float y); 5597 5598 computes the winding number of the path-space 2D (x,y) point given 5599 by /x/ and /y/ with respect to the path object named /path/ and 5600 returns TRUE if the winding count ANDed with /mask/ is non-zero; 5601 otherwise the query returns FALSE. If the /mask/ parameter is zero, 5602 substitute the path object's PATH_FILL_MASK_NV parameter value 5603 when ANDing with the winding count. The error INVALID_OPERATION is 5604 generated if /path/ does not exist. 5605 5606 This point-inside computation occurs in /path space/ rather than in 5607 the window space as the StencilFillPathNV command operates. 5608 5609 The query 5610 5611 boolean IsPointInStrokePathNV(uint path, 5612 float x, float y); 5613 5614 returns TRUE if the path-space 2D (x,y) point given by /x/ and 5615 /y/ is within the stroked region of the path object named /path/; 5616 otherwise the query returns FALSE. The error INVALID_OPERATION is 5617 generated if /path/ does not exist. 5618 5619 The stroked region's stroke width is specified by the path object's 5620 stroke width parameter. 5621 5622 The stroked region is defined as in section 5.X.2.1 ("Path 5623 Stenciling") so accounts for the path object's current end cap, 5624 join style, and dashing parameters. 5625 5626 This point-inside computation occurs in /path space/ rather than in 5627 the window space as the StencilStrokePathNV command operates. 5628 5629 The query 5630 5631 float GetPathLengthNV(uint path, 5632 sizei startSegment, sizei numSegments); 5633 5634 returns an approximation of the geometric length of a given portion 5635 of a path object named /path/. The portion of the path measured is 5636 from the (0-indexed) /startSegment/ through the next /numSegments/. 5637 The returned length is measured in path-space units. The error 5638 INVALID_OPERATION is generated if /path/ does not exist. 5639 5640 The geometric length of the path's measured portion depends only 5641 on the path's commands and associated coordinates for the indicated 5642 range of segments and the respective coordinates of these segments. 5643 The geometric length of the path does not, for example, depend on 5644 the path's dashing parameters. 5645 5646 The MOVE_TO_NV and RELATIVE_MOVE_TO_NV commands contribute zero 5647 units to the computed geometric length. For all other path commands, 5648 a path segment's geometric length contribution /s/ is: 5649 5650 s = int(sqrt(fx(t)^2+fy(t)^2), t, 0, 1) 5651 5652 [[ int(f(t),t,a,b) computes the definite integration of the function 5653 f(t) over the interval [a,b]. ]] 5654 5655 where /fx/ and /fy/ is the partial derivative of the command's 5656 respective path segment parametric function found in Table 5657 5.pathCommands. 5658 5659 The return value, assuming no error, is the sum of all /s/ values 5660 for segments /startSegment/ through /startSegment/+/numSegments/-1 5661 inclusive. If /numSegments/ is zero and no error is generated, 5662 0 is returned. 5663 5664 The INVALID_VALUE error is generated in any of the following 5665 circumstances: 5666 5667 * /startSegment/ is negative, 5668 5669 * /numSegments/ is negative, 5670 5671 * /startSegment/+/numSegments/-1 is greater than the index of 5672 the final path segment. 5673 5674 If an error occurs, -1.0 is returned. When no error occurs, the 5675 return value is always non-negative. 5676 5677 If /startSegment/ is zero and /numSegments/ is equal to the 5678 value of /path/'s PATH_COMMAND_COUNT_NV parameter and no error 5679 is generated, the value returned is identical to (equals) the value 5680 returned if GetPathParameterfvNV were used to query the value of 5681 /path/'s PATH_COMPUTED_LENGTH_NV parameter. 5682 5683 The query 5684 5685 boolean PointAlongPathNV(uint path, 5686 sizei startSegment, sizei numSegments, 5687 float distance, 5688 float *x, float *y, 5689 float *tangentX, float *tangentY); 5690 5691 returns the point lying a given distance along a given portion of a 5692 path object specified by /path/ and the unit-length tangent vector 5693 at that point. The boolean return value is TRUE if /distance/ 5694 is within (inclusive) the arc length of the range of segments from 5695 /startSegment/ to /startSegment/+/numSegments/-1; otherwise FALSE 5696 is returned. 5697 5698 The 2D point's (x,y) position is written to the values indicated 5699 by the /x/ and /y/ pointers respectively. The tangent vector is 5700 written to the values indicated by the /tangentX/ and /tangentY/ 5701 points. However if /x/, /y/, /tangentX/, or /tangentY/ is a 5702 NULL pointer, no value is written to such NULL pointers. Only the 5703 subpath consisting of the /numSegments/ path segments beginning with 5704 /startSegment/ (where the initial path segment has index 0) is used. 5705 PointAlongPathNV only considers this subpath. 5706 5707 If /distance/ is less than or equal to zero, the starting point 5708 of the path is used (and the query returns FALSE). If /distance/ 5709 is greater than the path length (i.e., the value returned when the 5710 GetPathLengthNV query is called with the same /startSegment/ and 5711 /numSegments/ parameters), the final point along the subpath is used 5712 (and the query returns FALSE). 5713 5714 The error INVALID_OPERATION is generated if /path/ does not exist. 5715 5716 The error INVALID_VALUE is generated if /startSegment/ 5717 or /numSegments/ are negative. The error INVALID_VALUE is 5718 generated if /startSegment/ is greater than the index of /path/'s 5719 final path segment. The error INVALID_VALUE is generated if 5720 /startSegment/+/numSegments/-1 is less than zero or greater than 5721 the index of /path/'s final path segment. 5722 5723 Because it is not possible in general to compute exact distances along 5724 a path, an implementation is not required to use exact computation 5725 even for segments where such computations are possible. 5726 5727 Implementations are not required to compute distances exactly, as 5728 long as the satisfy the constraint that as /distance/ increases 5729 monotonically the returned point and tangent move forward 5730 monotonically along the path. 5731 5732 Implementations should use the same distance-along-a-path algorithm 5733 for PointAlongPathNV as is used for dashing a stroked path. (The dash 5734 count and dashing array state of the path object is irrelevant to 5735 the results of this query.) 5736 5737 Where an implementation is able to determine that the point being 5738 queried lies exactly at a discontinuity or cusp, the incoming point 5739 and tangent should be returned. 5740 5741 6.X.5. Path Color and Texture Coordinate Generation Queries 5742 5743 The queries 5744 5745 void GetPathColorGenivNV(enum color, enum pname, int *value); 5746 void GetPathColorGenfvNV(enum color, enum pname, float *value); 5747 5748 return path color generation state. /color/ must be one of 5749 PRIMARY_COLOR, PRIMARY_COLOR_NV, SECONDARY_COLOR_NV to return the 5750 requested color generation state for the primary, primary, and 5751 secondary color respectively. /pname/ must be either PATH_GEN_MODE_NV, 5752 PATH_GEN_COLOR_FORMAT_NV, or PATH_GEN_COEFF_NV. 5753 5754 If /pname/ is PATH_GEN_MODE_NV, the scalar value of the respective 5755 color's path generation mode is written to the value referenced by 5756 the /value/ pointer. 5757 5758 If /pname/ is PATH_GEN_COLOR_FORMAT_NV, the scalar value of the 5759 respective color's path generation color format is written to the 5760 value reference by the /value/ pointer. 5761 5762 If /pname/ is PATH_GEN_COEFF_NV, 16 coefficients for the respective 5763 color's path generation are written to the array referenced by the 5764 /value/ pointer. Assuming no error is generated, 16 coefficients 5765 are written no matter what the path color generation mode is though 5766 coefficients not accessed by the indicated path color generation 5767 mode are returned as zero. 5768 5769 The queries 5770 5771 void GetPathTexGenivNV(enum texCoordSet, enum pname, int *value); 5772 void GetPathTexGenfvNV(enum texCoordSet, enum pname, float *value); 5773 5774 return path texture coordinate set generation state. /texCoordSet/ 5775 indicates the texture coordinate set being queried and must be 5776 one of TEXTURE0 through TEXTUREn where /n/ is one less than the 5777 implementation-dependent value of MAX_TEXTURE_COORDS; otherwise 5778 INVALID_ENUM is generated. /pname/ must be either PATH_GEN_MODE_NV 5779 PATH_GEN_COMPONENTS_NV, or PATH_GEN_COEFF_NV. 5780 5781 If /pname/ is PATH_GEN_MODE_NV, the scalar value of the respective 5782 texture coordinate set's path generation mode is written to the 5783 value referenced by the /value/ pointer. 5784 5785 If /pname/ is PATH_GEN_COMPONENTS_NV, the scalar value of the 5786 respective texture coordinate set's path generation number of 5787 components is written to the value reference by the /value/ pointer. 5788 5789 If /pname/ is PATH_GEN_COEFF_NV, 16 coefficients for the respective 5790 texture coordinate set's path generation are written to the array 5791 referenced by the /value/ pointer. Assuming no error is generated, 16 5792 coefficients are written no matter what the path texture generation 5793 mode is though coefficients not accessed by the indicated path 5794 texture generation mode are returned as zero. 5795 5796Additions to the AGL/GLX/WGL Specifications 5797 5798 Path objects are shared between AGL/GLX/WGL rendering contexts if 5799 and only if the rendering contexts share display lists. No change 5800 is made to the AGL/GLX/WGL API. 5801 5802 Changes to path objects shared between multiple rendering contexts 5803 will be serialized (i.e., the changes, queries, deletions, and 5804 stencil/cover operations will occur in a specific order). 5805 5806Additions to the OpenGL Shading Language 5807 5808 None 5809 5810GLX Protocol 5811 5812 XXX 5813 5814Errors 5815 5816 XXX 5817 5818Dependencies on ARB_program_interface_query. 5819 5820 When ARB_program_interface_query is not supported, all references to 5821 FRAGMENT_INPUT_NV and ProgramPathFragmentInputGenNV should be ignored. 5822 5823Dependencies on Core Profile and OpenGL ES 5824 5825 When NV_path_rendering is advertised, the following functionality 5826 must be supported... 5827 5828 References to the following commands should be ignored: 5829 5830 PathColorGenNV 5831 PathTexGenNV 5832 PathFogGenNV 5833 GetPathColorGenivNV 5834 GetPathColorGenfvNV 5835 GetPathTexGenivNV 5836 GetPathTexGenfvNV 5837 5838 including the state set and queried by these commands. 5839 5840 References to the following tokens should be ignored: 5841 5842 PATH_FOG_GEN_MODE_NV 5843 PRIMARY_COLOR 5844 PRIMARY_COLOR_NV 5845 SECONDARY_COLOR_NV 5846 PATH_GEN_COLOR_FORMAT_NV 5847 5848 References to the following GLSL built-in variables should be ignored: 5849 5850 gl_TexCoord 5851 gl_MaxTextureCoords 5852 gl_Color 5853 gl_FrontColor 5854 gl_BackColor 5855 gl_SecondaryColor 5856 gl_FrontSecondaryColor 5857 gl_BackSecondaryColor 5858 gl_FogFragCoord 5859 5860 The following types are defined as alias to the GL tokens: 5861 5862 2_BYTES_NV 0x1407 // from GL compat 5863 3_BYTES_NV 0x1408 // from GL compat 5864 4_BYTES_NV 0x1409 // from GL compat 5865 EYE_LINEAR_NV 0x2400 // from GL compat 5866 OBJECT_LINEAR_NV 0x2401 // from GL compat 5867 CONSTANT_NV 0x8576 // from GL compat 5868 5869 The following entry points (specified by the EXT_direct_state_access 5870 extension) MUST be supported: 5871 5872 void MatrixLoadfEXT(enum matrixMode, const float *m); 5873 void MatrixLoaddEXT(enum matrixMode, const double *m); 5874 5875 void MatrixMultfEXT(enum matrixMode, const float *m); 5876 void MatrixMultdEXT(enum matrixMode, const double *m); 5877 5878 void MatrixLoadTransposefEXT(enum matrixMode, const float *m); 5879 void MatrixLoadTransposedEXT(enum matrixMode, const float *m); 5880 5881 void MatrixMultTransposefEXT(enum matrixMode, const float *m); 5882 void MatrixMultTransposedEXT(enum matrixMode, const float *m); 5883 5884 void MatrixLoadIdentityEXT(enum matrixMode); 5885 5886 void MatrixRotatefEXT(enum matrixMode, float angle, 5887 float x, float y, float z); 5888 void MatrixRotatedEXT(enum matrixMode, double angle, 5889 double x, double y, double z); 5890 5891 void MatrixScalefEXT(enum matrixMode, 5892 float x, float y, float z); 5893 void MatrixScaledEXT(enum matrixMode, 5894 double x, double y, double z); 5895 5896 void MatrixTranslatefEXT(enum matrixMode, 5897 float x, float y, float z); 5898 void MatrixTranslatedEXT(enum matrixMode, 5899 double x, double y, double z); 5900 5901 void MatrixOrthoEXT(enum matrixMode, double l, double r, 5902 double b, double t, double n, double f); 5903 void MatrixFrustumEXT(enum matrixMode, double l, double r, 5904 double b, double t, double n, double f); 5905 5906 void MatrixPushEXT(enum matrixMode); 5907 void MatrixPopEXT(enum matrixMode); 5908 5909 These commands must support the PATH_PROJECTION_NV and PATH_MODELVIEW_NV 5910 tokens for matrixMode. The associated modelview and projection matrix 5911 state, including matrix stacks, MUST be supported. These token values 5912 for matrices are supported: 5913 5914 PATH_PROJECTION_NV 0x1701 5915 PATH_MODELVIEW_NV 0x1700 5916 5917 PATH_MODELVIEW_STACK_DEPTH_NV 0x0BA3 5918 PATH_MODELVIEW_MATRIX_NV 0x0BA6 5919 PATH_MAX_MODELVIEW_STACK_DEPTH_NV 0x0D36 5920 PATH_TRANSPOSE_MODELVIEW_MATRIX_NV 0x84E3 5921 PATH_PROJECTION_STACK_DEPTH_NV 0x0BA4 5922 PATH_PROJECTION_MATRIX_NV 0x0BA7 5923 PATH_MAX_PROJECTION_STACK_DEPTH_NV 0x0D38 5924 PATH_TRANSPOSE_PROJECTION_MATRIX_NV 0x84E4 5925 5926 The last 8 tokens are supported by GetFloatv, GetIntegerv, GetDoublev 5927 to query associated path modelview and projection state. 5928 5929 The values of sc, tc, rc, and qc discussed in section 5.X.2.2 "Path 5930 Covering" are always zero in a Core profile context as these values 5931 involve deprecated state. 5932 5933New State 5934 5935 -- NEW table 6.X, "Path (state per context)" following Table 6.33, "Renderbuffer" 5936 5937 Get Value Type Get Command Initial Value Description Section Attribute 5938 ----------------------------------- ------- ------------------- -------------- ------------------------ ------------ -------------- 5939 PATH_GEN_MODE_NV 2xZ4 GetPathColorGenivNV NONE path's color 6.X.5 lighting 5940 generation mode 5941 PATH_GEN_COLOR_FORMAT_NV 2xZ6 GetPathColorGenivNV NONE path's color 6.X.5 lighting 5942 generation color format 5943 PATH_GEN_COEFF_NV 2x16xR GetPathColorGenfvNV all 0's path's color gen mode 6.X.5 lighting 5944 generation coefficients 5945 PATH_GEN_MODE_NV nxZ4 GetPathTexGenivNV NONE path's texture 6.X.5 texture 5946 generation mode 5947 PATH_GEN_COMPONENTS_NV nxZ5 GetPathTexGenivNV 0 path's texture 6.X.5 texture 5948 generation number of 5949 components 5950 PATH_GEN_COEFF_NV nx16xR GetPathTexGenfvNV all 0's path's texture 6.X.5 texture 5951 generation coefficients 5952 PATH_FOG_GEN_MODE_NV Z2 GetIntegerv FRAGMENT_DEPTH path's fog generation 5.X.2.1 fog 5953 mode 5954 PATH_ERROR_POSITION_NV Z GetIntegerv -1 last path string 5.X.1.2 - 5955 error position 5956 PATH_STENCIL_FUNC_NV Z8 GetIntegerv ALWAYS path stenciling function 5.X.2.1 stencil-buffer 5957 PATH_STENCIL_REF_NV Z+ GetIntegerv 0 path stenciling 5.X.2.1 stencil-buffer 5958 reference value 5959 PATH_STENCIL_VALUE_MASK_NV Z+ GetIntegerv 1's path stencil read mask 5.X.2.1 stencil-buffer 5960 PATH_STENCIL_DEPTH_OFFSET_FACTOR_NV R GetFloatv 0 path stencil depth 5.X.2.1 polygon 5961 offset factor 5962 PATH_STENCIL_DEPTH_OFFSET_UNITS_NV R GetFloatv 0 path stencil depth 5.X.2.1 polygon 5963 units factor 5964 PATH_COVER_DEPTH_FUNC_NV Z8 GetIntegerv LESS path covering depth 5.X.2.2 depth-buffer 5965 function 5966 5967 where n is the implementation-dependent number of texture coordinate 5968 sets (MAX_TEXTURE_COORDS). 5969 5970 -- NEW table 6.Y, "Path (state per path object)" following Table 6.X 5971 5972 Get Value Type Get Command Initial Value Description Section Attribute 5973 ------------------------------- ------- -------------------- -------------------- -------------------------------- ------------ --------- 5974 - nxZ8* GetPathCommandsNV - path's sequence of path commands 6.X.1 - 5975 - mxR GetPathCoordsNV - path's sequence of path 6.X.1 - 5976 coordinates 5977 - cxR GetPathDashArrayNV - dash array contents 5.X.1.5 - 5978 PATH_COMMAND_COUNT_NV Z+ GetPathParameterivNV - path's count of path commands 6.X.1 - 5979 PATH_COORD_COUNT_NV Z+ GetPathParameterivNV - path's count of path coordinates 6.X.1 - 5980 PATH_COMPUTED_LENGTH_NV R+ GetPathParameterfvNV - GL's calculation of the path's 6.X.1 - 5981 length 5982 PATH_STROKE_WIDTH_NV R+ GetPathParameterfvNV 1.0 stroke width 5.X.1.5 - 5983 PATH_INITIAL_END_CAP_NV Z4 GetPathParameterivNV FLAT path's initial end cap style 5.X.1.5 - 5984 PATH_TERMINAL_END_CAP_NV Z4 GetPathParameterivNV FLAT path's terminal end cap style 5.X.1.5 - 5985 PATH_JOIN_STYLE_NV Z4 GetPathParameterivNV MITER_REVERT_NV path's join style 5.X.1.5 - 5986 PATH_MITER_LIMIT_NV R+ GetPathParameterfvNV 4 path's miter limit 5.X.1.5 - 5987 PATH_DASH_ARRAY_COUNT_NV Z+ GetPathParameterivNV 0 path's count of dashes in the 5.X.1.5 - 5988 path's dash array 5.X.1.5 - 5989 PATH_DASH_OFFSET_NV R GetPathParameterfvNV 0.0 path's dash offset 5.X.1.5 - 5990 PATH_DASH_OFFSET_RESET_NV Z2 GetPathParameterivNV MOVE_TO_CONTINUES_NV path's dash offset reset 5.X.1.5 - 5991 PATH_CLIENT_LENGTH_NV R+ GetPathParameterfvNV 0.0 the client-supplied calculation 5.X.1.5 - 5992 of the path's length 5993 PATH_INITIAL_DASH_CAP_NV Z4 GetPathParameterivNV FLAT path's initial dash cap style 5.X.1.5 - 5994 PATH_TERMINAL_DASH_CAP_NV Z4 GetPathParameterivNV FLAT path's terminal dash cap style 5.X.1.5 - 5995 PATH_FILL_MODE_NV Z3 GetPathParameterivNV COUNT_UP_NV path's default fill mode 5.X.1.5 - 5996 PATH_FILL_MASK_NV Z+ GetPathParameterivNV all 1's path's default fill mask 5.X.1.5 - 5997 PATH_FILL_COVER_MODE_NV Z4 GetPathParameterivNV CONVEX_HULL_NV path's default fill cover mode 5.X.1.5 - 5998 PATH_STROKE_COVER_MODE_NV Z4 GetPathParameterivNV CONVEX_HULL_NV path's default stroke cover mode 5.X.1.5 - 5999 PATH_STROKE_MASK_NV Z+ GetPathParameterivNV all 1's path's default stroke mask 5.X.1.5 - 6000 PATH_STROKE_BOUND_NV R[0,1] GetPathParameterfvNV 0.2 (20%) path's stroke approximation 5.X.1.5 - 6001 bound 6002 PATH_OBJECT_BOUNDING_BOX_NV R4 GetPathParameterfvNV - path's outline bounding box 6.X.1 - 6003 PATH_FILL_BOUNDING_BOX_NV R4 GetPathParameterfvNV - path's fill bounding box 6.X.1 - 6004 PATH_STROKE_BOUNDING_BOX_NV R4 GetPathParameterfvNV - path's stroke bounding box 6.X.1 - 6005 6006 where n is the number of commands in a path object, m is the number 6007 of coordinates in a path object, and c is the dash array count of 6008 a path object. 6009 6010 -- NEW table 6.Z, "Path Glyph Metrics (state per path object)" following Table 6.Z 6011 6012 Get Value Type Get Command Initial Value Description Section Attribute 6013 --------------------------------------- ------- --------------------- ------------- --------------------------- ------------ --------- 6014 GLYPH_WIDTH_BIT_NV R GetPathMetricsNV see 5.X.1.3 path's glyph width 6.X.3 - 6015 GLYPH_HEIGHT_BIT_NV R GetPathMetricsNV see 5.X.1.3 path's glyph height 6.X.3 - 6016 GLYPH_HORIZONTAL_BEARING_X_BIT_NV R GetPathMetricsNV see 5.X.1.3 path's glyph left side bearing 6.X.3 - 6017 for horizontal layout 6018 GLYPH_HORIZONTAL_BEARING_Y_BIT_NV R GetPathMetricsNV see 5.X.1.3 path's glyph top side bearing 6.X.3 - 6019 for horizontal layout 6020 GLYPH_HORIZONTAL_BEARING_ADVANCE_BIT_NV R GetPathMetricsNV see 5.X.1.3 path's glyph advance width 6.X.3 - 6021 for horizontal layout 6022 GLYPH_VERTICAL_BEARING_X_BIT_NV R GetPathMetricsNV see 5.X.1.3 path's glyph left side bearing 6.X.3 - 6023 for vertical layout 6024 GLYPH_VERTICAL_BEARING_Y_BIT_NV R GetPathMetricsNV see 5.X.1.3 path's glyph top side bearing 6.X.3 - 6025 for vertical layout 6026 GLYPH_VERTICAL_BEARING_ADVANCE_BIT_NV R GetPathMetricsNV see 5.X.1.3 path's glyph advance width 6.X.3 - 6027 for vertical layout 6028 GLYPH_HAS_KERNING_BIT_NV B GetPathMetricsNV see 5.X.1.3 whether or not glyph has kerning 6.X.3 - 6029 table 6030 6031 -- NEW table 6.W, "Path Font Metrics (state per path object though identical for glyphs from the same font face)" following Table 6.Z 6032 6033 Get Value Type Get Command Initial Value Description Section Attribute 6034 ------------------------------- ------- ---------------- ------------- --------------------------------------- ------------ --------- 6035 FONT_X_MIN_BOUNDS_BIT_NV R GetPathMetricsNV see 5.X.1.3 path's horizontal minimum (left-most) 6.X.3 - 6036 of the font bounding box 6037 FONT_Y_MIN_BOUNDS_BIT_NV R GetPathMetricsNV see 5.X.1.3 path's vertical minimum (bottom-most) 6.X.3 - 6038 of the font bounding box 6039 FONT_X_MAX_BOUNDS_BIT_NV R GetPathMetricsNV see 5.X.1.3 path's horizontal maximum (right-most) 6.X.3 - 6040 of the font bounding box 6041 FONT_Y_MAX_BOUNDS_BIT_NV R GetPathMetricsNV see 5.X.1.3 path's vertical maximum (top-most) 6.X.3 - 6042 of the font bounding box 6043 FONT_UNITS_PER_EM_BIT_NV R GetPathMetricsNV see 5.X.1.3 path's number of units in path space 6.X.3 - 6044 (font units) per Em square for font 6045 face 6046 FONT_ASCENDER_BIT_NV R GetPathMetricsNV see 5.X.1.3 path's typographical ascender (in font 6.X.3 - 6047 units) of the font face 6048 FONT_DESCENDER_BIT_NV R GetPathMetricsNV see 5.X.1.3 path's typographical descender (in font 6.X.3 - 6049 units) of the font face 6050 FONT_HEIGHT_BIT_NV R+ GetPathMetricsNV see 5.X.1.3 path's font face vertical distance 6.X.3 - 6051 between two consecutive baselines 6052 (in font units) 6053 FONT_MAX_ADVANCE_WIDTH_BIT_NV R GetPathMetricsNV see 5.X.1.3 path's maximal advance width (in font 6.X.3 - 6054 units) for all glyphs in font face 6055 FONT_MAX_ADVANCE_HEIGHT_BIT_NV R GetPathMetricsNV see 5.X.1.3 path's maximal advance height (in font 6.X.3 - 6056 units) for all glyphs in font face 6057 for vertical layout 6058 FONT_UNDERLINE_POSITION_BIT_NV R GetPathMetricsNV see 5.X.1.3 path's position (in font units) of the 6.X.3 - 6059 center of underline line for font face 6060 FONT_UNDERLINE_THICKNESS_BIT_NV R GetPathMetricsNV see 5.X.1.3 thickness (in font units) of the 6.X.3 - 6061 underline for font face 6062 FONT_HAS_KERNING_BIT_NV B GetPathMetricsNV see 5.X.1.3 whether or not glyph has kerning 6.X.3 - 6063 table 6064 FONT_NUM_GLYPH_INDICES_BIT_NV Z+ GetPathMetricsNV see 5.X.1.3 number of glyph indices in font face 6.X.3 - 6065 6066 Increment "n" in the Type field of the "Program Interface State" 6067 table by 1 to correspond to the FRAGMENT_INPUT_NV program interface. 6068 6069 Add the following rows to the table labeled "Program Object Resource 6070 State" (only fragment input resources support this state): 6071 6072 Initial 6073 Get Value Type Get Command Value Description Sec. 6074 ---------------------- ---- -------------------- --------- ------------------------------------------- ----- 6075 PATH_GEN_MODE_NV Z4 GetProgramResourceiv NONE Path fragment input generation mode 6076 PATH_GEN_COMPONENTS_NV Z5 GetProgramResourceiv 0 Number of path fragment input components 6077 PATH_GEN_COEFF_NV 16*R GetProgramResourceiv all zeros Path fragment input generation coefficients 6078 6079New Implementation Dependent State 6080 6081 None 6082 6083NVIDIA Implementation Details 6084 6085 -- API revision 1.0 6086 6087 Released in NVIDIA Driver Release 275.33 (June 2011). 6088 6089 -- API revision 1.1 6090 6091 Follow-on release (circa September 2011) adds these path 6092 commands for ISO PDF 32000 support: 6093 6094 GL_RESTART_PATH_NV 6095 GL_DUP_FIRST_CUBIC_CURVE_TO_NV 6096 GL_DUP_LAST_CUBIC_CURVE_TO_NV 6097 GL_RECT_NV 6098 6099 These path commands are not operational (generate GL_INVALID_ENUM 6100 errors) if used in 275.xx or 280.xx drivers. 6101 6102 Follow-on release (circa September 2011) adds these transformType 6103 parameters: 6104 6105 GL_NONE 6106 GL_TRANSLATE_3D_NV 6107 GL_AFFINE_3D_NV 6108 GL_TRANSPOSE_AFFINE_3D_NV 6109 6110 These transformType tokens are not operational (generate 6111 GL_INVALID_ENUM errors) if used in 275.xx or 280.xx drivers. 6112 6113 -- API revision 1.2 6114 6115 Follow-on release (circa December 2013) adding these commands: 6116 6117 void glMatrixLoad3x2fNV(GLenum matrixMode, const GLfloat *m); 6118 void glMatrixLoad3x3fNV(GLenum matrixMode, const GLfloat *m); 6119 void glMatrixLoadTranspose3x3fNV(GLenum matrixMode, const GLfloat *m); 6120 6121 void glMatrixMult3x2fNV(GLenum matrixMode, const GLfloat *m); 6122 void glMatrixMult3x3fNV(GLenum matrixMode, const GLfloat *m); 6123 void glMatrixMultTranspose3x3fNV(GLenum matrixMode, const GLfloat *m); 6124 6125 void glStencilThenCoverFillPathNV(GLuint path, GLenum fillMode, 6126 GLuint mask, GLenum coverMode); 6127 void glStencilThenCoverStrokePathNV(GLuint path, GLint reference, 6128 GLuint mask, GLenum coverMode); 6129 void glStencilThenCoverFillPathInstancedNV(GLsizei numPaths, 6130 GLenum pathNameType, 6131 const void *paths, 6132 GLuint pathBase, 6133 GLenum fillMode, uint mask, 6134 GLenum coverMode, 6135 GLenum transformType, 6136 const GLfloat *transformValues); 6137 void glStencilThenCoverStrokePathInstancedNV(GLsizei numPaths, 6138 GLenum pathNameType, 6139 const void *paths, 6140 GLuint pathBase, 6141 GLint reference, uint mask, 6142 GLenum coverMode, 6143 GLenum transformType, 6144 const GLfloat *transformValues); 6145 enum glPathGlyphIndexRangeNV(GLenum fontTarget, 6146 const void *fontName, 6147 GLbitfield fontStyle, 6148 GLuint pathParameterTemplate, 6149 GLfloat emScale, 6150 GLuint baseAndCount[2]); 6151 6152 If the window system's GetProcAddress mechanism for GL commands returns 6153 NULL for these function names, these API revision 1.2 features are 6154 not available. Likewise the these tokens are not supported either. 6155 6156 GL_ROUNDED_RECT_NV 6157 GL_RELATIVE_ROUNDED_RECT_NV 6158 GL_ROUNDED_RECT2_NV 6159 GL_RELATIVE_ROUNDED_RECT2_NV 6160 GL_ROUNDED_RECT4_NV 6161 GL_RELATIVE_ROUNDED_RECT4_NV 6162 GL_ROUNDED_RECT8_NV 6163 GL_RELATIVE_ROUNDED_RECT8_NV 6164 GL_RELATIVE_RECT_NV 6165 6166 These tokens may be returned by glPathGlyphIndexRangeNV: 6167 6168 GL_FONT_GLYPHS_AVAILABLE_NV 6169 GL_FONT_TARGET_UNAVAILABLE_NV 6170 GL_FONT_UNAVAILABLE_NV 6171 GL_FONT_UNINTELLIGIBLE_NV 6172 6173 -- API revision 1.3 6174 6175 Follow-on release (circa May 2014, first appearing in the 337.88 6176 drivers) adding these commands: 6177 6178 These new path commands: 6179 6180 GL_CONIC_CURVE_TO_NV 6181 GL_RELATIVE_CONIC_CURVE_TO_NV 6182 GL_RELATIVE_RECT_NV 6183 6184 New path glyph metric query: 6185 6186 GL_FONT_NUM_GLYPH_INDICES_BIT_NV 6187 6188 New return values from glyph index path specification commands: 6189 6190 GL_FONT_UNINTELLIGIBLE_NV 6191 GL_STANDARD_FONT_FORMAT_NV 6192 6193 New programInferface token: 6194 6195 FRAGMENT_INPUT_NV 6196 6197 New (aliased) matrix tokens for ES support: 6198 6199 PATH_PROJECTION_NV 6200 PATH_MODELVIEW_NV 6201 6202 PATH_MODELVIEW_STACK_DEPTH_NV 6203 PATH_MODELVIEW_MATRIX_NV 6204 PATH_MAX_MODELVIEW_STACK_DEPTH_NV 6205 PATH_TRANSPOSE_MODELVIEW_MATRIX_NV 6206 PATH_PROJECTION_STACK_DEPTH_NV 6207 PATH_PROJECTION_MATRIX_NV 6208 PATH_MAX_PROJECTION_STACK_DEPTH_NV 6209 PATH_TRANSPOSE_PROJECTION_MATRIX_NV 6210 6211 New glyph index path specification commands: 6212 6213 enum glPathGlyphIndexArrayNV(GLuint firstPathName, 6214 GLenum fontTarget, 6215 const void *fontName, 6216 GLbitfield fontStyle, 6217 GLuint firstGlyphIndex, 6218 GLsizei numGlyphs, 6219 GLuint pathParameterTemplate, 6220 GLfloat emScale); 6221 enum glPathMemoryGlyphIndexArrayNV(GLuint firstPathName, 6222 GLenum fontTarget, 6223 GLsizeiptr fontSize, 6224 const void *fontData, 6225 GLsizei faceIndex, 6226 GLuint firstGlyphIndex, 6227 GLsizei numGlyphs, 6228 GLuint pathParameterTemplate, 6229 GLfloat emScale); 6230 6231 GLSL-related commands: 6232 6233 void glProgramPathFragmentInputGenNV(GLuint program, 6234 GLint location, 6235 GLenum genMode, 6236 GLint components, 6237 const GLfloat *coeffs); 6238 6239 void glGetProgramResourcefvNV(GLuint program, GLenum programInterface, 6240 GLuint index, GLsizei propCount, 6241 const GLenum *props, GLsizei bufSize, 6242 GLsizei *length, GLfloat *params); 6243 6244 If the window system's GetProcAddress mechanism for GL commands returns 6245 NULL for these function names, these API revision 1.3 features are 6246 not available. Likewise the these tokens are not supported either. 6247 6248 -- Performance improvements: 6249 6250 Release 304.xx and on substantially improves the performance of 6251 path rendering stencil and cover operations on NVIDIA Fermi- and 6252 Kepler-based GPUs (GeForce 400 Series and on). 6253 6254 Release 314.xx improves the performance of initially specifying or 6255 modifying a path object prior to stenciling or covering the paths. 6256 6257 -- Bugs: 6258 6259 Due to NVIDIA driver bug 1315267, path objects were not actually 6260 shared among contexts prior to Driver release 320.xx (July 2013). 6261 6262Issues 6263 6264 1. What should this extension be called? 6265 6266 RESOLVED: NV_path_rendering 6267 6268 The extension adds an entirely new rendering paradigm for filled 6269 and stroked paths, hence "path rendering". 6270 6271 "path" alone was considered but deemed to vague. 6272 6273 2. Should this extension support specifying paths based on glyphs in fonts? 6274 6275 RESOLVED: Yes. 6276 6277 There are several problems solved by including first-class path 6278 specification via glyphs in fonts. 6279 6280 1) Support for glyphs from fonts are an expected part of nearly 6281 all path rendering systems. Not including glyph support will force 6282 all path rendering applications to build their own glyph system. 6283 6284 2) Fonts, particularly for Asian languages, can be large. 6285 By putting glyph specification from fonts directly into 6286 the extension, implementations will have the opportunity to 6287 cache commonly loaded font glyphs, including shared on-GPU 6288 representations. 6289 6290 3) Also because fonts have many glyphs, first-pass specification 6291 of a range of glyphs allows the GL implementation to load glyphs 6292 sparsely in response to use. It isn't appropriate to burden 6293 applications with the burden of properly caching large sets of 6294 glyphs from fonts. So while Unicode glyphs 0 through 2^21-1 6295 might be loaded for an entire Unicode font, the GL implementation 6296 could only actually load queried and used path objects. 6297 6298 4) Locating font files tends to be very system-specific. To the 6299 extent OpenGL supports cross-platform rendering, minimizing 6300 system-specific aspects of rendering increases the cross-platform 6301 nature of OpenGL applications. 6302 6303 5) I still feel bad about glutBitmapCharacter and 6304 glutStrokeCharacter being so lame; I thought something better 6305 would take their place but nothing has. 6306 6307 3. Should this extension provide a one-shot (single-pass) way to fill 6308 and stroke path objects? 6309 6310 RESOLVED: No. 6311 6312 The two-pass decoupling of path rendering into stenciling and 6313 covering operations has lots of advantages. 6314 6315 Some of the advantages are: 6316 6317 1) The cover step has complete control over how the fragment 6318 shader is configured. GLSL, assembly, or fixed-function 6319 (glTexEnv, glFog, etc.) fragment shading can all be used 6320 without conflating the path's coverage determination with 6321 the shading. 6322 6323 1a) If shading resources are used to implement the path coverage 6324 determination such as interpolants or textures, these 6325 resources aren't over-subscribed as could occur in a 6326 one-step API. 6327 6328 2) GPUs can accelerate stencil-only rendering during the stencil 6329 step in ways that are rasterization and bandwidth efficient. 6330 6331 3) Path rendering standards all allow a rendered path to be clipped 6332 by another arbitrary (clipping) path. This can even be 6333 done recursively sometimes. When the stencil coverage 6334 determination is a separate step from the shading, such 6335 clipping operations are easy to accomplish as simply multiple 6336 stenciled stencil steps. Otherwise clipping a path to another 6337 path is a complex intersection and re-tessellation task. 6338 6339 4) A two-step stencil, then cover" approach makes it 6340 straightforward to guarantee that pixels and samples are 6341 only visited once per path rendering as path rendering 6342 standards require. 6343 6344 5) Unconventional but efficient algorithms such as reverse 6345 Painter's algorithm are straightforward to implement when 6346 stencil and covering steps are decoupled. In this case, 6347 the stencil buffer simply never allows a pixel to be shaded 6348 a second time once covered. 6349 6350 6) Dilations and erosions can be performed with the two-step 6351 approach. You can fill a shape and then stroke the shape 6352 to dilate the shape. Then cover with both fill and stroking. 6353 6354 7) Novel stroking effects such as pin-striping are easy to 6355 accomplish. You can stroke a path with a stroke width of 7.5 6356 to write stencil to 1 and then stroke the same curve with 6357 a stroke width of 3.1 to write a stencil of 0. Then cover 6358 stroked path with a stroke width of 7.5 and accomplish the 6359 pen-striping. 6360 6361 4. What string formats should be supported for paths? 6362 6363 UNRESOLVED: Definitely SVG and PostScript. Perhaps Silverlight? 6364 6365 Silverlight's path syntax is very similar to SVG but allows 6366 infinity values and the specification of the fill mode. 6367 6368 Adobe's Type 2 charstring format, part of Adobe's Compact 6369 Font Format (CFF) standard, provides yet another encoding 6370 of a path outline. This is a binary, rather than textual, 6371 format that exists within OpenType and Type 2 font formats. 6372 It includes glyph hinting information. The utility of accepting 6373 the Type 2 charstring format is not sufficient for inclusion for 6374 a number of reasons. Content creation tools don't target this 6375 format for arbitrary path descriptions. This extension already 6376 provides commands (glPathGlyphsNV and glPathGlyphRangeNV) for 6377 specifying path objects from font glyphs. And the font hinting 6378 information the format provides would just be ignored. 6379 6380 5. Should there be a query to return a path as a string? 6381 6382 RESOLVED: No, returning dynamic strings of variable length is too hard. 6383 6384 Unlike parsing which is straightforward but slightly difficult, 6385 building a string from the results of glGetPathCommandsNV and 6386 glGetPathCoordsNV is not hard. But there's no one "right" 6387 way to build a string for a given path. 6388 6389 There are various string encodings of varying compactness and 6390 readability. How much precision is really required for converting 6391 a floating-point coordinate to a string representation varies? 6392 6393 6. Should path rendering allow per-vertex specification of attributes? 6394 6395 RESOLVED: No. 6396 6397 There is no allowance for the specification of interpolants 6398 (colors, texture coordinates, etc.) specified per control point. 6399 Assigning per-vertex values to control points doesn't really 6400 make sense in the context of path rendering. Instead a mechanism 6401 for generating color, texture coordinate, and fog generation as 6402 a linear function of object space. 6403 6404 The glPathTexGenNV, glPathColorGenNV, and glPathFogGenNV commands 6405 provide this mechanism. 6406 6407 glPathColorGenNV, glPathTexGenNV, and glPathFogGenNV 6408 provide a way to specify coefficients for plane equations based 6409 on the object-space or eye-space (x,y,1) position of a fragment 6410 generating by covering a filled or stroked path. 6411 6412 For those used to conventional 3D graphics where geometry is 6413 defined by meshes of triangles, not having per-vertex attributes 6414 sounds really strange. But this is the natural situation for 6415 path rendering. Paths do not really have vertices but rather 6416 control points. 6417 6418 7. Should path rendering use the existing texture coordinate 6419 generation state (glTexGen)? 6420 6421 RESOLVED: No, this extension should have its own path-specific 6422 texture coordinate generation state controlled by glPathColorGenNV 6423 and glPathTexGenNV. 6424 6425 The existing texture coordinate generation state has modes such 6426 as sphere, normal, and reflection mapping that make no sense for 6427 path rendering (since there are no per-vertex normals). 6428 6429 Also it is very desirable to keep the per-vertex attribute 6430 computations (normal transformation, lighting, texture coordinate 6431 generation) completely separate from the varying computations 6432 for path rendering. This means the vertex processing program 6433 needed for path rendering isn't changed by state updates intended 6434 to control geometric and image primitives. 6435 6436 8. How does path rendering work if all the fixed-function state, 6437 particularly the modelview and projection matrices and named vertex 6438 attributes (primary color, etc.) have been deprecated? 6439 6440 RESOLVED: ARB_compatibility (for OpenGL 3.1) or the Compatibility 6441 profile (for OpenGL 3.2 and up) is useful and supports the 6442 glPathColorGenNV, glPathTexGenNV, and glPathFogGenNV commands 6443 to interact properly with fixed-function OpenGL. 6444 6445 NV_path_rendering assumes that the modelview and projection 6446 matrices combine to transform the path into clip space. 6447 Without these matrices, there's no way to get the path 6448 transformed. Therefore these matrices are introduced through 6449 EXT_direct_state_access commands when only the Core profile is 6450 supported. 6451 6452 Without ARB_compatibility or the Compatibility profile, there is 6453 no way for GLSL to access built-in varyings as these have been 6454 deprecated. This means generated or passed-through colors and 6455 texture coordinate sets are inaccessible. There's also no longer 6456 a way to compile a fragment shader that doesn't have a vertex 6457 shader. The ARB_separate_shader_objects extension (core in OpenGL 6458 4.1) now allows a fragment shader to be specified in a program 6459 object with a vertex shader. The ARB_program_interface_query 6460 extension (core in OpenGL 4.3) allows queries to specific program 6461 object resources. The glProgramPathFragmentInputGenNV provides 6462 a means, in combination with the ARB_separate_shader_objects and 6463 ARB_program_interface_query extensions, to configure fragment 6464 input generation for GLSL fragment shaders use during the "cover" 6465 step of path rendering without reference to fixed-function 6466 mechanisms. 6467 6468 See the "Dependencies on Core Profile and OpenGL ES" section 6469 and issue 133 for more details about the Core profile support. 6470 6471 9. How does a GLSL fragment shader processing fragment generated by 6472 covering path access fragment varyings? 6473 6474 RESOLVED: The obvious way is to used the gl_TexCoord[], gl_Color, 6475 and gl_SecondaryColor built-in varyings for texture coordinate 6476 sets, primary color, and secondary color respectively. 6477 6478 Any user-specified varyings will be undefined since there is no 6479 upstream geometry or vertex shader to write them. 6480 6481 10. How should the command token values be assigned? 6482 6483 RESOLVED: Consistent with OpenVG's enumeration values but ALSO using 6484 the SVG command characters too. 6485 6486 The two token addition (missing from OpenVG's supported commands) 6487 are relative and absolute 7-component partial elliptical arc 6488 tokens (GL_ARC_TO_NV and GL_RELATIVE_ARC_TO_NV) that include the 6489 large/small and sweep flags as coordinates. These corresponds 6490 to the SVG 'arcto' commands. 6491 6492 Using character codes, in addition to tokens, allows simpler 6493 path descriptions coded with C character arrays (strings) such 6494 as "MLLCz" instead of the equivalent verbose aggregate array 6495 initializer { GL_MOVE_TO_NV, GL_LINE_TO_NV, GL_LINE_TO_NV, 6496 GL_CUBIC_CURVE_TO_NV, GL_CLOSE_PATH_NV }. 6497 6498 Also note there are NO character codes for the eight 5-component 6499 partial elliptical arc commands because these commands lack 6500 exact analogues in the SVG path command syntax. 6501 6502 There are also commands corresponding to PostScript's circular arc 6503 commands (arc, arcn, and arct), also without character aliases. 6504 6505 Unfortunately the path command token values do NOT match the 6506 SVGPathSeg interface path segment type values because these 6507 values overlap with the OpenVG enumeration values. 6508 6509 Excepting the printable ASCII character command tokens, absolute 6510 command token values should always be even, while relative 6511 command token values should always be odd. 6512 6513 11. Why are the glyph metric bits in the order they are specified? 6514 6515 RESOLVED: The glyph metric order matches the FreeType 2 library's 6516 FT_Glyph_Metrics structure for the per-glyph metrics. The 6517 per-font metric order matches the FreeType 2 library's FT_FaceRec 6518 structure. 6519 6520 Kerning information for a font face can be queried with the 6521 separate query glGetPathSpacingNV because the kerning displacement 6522 is not per-glyph, but rather dependent on a sequence of two 6523 glyphs. 6524 6525 12. What glyph metric information is beyond the scope of this extension? 6526 6527 RESOLVED: Metrics for vertical kerning, bi-directional layout, 6528 ligatures, etc. are beyond the scope of this extension. 6529 6530 Kerning information for horizontal layout is available. 6531 6532 The scope of the metrics provided by this extension are sufficient 6533 for basic kerned and non-kerned horizontal and non-kerned vertical 6534 text layout. 6535 6536 Applications that want more sophisticated metric information 6537 should either query the metrics from the corresponding system 6538 font directly or load the glyph outline data entirely from the 6539 application. 6540 6541 13. What glyph outline information is beyond the scope of this 6542 extension? 6543 6544 RESOLVED: For now, normal (indicated by GL_NONE), italic, 6545 bold, and bold/italic font faces are supported. Other styles 6546 (small caps, etc.) may be added with future extensions to this 6547 extension, but the four supported font styles are sufficient. 6548 6549 This is consistent with FreeType 2's support for the 6550 FT_STYLE_FLAG_ITALIC and FT_STYLE_FLAG_BOLD flags. 6551 6552 14. Should horizontal kerning information always be available? 6553 6554 RESOLVED: Yes, if the font provides this kerning information. 6555 6556 15. Why is the horizontal kerning information for a pair of path 6557 objects returned as a 2D (x,y) displacement? 6558 6559 RESOLVED: TrueType fonts always return kerning information 6560 as a sequence of horizontal displacements in x, but not y (the 6561 displacement is assumed to be zero in y). However PostScript 6562 fonts can support a 2D displacement. 6563 6564 This matches the behavior of FreeType 2's FT_Get_Kerning function. 6565 6566 Note that the returned (x,y) float pairs are NOT immediately 6567 suitable to be used as values for the /transformValues/ 6568 array parameter to StencilFillPathInstancedNV, 6569 StencilStrokePathInstancedNV, CoverFillPathInstancedNV, or 6570 CoverStrokePathInstancedNV with a /transformType/ parameter 6571 of TRANSLATE_2D_NV. The application would be responsible for 6572 accumulating the various translates to provide proper horizontal 6573 layout. When all the y values are zero (as will often be the 6574 case), GL_TRANSLATE_1D_NV could be used instead. 6575 6576 16. Should the path name zero be treated specially? 6577 6578 RESOLVED: No. There's no need for specially handling the zero 6579 name for a path object. 6580 6581 17. What tokens for color should glPathColorGenNV accept? 6582 6583 RESOLVED: GL_PRIMARY_COLOR (from OpenGL 1.3), GL_PRIMARY_COLOR_NV 6584 (from NV_register_combiners), and GL_SECONDARY_COLOR_NV (from 6585 NV_register_combiners). 6586 6587 GL_PRIMARY_COLOR and GL_PRIMARY_COLOR_NV have different token 6588 values; to avoid an API pitfall, both are accepted. 6589 6590 (There is no core GL_SECONDARY_COLOR token.) 6591 6592 18. Should two-sided color be supported for path rendering? 6593 6594 RESOLVED: No. No path rendering standards support this concept. 6595 6596 Two-sided lighting could be simulated with two passes and face 6597 culling. 6598 6599 19. How do PostScript's user path operators correspond to 6600 NV_path_rendering's path command tokens? 6601 6602 RESOLVED: 6603 6604 PostScript path 6605 operator Path command token 6606 --------------- ----------------------------- 6607 arc GL_CIRCULAR_CCW_ARC_TO_NV 6608 arcn GL_CIRCULAR_CW_ARC_TO_NV 6609 arcto GL_CIRCULAR_TANGENT_ARC_TO_NV 6610 closepath GL_CLOSE_PATH_NV 6611 curveto GL_CUBIC_CURVE_TO_NV 6612 lineto GL_LINE_TO_NV 6613 moveto GL_MOVE_TO_NV 6614 rcurveto GL_RELATIVE_CUBIC_CURVE_TO_NV 6615 rlineto GL_RELATIVE_LINE_TO_NV 6616 rmoveto GL_RELATIVE_MOVE_TO_NV 6617 setbbox /ignored/ 6618 ucache /ignored/ 6619 6620 The setbbox (set bounding box) operator "establishes a bounding 6621 box for the current path, within which the coordinates of all 6622 subsequent path construction operators must fall." There is 6623 no such requirement in this extension so this bounding box 6624 information is parsed but ignored. 6625 6626 The ucache (user cache) operator "notifies the PostScript 6627 interpreter that the enclosing user path is to be retained in 6628 the cache if the path is not already there." This notion that 6629 paths are expensive and so must be cached is not particularly 6630 applicable to this extension because all path object are in 6631 some sense cached. Therefore the ucache operator is parsed 6632 but ignored. 6633 6634 20. How do OpenVG 1.1's commands (as enumerated by the VGPathCommand 6635 and VGPathCommand enumerations) correspond to NV_path_rendering's 6636 path command tokens? 6637 6638 RESOLVED: 6639 6640 OpenVG path 6641 segment command Path command token 6642 ----------------- ---------------------------------------- 6643 VG_CLOSE_PATH GL_CLOSE_PATH_NV 6644 VG_CUBIC_TO GL_CUBIC_CURVE_TO_NV 6645 VG_CUBIC_TO_ABS " 6646 VG_CUBIC_TO_REL GL_RELATIVE_CUBIC_CURVE_TO_NV 6647 VG_HLINE_TO GL_HORIZONTAL_LINE_TO_NV 6648 VG_HLINE_TO_ABS " 6649 VG_HLINE_TO_REL GL_RELATIVE_HORIZONTAL_LINE_TO_NV 6650 VG_LCCWARC_TO GL_LARGE_CCW_ARC_TO_NV 6651 VG_LCCWARC_TO_ABS " 6652 VG_LCCWARC_TO_REL GL_RELATIVE_LARGE_CCW_ARC_TO_NV 6653 VG_LCWARC_TO GL_LARGE_CW_ARC_TO_NV 6654 VG_LCWARC_TO_ABS " 6655 VG_LCWARC_TO_REL GL_RELATIVE_LARGE_CW_ARC_TO_NV 6656 VG_LINE_TO GL_LINE_TO_NV 6657 VG_LINE_TO_ABS " 6658 VG_LINE_TO_REL GL_RELATIVE_LINE_TO_NV 6659 VG_MOVE_TO GL_MOVE_TO_NV 6660 VG_MOVE_TO_ABS " 6661 VG_MOVE_TO_REL GL_RELATIVE_MOVE_TO_NV 6662 VG_QUAD_TO GL_QUADRATIC_CURVE_TO_NV 6663 VG_QUAD_TO_ABS " 6664 VG_QUAD_TO_REL GL_RELATIVE_QUADRATIC_CURVE_TO_NV 6665 VG_SCCWARC_TO GL_SMALL_CCW_ARC_TO_NV 6666 VG_SCCWARC_TO_ABS " 6667 VG_SCCWARC_TO_REL GL_RELATIVE_SMALL_CCW_ARC_TO_NV 6668 VG_SCUBIC_TO GL_SMOOTH_CUBIC_TO_NV 6669 VG_SCUBIC_TO_ABS " 6670 VG_SCUBIC_TO_REL GL_RELATIVE_SMOOTH_CUBIC_TO_NV 6671 VG_SCWARC_TO GL_SMALL_CW_ARC_TO_NV 6672 VG_SCWARC_TO_ABS " 6673 VG_SCWARC_TO_REL GL_RELATIVE_SMALL_CW_ARC_TO_NV 6674 VG_SQUAD_TO GL_SMOOTH_QUADRATIC_CURVE_TO_NV 6675 VG_SQUAD_TO_ABS " 6676 VG_SQUAD_TO_REL GL_RELATIVE_SMOOTH_QUADRATIC_CURVE_TO_NV 6677 VG_VLINE_TO GL_VERTICAL_LINE_TO_NV 6678 VG_VLINE_TO_ABS " 6679 VG_VLINE_TO_REL GL_RELATIVE_VERTICAL_LINE_TO_NV 6680 6681 21. What should the initial GL_PATH_FILL_MODE_NV state be? 6682 6683 RESOLVED: GL_PATH_FILL_MODE_NV should initially be 6684 GL_COUNT_UP_NV. 6685 6686 This is consistent with SVG default non-zero fill rule and the 6687 typical usage of PostScript. 6688 6689 However this is the opposite of Silverlight's default fill rule 6690 which is even-odd. 6691 6692 22. Should we support a GL_PATH_FORMAT_SL3_NV for Silverlight 3.0 be 6693 added? 6694 6695 UNRESOLVED: Silverlight 3.0's path markup syntax includes 6696 support for two extensions of the SVG 1.1 path grammar: 1) 6697 specification of a fill rule ("F0" is even-odd, "F1" is non-zero) 6698 at the beginning of the string; and 2) allowing "Infinity", 6699 "-Infinity" and "NaN" (all case-sensitive) as special values 6700 allowed instead of standard numerical values. 6701 6702 Seems like a reasonable thing to support. 6703 6704 The fill rule specification is straightforward. This would 6705 simply allow the path object's GL_PATH_FILL_MODE_NV parameter to 6706 be specified as part of the path string specification. The "F0" 6707 or "F1" would not be treated as an actual path command however. 6708 6709 Note that Silverlight's default fill rule if none is specified is 6710 EvenOdd whereas NV_path_rendering's default GL_PATH_FILL_MODE_NV 6711 is GL_COUNT_UP_NV (essentially a non-zero rule). So specifying a 6712 path with the Silverlight format would have a different initial 6713 value for GL_PATH_FILL_MODE_NV if "F0" or no initial F 6714 command is specified. 6715 6716 What exactly would it mean to allow infinite and not-a-number 6717 values for the coordinate values of a path object? Infinite is 6718 probably representable today by simply writing a number with a 6719 sufficiently large enough magnitude. Allowing not-a-number is 6720 probably more 6721 6722 23. Should there be some maximum specified limit for the number of 6723 command (and hence coordinates) in a path object? 6724 6725 RESOLVED: No. The standards for path rendering do no generally 6726 have limits on path command lengths. 6727 6728 For extreme cases, the OUT_OF_MEMORY error would be generated but 6729 that is considered an exceptional case due to memory exhaustion, 6730 not simply the specification of a huge path. 6731 6732 24. Should there be some maximum specified limit for the dash array? 6733 6734 RESOLVED: No. The standards for path rendering do not generally 6735 have a limit on the dash array length. 6736 6737 25. How do the client-defined clip planes and the clip volume interact 6738 with path rendering? 6739 6740 RESOLVED: Stenciled and covered paths are affected by both the 6741 clip volume and client-defined clip planes. 6742 6743 Clip planes affect the set of accessible pixels for stenciling 6744 and covering operations (see the "ACCESSIBLE SAMPLES WITH RESPECT 6745 TO A TRANSFORMED PATH" subsection of section 5.X.2.1). 6746 6747 26. What should the end cap style be called that adds no additional 6748 cap region to a stroked path? 6749 6750 RESOLSVED: FLAT. 6751 6752 FLAT is already an existing OpenGL token name. Silverlight and 6753 the OpenXML Paper Specification (XPS) calls this end cap style 6754 "flat". However PostScript, Flash, OpenVG, SVG, Quartz 2D, 6755 and Cairo Graphics all call this end cap style "butt". 6756 6757 Using FLAT also avoids verbalizing the awkward phrase "butt 6758 stroking" (not that there's anything wrong with that). 6759 6760 27. Should the PostScript grammar for user-defined paths be supported? 6761 6762 RESOLVED: Yes. PostScript has commands (arc, arcn, arct) that 6763 do not correspond to precisely to SVG command. This is 6764 particularly true of arct. 6765 6766 Applications have been generating paths according to the syntax 6767 of Level 2 PostScript for a long time. 6768 6769 Level 2 PostScript also has support for binary encoding that 6770 makes it significantly more compact and less expensive to parse 6771 than the SVG grammar. 6772 6773 The binary encoding allows precise floating-point (and compact 6774 fixed-point) values to be specified. 6775 6776 28. Should the PostScript grammar support big-endian, little-endian, 6777 and native numeric encodings? 6778 6779 RESOLVED: Yes, yes, yes. 6780 6781 29. Should the PostScript grammar support encoded user paths? 6782 6783 RESOLVED: Yes. 6784 6785 30. How should the PostScript grammar support strings? 6786 6787 UNRESOLVED: Hexadecimal encoded data, that is strings enclosed 6788 in < and >, are supported. 6789 6790 Strings for ASCII base-85 encoded data, that is strings enclosed 6791 in <~ and ~>, are supported for the data-array and operator-string 6792 production 6793 6794 Also the short-binary-string, be-long-binary-string, and 6795 le-long-binary-string productions allow very compact and precise 6796 encoding of operator strings through binary encoding. 6797 6798 Strings for literal text, that is strings enclosed in ( and ), 6799 are NOT supported. 6800 6801 The rationale for not supporting literal text is this format 6802 is awkward for encoding the operator-string production (though 6803 PostScript does technically allow it) and is not compact. 6804 6805 31. Should the PostScript grammar support Binary Object Sequences? 6806 6807 RESOLVED: No. 6808 6809 Binary Object Sequences are intended to support complex 6810 (potentially nested) data structures and are over-kill for 6811 user paths. 6812 6813 32. Why are the binary tokens in the PS grammar assigned the values 6814 they are assigned? 6815 6816 RESOLVED: These values are from the "Binary Tokens" section of 6817 the PostScript Language Reference Manual. 6818 6819 33. Why are the binary encodings for the path commands in the PS 6820 grammar assigned the specified values? 6821 6822 RESOLVED: These values match PostScript's system name table 6823 values. These are documented in the "System Name Encodings" 6824 appendix of the PostScript Language Reference Manual. 6825 Specifically (in decimal): 6826 6827 Index Name 6828 ----- --------- 6829 22 closepath 6830 99 lineto 6831 107 moveto 6832 133 rlineto 6833 134 rmoveto 6834 143 setbbox 6835 43 curveto 6836 122 rcurveto 6837 5 arc 6838 6 arcn 6839 7 arct 6840 177 ucache 6841 6842 34. Why do glGetPathCommandsNV, glGetPathCoordsNV, and 6843 glGetPathDashArrayNV have their own queries? Could there not 6844 simply be a token for glGetPathParameteriv/glGetPathParameterfvNV 6845 to return this state? 6846 6847 RESOLVED: These queries for path commands, coordinates, and 6848 the path's dash array return a variable payload of data so are 6849 more like glGetTexImage than glGetIntegerv/glGetFloatv which 6850 return a static amount of data. 6851 6852 APIs that return variable amounts of data are prone to buffer 6853 overflows. It is somewhat more obvious these commands return 6854 a variable amount of data if they have their own API calls, than 6855 simply having certain token values to a multi-purpose glGet* call 6856 that mysteriously returns varying amounts of data for these token 6857 values while all the other tokens return static amounts of data. 6858 6859 This resolution follows the existing precedent from 6860 core OpenGL where glGetColorTable is distinct from 6861 glGetColorTableParameter{fv,iv}. Same with glGetConvolutionFilter 6862 and glGetHistogram relative to glGetConvolutionParameter{fv,iv} 6863 and glGetHistogramParameter{fv,iv}. 6864 6865 (There is a poor precedent for having an OpenGL query return both 6866 static and varying amounts of data based on a pname parameter. 6867 glGetMap{dv,fv,iv} returns varying data when GL_COEFF is queried 6868 while GL_ORDER and GL_DOMAIN return n and 2*n values respectively 6869 where n is the dimensionality of the map target. This isn't a 6870 good precedent and is obscure.) 6871 6872 35. How should the GL_PATH_*_BOUNDING_BOX_NV path parameters be 6873 returned? 6874 6875 RESOLVED: In (x1,y1,x2,y2) order where (x1,y1) is the minimum 6876 bounds of the bounding box and (x2,y2) is the maximum bounds. 6877 6878 This is contrary to the precedent of GL_SCISSOR_BOX query 6879 which returns the scissor as an (x,y,width,height) 4-tuple. 6880 While that makes sense for a scissor box, particularly given how 6881 the scissor is specified with glScissor, it is not a convenient 6882 way to specify a bounding box. 6883 6884 The (x1,y1,x2,y2) format also makes the 6885 glCover{Fill|Stroke}PathInstancedNV pseudo-code work nicely 6886 with glRectf. See the renderBoundingBox pseudo-code. 6887 6888 The (x1,y1,x2,y2) format is also consistent with the way 6889 FreeType 2 provides per-font face bounds information through 6890 the GL_FONT_X_MIN_BOUNDS_BIT_NV, GL_FONT_Y_MIN_BOUNDS_BIT_NV, 6891 GL_FONT_X_MAX_BOUNDS_BIT_NV, and GL_FONT_Y_MAX_BOUNDS_BIT_NV 6892 metric queries. 6893 6894 36. Why is font loading part of this extension? Shouldn't OpenGL 6895 stick with just rendering and not involved itself with fonts? 6896 6897 RESOLVED: An explicit goal of this extension is to provide 6898 GPU-accelerated path rendering that INCLUDES excellent support 6899 for glyphs and their associated metrics. 6900 6901 The fact is all the major existing standards for path rendering 6902 (PostScript, SVG, OpenVG, Java 2D, Quartz 2D, Flash) include 6903 first-class font and glyph support. 6904 6905 Not including font and glyph support would be a glaring omission 6906 that would make this extension much less useful to simple OpenGL 6907 applications that don't want to incorporate large font libraries. 6908 6909 Additionally font loading is notoriously platform dependent. 6910 This extension provides a simple platform-independent mechanism to 6911 rendezvous with standard font names. However an implementation of 6912 this extension can make use of whatever platform-specific font 6913 services the platform provides (such as through DirectWrite, 6914 etc.). 6915 6916 Fonts, particularly for Asian languages or designed to support a 6917 large portion of Unicode, are large. Populating their complete 6918 outlines can consume substantial amounts of system and video 6919 memory. Many applications on a system are likely to access 6920 the same collections of fonts. Having fonts loaded by name 6921 allows GL implementations to coordinate the efficient sharing 6922 of font outline data among multiple GL application instances. 6923 This font sharing can have a substantial reduction in the total 6924 system resources devoted to font data which is not possible if 6925 the GL is unable to be aware of duplicated font outline data 6926 within the system. 6927 6928 Font formats change and evolve over time. Building font format 6929 knowledge into applications will ultimately be limiting long-term. 6930 6931 Fonts are really properly thought of as system resources. 6932 They represent intellectual property that is typically licensed 6933 on a per-system basis. Building font access into the GL promotes 6934 use of the system's properly licensed fonts. Most applications 6935 do not want to be encumbered by licensing issues associated with 6936 fonts so to the extent that the API makes access to system fonts 6937 easier, that promotes properly licensed use of fonts. 6938 6939 37. What is the typographical philosophy for this extension? 6940 6941 RESOLVED: This extension relies on other standards to provide 6942 its typographic backbone and philosophy. 6943 6944 The character set supported depends on the Unicode standard. 6945 6946 Specific font formats supported depend on the system but the 6947 expectation is that standard TrueType, PostScript, and OpenType 6948 fonts can be used through this extension. The metrics from such 6949 fonts will generally be "passed through" the glGetPathMetricsNV 6950 query. 6951 6952 The naming of fonts is consistent with the underlying system 6953 with the expectation that the system's naming is consistent with 6954 modern web standards for identifying fonts in web content. 6955 6956 While the specific set of supported fonts may vary from system to 6957 system based on the available installed fonts, the expectation is 6958 that standard TrueType fonts such as Arial, New Courier, Georgia, 6959 etc. will be available on systems that support this extension. 6960 6961 For applications that demand a set of glyphs that are guaranteed 6962 to be available, the GL_STANDARD_FONT_NAME font target is 6963 available for the names "Sans", "Serif", and "Mono" and these 6964 fonts are understood to match a set of glyphs consistent with the 6965 DejaVu font set populated with at least the Latin-1 character set. 6966 6967 The underlying font engine is likely to be FreeType 2 or the 6968 system's native font engine (such as DirectWrite for newer 6969 Windows versions). 6970 6971 38. What is the path rendering philosophy for this extension? 6972 6973 RESOLVED: Two-step stencil-based GPU-acceleration + broad-tent 6974 support for the accepted functionality of path rendering. 6975 6976 This extension assumes that the two-step "stencil, then cover" 6977 stencil-based approach to GPU-accelerating path rendering. 6978 6979 Both stenciling and stroking are supported. Strokes are 6980 first-class representations and not treated as fills that 6981 approximate the stroked region. For pragmatic reasons, cubic 6982 Bezier segments, conic segments, and partial elliptical 6983 (non-circular) arcs path segments are assumed to be approximated 6984 by a sequence of quadratic Bezier path segments that guarantee 6985 G1 continuity. 6986 6987 The contrapositive of this approach is an avoidance of schemes 6988 based on tessellation of path outlines. 6989 6990 Paths are defined using both cubic and quadratic Bezier curves. 6991 This broadly allows path content from TrueType (based on quadratic 6992 Bezier curves) and PostScript and its font families (based on 6993 cubic Bezier curves) to be supported. 6994 6995 Arcs are drawn consistent with both SVG (partial elliptical arcs) 6996 and PostScript (circular arcs and circular tangent arcs). 6997 6998 The set of stroking options is a union of the stroking features 6999 of OpenVG, SVG, XML Paper Specification (XPS), PostScript, and 7000 other standards. For example, XPS supports dash caps that other 7001 standards lack. 7002 7003 The path queries support the key path queries supported by OpenVG. 7004 7005 39. Should there be an API for assigning path metric information to 7006 a path object? 7007 7008 RESOLVED: No. 7009 7010 Path metrics are available when a path object is created with 7011 glPathGlyphsNV or glPathGlyphRangeNV. In these cases, the font 7012 supplies the metric data for these path objects. 7013 7014 It might be useful to allow these metrics to be specified for an 7015 arbitrary path object. This way user-defined path objects could 7016 appear to have metrics available as if they had been specified 7017 by glPathGlyphsNV or glPathGlyphRangeNV. 7018 7019 Supporting the specification of path metrics would require new 7020 API. Something like glPathMetricsNV perhaps? Or having parameter 7021 names for the font metrics supported by glPathParameter{f,i}v? 7022 The later approach would probably require new tokens and would 7023 mean glGetPathParameter{f,i}v should support these tokens too. 7024 7025 Since the metrics are for information purposes only, meaning 7026 the rendering functionality for paths never involves the metrics 7027 (unlike other path parameters), it seems odd to allow information 7028 to be specified just so it can be queried by the application. 7029 This doesn't feel like essential functionality though its 7030 absence may be missed by library developers that want to "fake" 7031 font loaders. 7032 7033 40. What happens when an input path object to glWeightPathsNV, 7034 glInterpolatePathsNV contains an arc command when there are two 7035 or more path objects involved? 7036 7037 RESOLVED: An INVALID_OPERATION error is generated. 7038 7039 In general, arc commands are not "closed" under linear 7040 combination. Said another way, the linear combination of two 7041 or more arcs is not, in general, itself an arc of the same form. 7042 7043 glCopyPathNV copies outlines for path objects containing any 7044 valid commands including arc commands. 7045 7046 41. When a path object is created from other existing path objects 7047 through the glWeightPathsNV, glInterpolatePathsNV, or glCopyPathNV 7048 commands, where does the new path's parameters come from? 7049 7050 RESOLVED: While the path commands are interpolated on a 7051 command-by-command basis with these commands, the path parameters 7052 should be copied from the first path object specified. 7053 7054 So for glWeightPathsNV, glInterpolatePathsNV, and glCopyPathNV, 7055 the path parameters from the path[0], pathA, and srcPath 7056 parameters respectively. 7057 7058 42. How is the glyph metric and kerning information specified for 7059 a path object created from other existing path objects through the 7060 glWeightPathsNV, glInterpolatePathsNV, or glCopyPathNV commands, 7061 where does the new path's parameters come from? 7062 7063 RESOLVED: The path metric information is set to negative one 7064 for glWeightPathsNV and glInterpolatePathsNV. 7065 7066 There's no reasonable way to weight the metric information. 7067 Metric information is tuned to a particular glyph. 7068 7069 More explicitly, the path metric information from the first path 7070 object to be combined is NOT copied (as the parameters are). 7071 7072 However glCopyPathNV does copy the glyph metric and kerning 7073 information (since only one path object is involved so there's 7074 no combination of outlines). 7075 7076 43. Should there be a way to specify different stroking parameters 7077 (stroke width, end caps, etc.) within the command sequence of 7078 a path? 7079 7080 RESOLVED: No. 7081 7082 Existing path rendering standards keep the stroking parameters 7083 constant for a given path's outline. For example, there's not 7084 support for a dashed stroked segment of width 5.0 as well as a 7085 non-dashed stroked segment with width 9.4 in the same path. 7086 7087 This wouldn't be impossible to support; commands that changed 7088 stroking parameters could be supported within the command 7089 sequence. However it would complicate the meaning of the path 7090 parameters for stroking; these parameters could be considered 7091 defaults for stroking parameters if stroking parameters are not 7092 otherwise specified. There's also the complication of when 7093 new stroking parameters would latch into place. Would it be 7094 immediately (mid path?) or not latch until the next "moveto" 7095 command? And how would such commands be weighted/interpolated? 7096 7097 Attempting to support changing stroking parameters within a path 7098 appears to open up a complicated can of worms. 7099 7100 The same rendering effect can be achieved with the 7101 gl{Stencil,Cover}StrokePathInstancedNV commands using multiple 7102 path object, each with the appropriate stroking parameters for 7103 the appropriate path segments. 7104 7105 44. What should the query token for the path color and texture 7106 coordinate generation coefficients be named? 7107 7108 RESOLVED: GL_PATH_GEN_COEFF_NV. 7109 7110 Alternatively this could be GL_PATH_GEN_COEFF_NV (plural), 7111 but that doesn't match the precedent set by GL_COEFF used by 7112 glGetMap{f,d}v. These existing queries return a plurality of 7113 coefficients too. 7114 7115 45. What should the number of coefficients returned when querying the 7116 path color and texture coordinate generation coefficients depend 7117 on the current path color or texture coordinate generation mode or 7118 should a fixed maximum number of coefficients always be returned? 7119 7120 RESOLVED: A fixed maximum of 16 coefficients should always 7121 be returned. 7122 7123 It is error-prone and likely to result in obscure buffer 7124 overflow cases if the number of coefficients returned depends 7125 on the respective current path generation mode. It is better 7126 to simply always return 16 values. Unused coefficients by the 7127 current generation mode should always be returned as zero. 7128 7129 46. How does glGetPathLengthNV compare to OpenVG's vgPathLength? 7130 7131 RESOLVED: glGetPathLengthNV and vgPathLength compute 7132 essentially the same result except glGetPathLengthNV returns 7133 0 when /numSegments/ is 0 whereas vgPathLength considers this 7134 case an error. 7135 7136 47. Where does all the discussion of partial elliptical arc 7137 parameterization come from? 7138 7139 RESOLVED: This discussion is based on and fully consistent with: 7140 7141 http://www.w3.org/TR/SVG/implnote.html#ArcImplementationNotes 7142 7143 48. Where does the parameterization of the 7144 GL_CIRCULAR_TANGENT_ARC_TO_NV come from? 7145 7146 RESOLVED: The GL_CIRCULAR_TANGENT_ARC_TO_NV is based on the 7147 PostScript arct command (which is based on arcto) for user paths. 7148 7149 See the gs_arcto routine in: 7150 7151 http://svn.ghostscript.com/ghostscript/trunk/gs/base/gspath1.c 7152 7153 49. How should fog coordinate generation work for path rendering? 7154 7155 RESOLVED: The glPathFogGenNV command controls how generation 7156 of the fog coordinate operates for path rendering commands. 7157 7158 The GL_FOG enable is tricky because it controls both per-vertex and 7159 per-fragment processing state (unlike per-vertex lighting and texture 7160 coordinate generation). 7161 7162 Simply using the existing fixed-function fog coordinate state is 7163 undesirable because that 1) entangles fog coordinate generation 7164 with conventional vertex processing and path vertex processing, 7165 and 2) the NV_fog_distance extension allows a non-linear fog 7166 coordinate to be generated through the GL_EYE_RADIAL_NV mode. 7167 7168 The fog coordinate generation for path rendering can either 7169 use the fog coordinate "as is" for the entire covered path or 7170 have the fog coordinate be the negated perspective-divided 7171 eye-space Z component (which can vary, but only linearly). 7172 7173 50. What should glyph metrics return for path objects not specified 7174 by glPathGlyphsNV or glPathGlyphRangeNV? 7175 7176 RESOLVED: All queried metrics should return the value -1. 7177 7178 Negative values are out-of-range for many of the metric values so 7179 negative values provide a reliable indicator that a path object 7180 was not specified from a glyph. 7181 7182 51. How should the fill mode state of path objects created from 7183 glyphs be initialized? 7184 7185 RESOLVED: The initial GL_PATH_FILL_MODE_NV for path objects 7186 created from glyphs depends on the source font's convention. 7187 7188 Typically TrueType and newer (all?) PostScript fonts depend on the 7189 non-zero fill rule. TrueType fonts assume a clockwise outline 7190 winding (hence will use GL_COUNT_DOWN_NV) while PostScript 7191 fonts assume a counterclockwise outline winding (hence will 7192 use GL_COUNT_UP_NV). 7193 7194 It's unlikely an actual font will use GL_INVERT as its 7195 GL_PATH_FILL_MODE_NV but the possibility is allowed. 7196 7197 52. Should other path object parameters other than the fill mode be 7198 initialized specially when path objects are specified from glyphs? 7199 7200 RESOLVED: No. 7201 7202 In theory, other path parameters such as stroke width, join style, 7203 etc. could all be specified from the font. In practice, most 7204 font forms don't provide such parameters. 7205 7206 At least one font format, Bitstream's PFA format, does provide 7207 such information though how applicable these parameters are to 7208 a path object is unclear. The availability of these parameters 7209 appears to be intended as a way to bold or otherwise dilate the 7210 glyph's outline rather than being intended for stroking. 7211 7212 SVG supports stroking of fonts but the stroke-width tag is 7213 specified in the current user coordinate system rather than 7214 depending on the particular font or its glyphs. 7215 7216 53. How should the integers passed to glPathGlyphsNV and 7217 glPathGlyphRangeNV be mapped to actual glyph outlines for a font? 7218 7219 RESOLVED: The integers that come from the charcode array or 7220 the firstGlyph to firstGlyph+numGlyphs-1 range are treated as 7221 Unicode character codes if the font has a meaningful mapping of 7222 Unicode to its glyphs. 7223 7224 The existence of a meaningful mapping from Unicode to glyph 7225 outlines is the expected situation. For fonts without a 7226 meaningful mapping to Unicode character codes (such as custom 7227 symbol fonts), the font's standard mapping of character codes to 7228 glyphs should be used. This situation should be rare, probably 7229 due to a font that is poorly authored, very old, or custom built. 7230 7231 54. How are typographical situations such as ligatures, composite 7232 characters, glyph substitution, and language-dependent character 7233 sequence conversion handled? 7234 7235 RESOLVED: If a particular behavior is desired for how such 7236 situations are handled, that is up to the application software 7237 using this extension. 7238 7239 For example, in the case of ligatures, multiple Unicode characters 7240 may map to a single ligature glyph. Support for ligatures is 7241 a stylistic typographic decision and the application is free to 7242 handle this in any of a number of ways; this extension neither 7243 forces nor precludes specific approaches to handle ligatures. 7244 The application can overlap existing glyphs to create the 7245 appearance of a path object by rendering the individual multiple 7246 Unicode characters overlapped; a ligature character that is 7247 part of the Unicode character set could be selected; or the 7248 application could create its own custom path object in this 7249 situation and render it. 7250 7251 For composite characters, the underlying font engine used to 7252 implement this extension may construct composite characters. 7253 Or this may be a situation where, due to limitations of the 7254 font or font engine, possibly in combination, this is treated as 7255 an unknown or missing character where implementation-dependent 7256 handling is possible. Such a situation could also exist for a 7257 ligature character specified by Unicode. 7258 7259 In general, higher level details of text presentation such 7260 as ligatures, composite characters, glyph substitution, and 7261 language-dependent character sequence conversion are beyond the 7262 scope of this extension. 7263 7264 See the Unicode FAQ on "Ligatures, Digraphs and Presentation 7265 Forms": 7266 7267 http://www.unicode.org/faq/ligature_digraph.html 7268 7269 In complicated typographical situations, the assumption is that 7270 the application will construct the appropriate inter-glyph 7271 transformation values (the transformValues and transformType 7272 for glStencilFillPathInstancedNV and glCoverFillPathInstancedNV) 7273 and build digraphs or other presentation forms. 7274 7275 55. Are relative path commands converted to absolute commands upon 7276 path specification? 7277 7278 RESOLVED: No, relative commands are first-class and are 7279 maintained as relative commands. 7280 7281 This includes when relative commands are created by copying, 7282 interpolating, or weighting existing path objects. Relative path 7283 commands must match identical relative path commands and their 7284 relatively control points are weighted as relative position 7285 offsets. 7286 7287 Another implication if this is that if an application modifying 7288 the control points with glPathSubCoordsNV, those edits can effect 7289 the outline of subsequent relative commands that depend on the 7290 modified coordinates. 7291 7292 The same applies to changing commands. Editing commands with 7293 glPathSubCommandsNV can change how coordinates are interpreted 7294 for the edited commands and subsequent relative commands. 7295 7296 In other words, if a path object is modified or edited, the 7297 outline of the path is the same as if the path object had been 7298 specified from scratch with the same command and coordinate 7299 sequences. 7300 7301 56. What does this extension do with so-called "hinting" in outline 7302 font glyphs? 7303 7304 RESOLVED: When a path object is specified from the glyph of a 7305 font, the path object's outline is specified from the "ideal" 7306 resolution-independent form of the glyph. 7307 7308 This is because a path object is rendered (stenciled or covered) 7309 from a resolution-independent form. There is an implicit 7310 assumption in the specified transformation and rendering process 7311 that the process is unaware of the device coordinate grid. 7312 7313 This means there's not the knowledge of device coordinate space 7314 necessary to apply hinting information. 7315 7316 In TrueType terms, this amounts to the path object's outline for 7317 a TrueType glyph being the glyph's "master outline". This means 7318 the TrueType instructions associated with the glyph are ignored 7319 and not executed. 7320 7321 While it is beyond the scope of this extension, there's nothing 7322 in this extension that keeps an application in decoding itself the 7323 TrueType master outline of a glyph and performing the grid-fitted 7324 outline generation at a given arbitrary device resolution. 7325 Then this fitted outline could be specified for a path object. 7326 The key observation is that doing so makes the resulting outline 7327 resolution-dependent which obviates much of the advantage of 7328 this extension's ability to render from a resolution-independent 7329 outline. 7330 7331 Rather than relying on hinting for legibility, applications using 7332 this extension are likely to rely on multisampling or multiple 7333 jittered rendering passes for antialiasing and assume a certain 7334 amount of grayscale appearance as a consequence. 7335 7336 57. If a font format has bitmap font data, is that used? 7337 7338 RESOLVED: No, only resolution-independent outline data is used; 7339 bitmap data is ignored. Bitmap-only font formats won't be loaded. 7340 7341 In the FreeType 2 API, the information available is comparable 7342 to calling FT_Load_Glyph with the FT_LOAD_NO_SCALE and 7343 FT_LOAD_NO_BITMAP flags specified. 7344 7345 58. How is antialiasing of path object rendering accomplished? 7346 7347 RESOLVED: Multisampling is the expected way that antialiasing 7348 will be accomplished when rendering path objects. 7349 7350 Recall in multisampling that the stencil buffer is maintained 7351 at per-sample resolution. This means the coverage determined 7352 by stenciling path objects should be accurate to the sample 7353 resolution. 7354 7355 If a multisampled framebuffer provides N samples per pixel, that 7356 means that there are N+1 possible coverage weightings of a given 7357 path with respect to that pixel, assuming a single "stencil, then 7358 cover step", equal weighting of samples in the final pixel color, 7359 and the samples for a given pixel belonging to a single pixel. 7360 7361 One explicit goal of this extension is to maintain a separation 7362 between coverage and opacity. The two concepts are often 7363 conflated treating both as percentages and then modulating 7364 opacity with coverage. Conflating the two leads to coverage 7365 bleeding at what should be sharp, though transparent, edges and 7366 corners. 7367 7368 In this extension, the stencil buffer maintains coverage and 7369 the alpha channel for RGBA colors, which is per-sample when the 7370 framebuffer format supports multisampling, maintains opacity. 7371 7372 Philosophically this extension provides a robust and accurate 7373 mechanism for determining point-sampled coverage for arbitrary 7374 filled and stroked paths. The extension does not rely on, nor 7375 does it even attempt, to compute or approximate a path's area 7376 coverage with respect to a pixel. For practical reasons, such 7377 analytical computations are inevitably approximations for 7378 arbitrary paths and are difficult to make robust. 7379 7380 Point sampling of path object rasterization can offer more 7381 robustness and precision. Point sampling also allows this 7382 extension's rendering results to seamlessly co-exist with OpenGL's 7383 conventional point, line, and polygon rasterization approaches 7384 which are point-sampled. 7385 7386 The implication of this observation is path rendered content can 7387 be mixed with arbitrary OpenGL 3D content, whether rendered with 7388 depth testing or not. This provides the very powerful ability to 7389 mix path rendered and 3D rendered content in the same framebuffer 7390 in predictable ways with negligible overhead for doing so. 7391 7392 Keep in mind that 2D path rendered content is transformed by the 7393 projective modelview-projection transform, just like other OpenGL 7394 rendering primitives, so fragments generated with path rendering 7395 have varying depth values that can be depth tested, fogged, etc. 7396 7397 Point sampling is prone to missing coverage but avoids indicating 7398 coverage where no actual coverage exists. 7399 7400 This extension implicitly assumes that GPUs have some maximum 7401 sample location precision while rasterizing. This is an artifact 7402 of subpixel precision. This concept is built into OpenGL; see 7403 the GL_SUBPIXEL_BITS implementation-dependent limit. Developers 7404 should not expect any additional sampling precision beyond this 7405 limit. To get beyond this limit, applications would be expected 7406 to render at a larger framebuffer resolution and downsample to 7407 the appropriate resolution or render in some tiled fashion. 7408 7409 If multisampling provides insufficient antialiasing, further 7410 antialiasing is possible by rendering with multiple passes. 7411 7412 For example, applications can use accumulation buffer techniques 7413 with sub-pixel jittered re-rendering of the entire scene 7414 to improve the overall quality. This provides full-scene 7415 antialiasing. 7416 7417 Alternatively, a path object itself needing extra antialiasing, 7418 perhaps because the application has determined the path object 7419 maps to a small region of the framebuffer in window space, can 7420 be rendered multiple times, each time with subpixel jittering. 7421 By writing just into the non-visible alpha component of the 7422 framebuffer, a coverage percentage at each color sample can 7423 be accumulated. Then a final cover operation can blend this 7424 coverage information into the visible RGB color channels. 7425 7426 Despite the multiple passes involved, this approach can still 7427 be several times faster than CPU path rendering methods because 7428 of the rendering rate possible through GPU acceleration. 7429 7430 59. How do the multisample fragment operations interact with path 7431 rendering? 7432 7433 RESOLVED: They are ignored for the "stencil" path rendering 7434 operations (since only the stencil buffer is updated), and they 7435 work as specified for the "cover" path rendering operation. 7436 7437 The coverage determination made during the "cover" path 7438 rendering operation doesn't reflect the path itself but rather 7439 the conservative coverage provide by the covering operation. 7440 For this reason, the coverage mask is conservative, meaning 7441 samples may be covered that don't actually belong to the filled 7442 or stenciled region of the path being covered. And exactly how 7443 conservative this coverage is depends on the implementation. 7444 7445 Still the coverage is available and can be used as specified in 7446 section 4.1.3 ("Multisample Fragment Operations"). 7447 7448 The GL_SAMPLE_COVERAGE mode would be more useful if the stencil 7449 testing was performed prior to the shading of the covered geometry 7450 and the covered sample mask reflected any discards performed by 7451 the stencil (or depth) tests. 7452 7453 The NV_explicit_multisample extension and its 7454 ARB_texture_multisample functionality (standard with OpenGL 3.2) 7455 provide explicit control of the multisample mask. This mask is 7456 respected for path rendering. 7457 7458 60. Does creating multiple instances of path objects from the same 7459 glyph in the same font face "waste memory"? What about copies 7460 of objects created with glCopyPathNV? 7461 7462 RESOLVED: This is an implementation issue, but it is reasonable 7463 to expect that copies of path objects created with glCopyPathNV 7464 will share their outline data on a copy-on-write basis. This is 7465 true even if a path object is copied and its path parameters 7466 are modified (but not the path commands and coordinates). 7467 7468 It is also reasonable to expect that path objects created with 7469 glPathGlyphsNV may use copies if there are replicated character 7470 codes. While glPathGlyphRangeNV isn't subject to replicated 7471 character codes, if two or more character codes share the same 7472 glyph, it would be reasonable to expect the implementation might 7473 share the outline data. 7474 7475 It's always possible to use glPathSubCommandsNV or 7476 glPathSubCoordsNV to modify the path commands and/or coordinate 7477 data so then sharing will have to be broken. 7478 7479 61. Why does glPathGlyphsNV (and hence glPathGlyphRangeNV as well) 7480 not disturb path objects that already exist in the range of path 7481 objects to be created? 7482 7483 RESOLVED: This facilitates a strategy for supporting multiple 7484 font names specified in preferential order. 7485 7486 An application can do something like: 7487 7488 GLint firstPathName = glGenPathsNV(256); 7489 const GLfloat emScale = 2048; 7490 glPathGlyphRangeNV(firstPathName, GL_SYSTEM_FONT_NAME_NV, 7491 "Helvetica", GL_NONE, 0, 256, emScale); 7492 glPathGlyphRangeNV(firstPathName, GL_SYSTEM_FONT_NAME_NV, 7493 "Arial", GL_NONE, 0, 256, emScale); 7494 glPathGlyphRangeNV(firstPathName, GL_STANDARD_FONT_NAME_NV, 7495 "Sans", GL_NONE, 0, 256, emScale); 7496 7497 This ensures that path object names /firstPathName/ through 7498 /firstPathName/+255 will be loaded with the glyphs from Helvetica, 7499 Arial, or the guaranteed-present Sans font face, in that order 7500 of preference. 7501 7502 This is consistent with the CSS font-family property used in 7503 web standards, including SVG. 7504 7505 62. Why are the angles for the arc path commands specified with 7506 degrees (instead of radians)? 7507 7508 RESOLVED: Using degrees is consistent with OpenGL's existing 7509 glRotatef, glRotated, and gluPerspective commands. 7510 7511 Using degrees for angles is also consistent with the conventions 7512 of the PostScript, SVG, and OpenVG commands upon which the arc 7513 path commands are based. 7514 7515 Using degrees (90 degrees, 30 degrees, 45 degrees) also allows 7516 important angles be represented exactly with integer values. 7517 This is relevant for compact coordinate formats and paths defined 7518 by strings. 7519 7520 63. Should UTF-8 and UTF-16 be supported for arrays of path names? 7521 7522 RESOLVED: Yes. 7523 7524 64. What order should the arguments be listed when a array of 7525 path objects with typed elements and a base are specified? 7526 7527 RESOLVED: 7528 7529 1) sizei count, 7530 2) enum pathNameType, 7531 3) const void *paths, 7532 4) uint pathBase 7533 7534 The standard OpenGL parameter pattern is count/type/array. 7535 Examples of this are glDrawElements and glCallLists. 7536 (More generally the pattern is count/format/type/array.) 7537 7538 Having the pathBase parameter last matches the precedent set by. 7539 glDrawElementsBaseVertex where the base vertex value follows 7540 the list of element indices. Hence the pattern 7541 count/type/array/base. 7542 7543 The basevertex parameter to glDrawElementsBaseVertex is typed 7544 GLint; the pathBase parameter is typed GLuint. GLuint makes 7545 sense to avoid useless signed/unsigned mismatch warnings from 7546 C compilers when most values passed to pathBase parameters are 7547 likely to be from GLuint variables. When GLuint and GLint are 7548 both 32-bit data types, the choice is not consequential. 7549 7550 Commands that use this order are glStencilFillPathInstancedNV, 7551 glStencilStrokePathInstancedNV, glCoverFillPathInstancedNV, 7552 glCoverStrokePathInstancedNV, glGetPathMetricsNV, and 7553 glGetPathSpacingNV. 7554 7555 65. What order should the arguments be listed when a range of 7556 path objects is specified? 7557 7558 RESOLVED: 7559 7560 1) uint firstPath, 7561 2) sizei count 7562 7563 The glDeletePathsNV command and GetPathMetricRangeNV query use 7564 this order. 7565 7566 glDeleteLists uses this same order. 7567 7568 66. Where does the UTF-8 and UTF-16 specification language come from? 7569 7570 See the RFC "UTF-8, a transformation format of ISO 10646": 7571 7572 http://tools.ietf.org/html/rfc3629 7573 7574 See the RFC "UTF-16, an encoding of ISO 10646": 7575 7576 http://tools.ietf.org/html/rfc2781 7577 7578 The intent of the specification language is to match these RFCs. 7579 7580 67. How does the GL_BOUNDING_BOX_OF_BOUNDING_BOXES_NV cover mode 7581 work for glCoverFillPathInstancedNV and glCoverStrokePathInstancedNV? 7582 7583 RESOLVED: The command computes the bounding box of all the 7584 path's bounding boxes. (This can be too conservative for an 7585 arbitrarily arranged collection of path objects but works well 7586 enough for glyphs in line of text.) 7587 7588 This bounding box has a consistent counterclockwise winding 7589 order no matter what path objects are listed. This property 7590 is a combination of how glRectf works and how the parameters to 7591 glRectf are computed. 7592 7593 The object-space z (depth) is always zero. (This behavior is 7594 a consequence of the primitive being emitted by glRectf.) The 7595 matrix elements in the Z row (if such a row exists) of the 7596 transforms specified for glCoverFillPathInstancedNV and 7597 glCoverStrokePathInstancedNV is ignored. 7598 7599 Programmers are cautioned that this could result in the 7600 covering geometry being view-frustum culled if the programmer 7601 is not careful when using 3D transformTypes (GL_TRANSLATE_3D_NV, 7602 GL_AFFINE_3D_NV, GL_TRANSPOSE_AFFINE_3D_NV). To guard against 7603 this mishap, consider something such as the following: 7604 7605 glMatrixPushEXT(GL_PROJECTION); 7606 glScalef(1,1,0); 7607 glCoverFillPathInstancedNV(...); 7608 glMatrixPopEXT(GL_PROJECTION); 7609 7610 This essentially forces the clip-space Z to be zero which will 7611 never be clipped by the near or far view-frustum clip planes. 7612 7613 If depth testing is desired, perform the depth testing during the 7614 "stenciling" step so that depth testing is unnecessary during the 7615 "covering" step done by the glCoverFillPathInstancedNV command. 7616 7617 68. What happens when the radius of a circular arc command is 7618 negative? 7619 7620 UNRESOLVED: The intent is to match the behavior of the PostScript 7621 circular arc commands (arc, arcn, arct). Unfortunately the 7622 PostScript specification is not entirely clear about how negative 7623 radius is handled. 7624 7625 Table 5.arcParameterSpecialization has absolute values (abs) 7626 computed for the rv and rh columns. 7627 7628 However, the points A and B (used for arc and arcn) are computed 7629 with c[2] directly (without an absolute value). 7630 7631 This computation looks consistent with Ghostscript's behavior 7632 for arct: 7633 7634 dist = abs(c[4] * num/denom) 7635 l0 = dist/sqrt(dot(d0,d0)) * c[4]/abs(c[4]) 7636 l2 = dist/sqrt(dot(d2,d2)) * c[4]/abs(c[4]) 7637 7638 Could this simply be: 7639 7640 dist = c[4] * num/denom 7641 l0 = dist/sqrt(dot(d0,d0)) 7642 l2 = dist/sqrt(dot(d2,d2)) 7643 7644 Probably. 7645 7646 This really needs testing and comparison with a PostScript 7647 implementation to make sure the specified equations really match 7648 PostScript's implemented behavior. 7649 7650 69. What happens when the two angles (c[2] and c[3]) for a circular 7651 arc command (GL_CIRCULAR_CCW_ARC_TO_NV or 7652 GL_CIRCULAR_CW_ARC_TO_NV) create 1 or more full revolutions? 7653 7654 UNRESOLVED: The intent is to match the behavior of the PostScript 7655 circular arc commands (arc and arcn). 7656 7657 PostScript specifies that "If angle2 is less than angle1, it is 7658 increased by multiples of 360 [degrees] until it becomes greater 7659 than or equal to angle1. No other adjustments are made to the 7660 two angles. In particular, if the difference angle2-angle1 7661 exceeds 360 [degrees], the resulting path will trace portions 7662 of the circle more than once." 7663 7664 The current equations based on an end-point partial elliptical arc 7665 parameterization achieve this. Extra parametric behavior would be 7666 necessary to trace a circle multiple times. The current equations 7667 in Table 5.pathEquations do not capture this (but should). 7668 7669 This needs to be thought through carefully to make sure stroking, 7670 particularly when dashed, is handled correctly. 7671 7672 70. PostScript generates a limitcheck error when numbers are 7673 encountered that exceed the implementation limit for real numbers. 7674 Should the PostScript grammar treat such situations as a parsing 7675 error? 7676 7677 RESOLVED: No, it's not a parsing error, but the results in 7678 such a situation are likely to be undefined. 7679 7680 This paragraph in Section 5.X.1 ("Path Specification") applies 7681 which begins "If a value specified for a coordinate (however 7682 the coordinate is specified) or a value computed from these 7683 coordinates (as specified in the discussion that follows) 7684 exceeds the implementation's maximum representable value for a 7685 single-precision floating-point number, ..." 7686 7687 The PostScript's notion of a limitcheck error doesn't nicely 7688 correspond to a parsing error. And PostScript's notion of "the 7689 implementation limit for real numbers" (likely double precision) 7690 might not correspond to the GL's notion of floating-point 7691 (typically single precision). 7692 7693 The PostScript notion of a limitcheck on numeric range is 7694 particularly hard to enforce with relative commands where the 7695 limitcheck might not occur until all the relative offsets are 7696 applied, something which isn't really part of parsing. 7697 7698 What an actual implementation does may vary but a likely 7699 implementation approach is generate an IEEE infinity value when 7700 single-precision floating-point range is exceeded. This will 7701 generate undefined rendering behavior. 7702 7703 SVG doesn't offer guidance in its specification when coordinate 7704 values exceed the representable range of floating-point. 7705 Presumably such range overflows result in implementation-dependent 7706 undefined rendering behavior too. 7707 7708 71. What happens when the radius of a OpenVG-style partial elliptical 7709 arc commands is negative? 7710 7711 RESOLVED: The absolute value of the radius is used for 7712 the OpenVG-style arc commands GL_SMALL_CCW_ARC_TO_NV, 7713 GL_RELATIVE_SMALL_CCW_ARC_TO_NV, GL_SMALL_CW_ARC_TO_NV, 7714 GL_RELATIVE_SMALL_CW_ARC_TO_NV, GL_LARGE_CCW_ARC_TO_NV, 7715 GL_RELATIVE_LARGE_CCW_ARC_TO_NV, GL_LARGE_CW_ARC_TO_NV, and 7716 GL_RELATIVE_SMALL_CW_ARC_TO_NV. 7717 7718 Table 5.arcParameterSpecialization specifies an absolute value 7719 (abs) in the rh and rv entries of all these commands. 7720 7721 The OpenVG specification is clear on this point in section 8.4 7722 ("Elliptical Arcs") saying "Negative values of [radii] rh and 7723 rv are replaced with their absolute values." 7724 7725 72. What should happen for a stroked subpath that is zero length? 7726 7727 UNRESOLVED: Not sure yet. 7728 7729 SVG gives this advice: 7730 7731 http://www.w3.org/TR/SVG11/implnote.html#PathElementImplementationNotes 7732 7733 Probably need to check what other path renders, particularly 7734 PostScript do in this situation. Requires testing actual 7735 implementations because the specifications are not clear. 7736 7737 73. Why have the GL_PATH_CLIENT_LENGTH_NV path parameter? 7738 7739 RESOLVED: This supports SVG's pathLength attribute used to 7740 calibrate distance-along-a-path computations. 7741 7742 This applies to dashing a stroked segment, but does NOT 7743 apply to the lengths returned by the glGetPathLengthNV and 7744 glPointAlongPathNV queries. 7745 7746 The client length just applies to dashing because having a 7747 client length that is different from the GL's computed length 7748 for a path may greatly affect the dashing pattern. The client 7749 knows the path's client length, but the GL doesn't unless the 7750 client state is available to the GL when dashing a stroked path. 7751 7752 It's better to have the client send the client path length 7753 unconditionally than require the client to query the GL's computed 7754 path length ahead of any sending of a rescaled version of the 7755 dash offset or dash array. 7756 7757 For the queries, presumably the client can perform the necessary 7758 scaling by the client length itself if that's desirable. 7759 7760 74. Should there be a query for GL_PATH_END_CAPS_NV and 7761 GL_PATH_DASH_CAPS_NV? 7762 7763 RESOLVED: No. You have to query GL_PATH_INTIAL_END_CAP_NV or 7764 GL_PATH_TERMINAL_END_CAP_NV for the each respective end cap; or 7765 query GL_PATH_INITIAL_DASH_CAP_NV or GL_PATH_TERMINAL_DASH_CAP_NV 7766 for each respective dash cap. 7767 7768 GL_PATH_END_CAPS_NV and GL_PATH_DASH_CAPS_NV are convenient 7769 for most path rendering systems that have identical initial 7770 and terminal end and dash caps, but are NOT supported by 7771 glGetPathParameteriv or glGetPathParameterfv. 7772 7773 75. What should the path format tokens for SVG and PostScript tokens 7774 be named? 7775 7776 RESOLVED: Use the abbreviated names SVG and PS respectively: 7777 GL_PATH_FORMAT_SVG_NV and GL_PATH_FORMAT_PS_NV. These names 7778 are shorter and avoid putting an Adobe trademark in a token name. 7779 7780 Future extensions might want to add version numbers to these 7781 abbreviated names (another reason to stick with short abbreviated 7782 names). 7783 7784 76. In what content (GL client or GL server) are font file names 7785 and system font names interpreted? 7786 7787 RESOLVED: The GL_STANDARD_FONT_NAME_NV and GL_SYSTEM_FONT_NAME_NV 7788 font targets map their respective font names to a font within 7789 the GL server. The GL_FILE_NAME_NV font target does the file 7790 reading in the GL client; for GLX, there needs to be GLX protocol 7791 to transfer glyphs including their kerning and metric data to 7792 the GL server. 7793 7794 77. How can the glPathSubCommandsNV command be used to append to 7795 the end of an existing path object? 7796 7797 RESOLVED: If you set the /commandStart/ parameter to 7798 glPathSubCommandsNV to be sufficiently large (greater or equal 7799 to the number of path commands in the path object suffices), 7800 that works to append commands. 7801 7802 78. Does depth offset (a.k.a. polygon offset) work when using the 7803 "stencil" and "cover" path operations? 7804 7805 RESOLVED: Yes with caveats. 7806 7807 The "stencil" path operations use the 7808 GL_PATH_STENCIL_DEPTH_OFFSET_FACTOR_NV and 7809 GL_PATH_STENCIL_DEPTH_OFFSET_UNITS_NV state set by 7810 glPathStencilDepthOffsetNV. There is no specific enable; instead 7811 set the scale and units to zero if no depth offset is desired. 7812 7813 The "cover" path operations use the polygon depth offset state if 7814 the GL_POLYGON_OFFSET_FILL enable is enabled, using the polygon 7815 offset factor and units specified for glPolygonOffset. This is 7816 because the "cover" operation (unlike the stencil operation) 7817 does rasterize a polygon primitive. 7818 7819 Depth offset is useful when a path rendered decal is applied 7820 on depth tested 3D geometry and the path rendered geometry has 7821 to be biased forward (negative bias) by polygon offset to avoid 7822 depth ambiguities. See issue #120 for details. 7823 7824 This is also useful when putting path rendered primitives into 7825 shadow maps with a positive depth bias to avoid shadow acne 7826 issues. 7827 7828 There is NOT a guarantee that the depth offset computed for a 7829 "stencil" operation will exactly match the depth offset for a 7830 "cover" operation given identical path object and transformations. 7831 The two offsets will be close but not generally exact for all 7832 generated samples. 7833 7834 79. Can fragment shaders access the facingness state during a cover 7835 operation? 7836 7837 RESOLVED: Yes, the gl_FrontFacing special variable in GLSL 7838 is available. So is the fragment.facing fragment attribute 7839 binding in NV_fragment_program2 and subsequent NVIDIA shader 7840 assembly extensions. 7841 7842 In cases where the path rendered primitive is "very edge" on the 7843 facingness fragment state may be ambiguous in extreme situations. 7844 7845 80. When are various computed path parameters re-computed? 7846 7847 RESOLVED: If the computed parameter parameters 7848 (PATH_COMMAND_COUNT_NV, PATH_COORD_COUNT_NV, 7849 PATH_DASH_ARRAY_COUNT_NV, PATH_COMPUTED_LENGTH_NV, 7850 PATH_OBJECT_BOUNDING_BOX_NV, PATH_FILL_BOUNDING_BOX_NV, and 7851 PATH_STROKE_BOUNDING_BOX_NV) are queried, the values returned 7852 always reflect the most up-to-date state of the path object. 7853 7854 This also includes when path object parameters are used in 7855 contexts such as instanced "cover" operations. 7856 7857 81. Should projective 2D path coordinates be supported? 7858 7859 RESOLVED: No. Major path rendering standards don't support 7860 projective 2D path coordinates. 7861 7862 Moreover, projective 2D path coordinates create technical 7863 problems because the projective transformation of projective 7864 2D path coordinates for cubic Bezier curves do not necessarily 7865 retain their topology (serpentine, cusp, or loop). 7866 7867 82. Should a non-dashed stroked path's coverage be the same 7868 independent of how its control points are specified? 7869 7870 RESOLVED: Yes, this is a symmetry rule mandated by the OpenXML 7871 Paper Specification. This applies to lines and Bezier curves. 7872 7873 So a cubic Bezier curve defined by control points cp0, cp1, cp2, 7874 and cp3 should generate the same stroked coverage (assuming the 7875 same stroke parameters and requiring the dash array count to be 7876 zero) as a cubic Bezier curve with control points cp3, cp2, cp1, 7877 and cp0 (so the reversed control point order). 7878 7879 XXX Unresolved if it applies to arcs. 7880 7881 83. Should character aliases used to specify path commands be returned 7882 as their character alias values or remapped to the actual token 7883 name of the command? 7884 7885 RESOLVED: Remapped. Any path commands specified with a 7886 character alias value (from Table 5.pathCommands) is returned 7887 as the command's token value instead. 7888 7889 This avoids applications calling glGetPathCommandsNV from having 7890 bugs where they handle token names but not character aliases. 7891 7892 This also makes it simpler to say "identical" when saying command 7893 sequences must match for glWeightPathsNV. Character aliases 7894 remapped to command token values makes it unambiguous that 7895 GL_LINE_TO and 'L" are the identical command. 7896 7897 84. Is there a way to use this extension to trade-off rendering performance 7898 for more effective samples per pixel to improve coverage quality? 7899 7900 RESOLVED: Yes. 7901 7902 This code demonstrates how multiple passes could accumulate 7903 coverage information in the alpha channel of the framebuffer and 7904 then a final cover pass could blend the incoming color with the 7905 accumulated coverage from the framebuffer's alpha channel. 7906 7907 // INITIALIZATION 7908 // assume stencil is cleared to zero and framebuffer alpha is clear to zero 7909 const int coveragePassesToAccumulate = 4; 7910 glEnable(GL_STENCIL_TEST); 7911 glStencilFunc(GL_NOT_EQUAL, 0x80, 0x7F); 7912 glStencilOp(GL_KEEP, GL_KEEP, GL_REPLACE); // tricky: zero 0x7F mask stencil on covers, but set 0x80 7913 glColorMask(0,0,0,1); // just update alpha 7914 7915 // M STENCIL+COVER PASSES to accumulate jittered path coverage into framebuffer's alpha channel 7916 glStencilFillPathNV(path, GL_COUNT_UP_NV, 0x7F); 7917 glCoverFillPathNV(path, GL_PATH_FILL_COVER_MODE_NV); 7918 glEnable(GL_BLEND); 7919 glBlendFunc(GL_ONE, GL_ONE); // sum up alpha 7920 glColor4f(0,0,0, 1.0/coveragePassesToAccumulate ); 7921 static const GLfloat jitters[4][2] = { 7922 {0,0}, /* various small subpixel jitter X & Y values */ 7923 }; 7924 for (i=1; i<coveragePassesToAccumulate ; i++) { 7925 glMatrixPushEXT(GL_MODELVIEW); { 7926 glMatrixTranslatef(GL_MODELVIEW, jitters[i][0], jitters[i][1], 0); 7927 glStencilFillPathNV(path, GL_COUNT_UP_NV, 0x7F); 7928 glCoverFillPathNV(path, GL_PATH_FILL_COVER_MODE_NV); 7929 } glMatrixPopEXT(GL_MODELVIEW); 7930 } 7931 7932 // FINAL COVER PASS uses accumulated coverage stashed in destination alpha 7933 glColorMask(1,1,1,1); 7934 // modulate RGB with destination alpha and then zero destination alpha 7935 glBlendFuncSeparate(GL_DST_ALPHA, GL_ZERO, GL_ZERO, GL_ZERO); 7936 glColor4f(red, green, blue, dontcare); // some color 7937 glStencilFunc(GL_EQUAL, 0x80, 0xFF); // update any sample touched in earlier passes 7938 glStencilOp(GL_KEEP, GL_KEEP, GL_ZERO); // now set stencil back to zero (clearing 0x80) 7939 glCoverFillPathInstancedNV(coveragePassesToAccumulate, 7940 GL_UNSIGNED_BYTE, "\0\0\0\0", // tricky: draw path objects path+0,path+0,path+0,path+0 7941 path, // this is that path object that is added to zero four times 7942 GL_BOUNDING_BOX_OF_BOUNDING_BOXES_NV, GL_TRANSLATE_2D_NV, jitters); 7943 7944 Assuming N passes and M samples per pixel, this approach 7945 accumulates coverage for N*M+1 grayscale levels doing N stencil 7946 operations and N+1 cover operations. 7947 7948 85. Why do the commands glGenPathsNV and glDeletePathsNV allocate 7949 contiguous ranges of path objects instead of returning an array of 7950 (possibly scattered) names and deleting an array of names? 7951 7952 RESOLVED: The expectation that path objects will be arranged 7953 as characters mapping to glyphs warrants adopting the object 7954 model of display lists. 7955 7956 glPathGlyphRangeNV, the instanced commands, and the metric and 7957 kerning queries all rely on this assumption. 7958 7959 86. What do the stencil and cover commands do if the specified path 7960 name does not refer to an existing path object? 7961 7962 RESOLVED: Do nothing (and generate no error). 7963 7964 This is useful to avoid rendering unpopulated path objects. 7965 7966 This "do nothing" behavior also applies to the instanced 7967 stencil and cover routines that are expressed in terms of 7968 glStencilFillPathNV, glStencilStrokePathNV, glCoverFillPathNV, 7969 and glCoverStrokePathNV. 7970 7971 Applications that want some "glyph is missing" for non-existent 7972 path objects can use glCopyPathNV to copy some existing path 7973 object's "glyph is missing" outline to non-existent paths. 7974 Alternatively, glPathGlyphRangeNV (or glPathGlyphsNV) can be used 7975 with the GL_STANDARD_FONT_NAME of "Missing" to populate a range 7976 (or sequence) of path objects with a standard missing glyph 7977 (typically a rectangle). (See issue #89.) 7978 7979 Queries (glGetPathParameteriv, etc.) allowing only a single path 7980 object to be specified, generate a GL_INVALID_OPERATION error 7981 if the path name does not exist. 7982 7983 glWeightPaths, glInterpolatePathsNV, and glCopyPathNV generate 7984 a GL_INVALID_OPERATION error if any of the named source paths 7985 do not exist. 7986 7987 Path commands that modify the commands, coordinates, or parameters 7988 of existing path objects (as opposed to specifying a path object 7989 completely) generate a GL_INVALID_OPERATION error if the path 7990 name does not exist. 7991 7992 87. What of this extension's per-context state should apply to 7993 glPushAttrib and glPopAttrib? 7994 7995 RESOLVED: Apply the existing conventions; see new table 6.X, 7996 "Path (state per context)". 7997 7998 The path fog generation mode applies to GL_FOG_BIT. 7999 8000 The path color generation mode and coefficients apply to 8001 GL_LIGHTING_BIT. 8002 8003 The path texture coordinate set generation modes and coefficients 8004 apply to GL_TEXTURE_BIT. 8005 8006 The path error position is not pushed or popped, following the 8007 convention of the ARB_vertex_program extension. 8008 8009 88. How should the numCoords parameter to the various path 8010 specification commands work? 8011 8012 RESOLVED: When there is also a /numCoords/ parameter, 8013 the GL_INVALID_OPERATION error is generated if the number of 8014 coordinates is not equal to the number of coordinates needed by 8015 the command's specified path command sequence. This provides 8016 a sanity check. 8017 8018 For the glPathSubCoordsNV command, there's no requirement that 8019 the range of coordinates "match up" with path command boundaries 8020 for coordinates. 8021 8022 Some consideration was given to specifically treating a value of 8023 zero for /numCoords/ by allowing the number of coordinates to 8024 be based on the command's corresponding path command sequence. 8025 This would allow an application to bypass the sanity check if 8026 the application didn't exactly know how many coordinates a path 8027 command sequence required. This was rejected because it is likely 8028 error-prone and it means when such commands are compiled into 8029 a display list or packed into GLX protocol, the path command 8030 sequence would then have the be scanned. This would make the 8031 GL client unnecessarily knowledgeable about the supported path 8032 commands. So for both "safety" and implementation reasons, 8033 the /numCoords/ value of zero is not specially interpreted; 8034 it means that the path command sequence really is expected to 8035 require zero coordinates (not generally the case except for the 8036 GL_CLOSE_PATH_NV command). 8037 8038 89. How can an application guarantee that every glyph in a range 8039 of Unicode character codes has /some/ default outline defined? 8040 8041 RESOLVED: The "Missing" name with the GL_STANDARD_FONT_NAME_NV 8042 target populates the entire sequence or range of path objects 8043 with a default outlines. 8044 8045 Example: 8046 8047 const int allOfUnicode = 1<<21; // Entire 21-bit Unicode range! 8048 const GLfloat emScale = 2048; 8049 GLuint glyphBase = glGenPathsNV(allOfUnicode); 8050 glPathGlyphRangeNV(glyphBase, 8051 GL_STANDARD_FONT_NAME_NV, "Missing", GL_NONE, 8052 0, allOfUnicode, emScale); 8053 8054 90. Does the "Missing" font name used for GL_STANDARD_FONT_NAME_NV 8055 skip or avoid character codes that Unicode designates as white 8056 space, line terminators, etc. 8057 8058 RESOLVED: The "Missing" font name populates these with a path 8059 object with the missing outline (a box) and corresponding metrics 8060 for such spacing characters and all other characters. 8061 8062 The assumption is that Unicode fonts will populate various 8063 blank space, line and paragraph terminators, and other blank 8064 or ignorable character points with appropriate null outlines 8065 and zero-width metrics. Because glPathGlyphRangeNV and 8066 glPathGlyphsNV don't re-specify existing path objects, these 8067 will be left along if the "Missing" standard font is the last 8068 font used to specify a given range of path objects. All white 8069 space and separator character codes less than 256 (the Latin-1) 8070 range will be populated by the "Serif", "Sans", and "Mono" 8071 standard fonts if specified because these guarantee the Latin-1 8072 range is populated. These are specifically U+0009..000D, U+0020, 8073 U+0085, 0x00A0 but also other blank or ignorable character points 8074 such as control characters. 8075 8076 For more information: 8077 8078 http://unicode.org/faq/unsup_char.html 8079 8080 91. What is the /emScale/ parameter to glPathGlyphRangeNV and 8081 glPathGlyphsNV for and how should it be used? 8082 8083 RESOLVED: /emScale/ exists to ensure multiple fonts, potentially 8084 with distinct font unit scales, can be scaled to a consistent 8085 scale. 8086 8087 Typically TrueType fonts are authored for 2048 font units per 8088 Em while Type1 fonts have been historically authored to 1000 8089 font units per Em. 8090 8091 Typically a good value for /emScale/ is 2048 to match the 8092 convention of TrueType. This avoid TrueType font metrics from 8093 being rescaled. 8094 8095 Setting /emScale/ to zero allows the native font units per Em 8096 to be used. Be careful because outlines of path objects for 8097 glyphs from fonts with different font units per Em will have 8098 different scales. 8099 8100 92. Should glWeightPathsNV work for a single path object? 8101 8102 RESOLVED: No, two or more paths are required to generate a 8103 weighted path. 8104 8105 Use glCopyPathNV if copying a single path object is desired. 8106 8107 glCopyPathNV copies glyph metrics and kerning information and 8108 allows arc commands while glWeightPathsNV does not. 8109 8110 While glInterpolatePathsNV can be expressed in terms of 8111 glWeightPathsNV, glCopyPathNV cannot. 8112 8113 94. What should the initial join style of a path object be? 8114 8115 RESOLVED: GL_MITER_REVERT_NV. This is consistent with the join 8116 style used by SVG, PostScript, PDF, and Cairo. 8117 8118 Note that Flash, XPS, and Qt use GL_MITER_TRUNCATE_NV instead. 8119 8120 Arguably GL_MITER_TRUNCATE_NV is a "nicer" join style because 8121 the miter does not "pop" from miter to bevel when the miter limit 8122 is exceeded; instead when the miter limit is approached and then 8123 exceeded, the miter stops growing further and simply loses its 8124 sharp tip. 8125 8126 95. What type of triangle should the GL_TRIANGULAR cap be? 8127 8128 RESOLVED: A right triangle. 8129 8130 This is consistent with the XPS specification. Other standards 8131 don't support triangular caps. 8132 8133 96. Can NV_path_rendering be implemented without *any* dependencies 8134 on system specific fonts? 8135 8136 RESOLVED: YES. 8137 8138 Say a platform had poor or unstable interfaces for accessing 8139 system specific fonts (e.g. Linux). In the case of Linux, 8140 resolution-independent fonts are typically accessed through a 8141 combination of freetype2 and fontconfig. 8142 8143 One or both of these standards may be missing from the platform 8144 or be unreliable or misconfigured. 8145 8146 In such a case, NV_path_rendering could be implemented so 8147 that the GL_SYSTEM_FONT_NAME_NV usage for glPathGlyphsNV and 8148 glPathGlyphRangeNV would never populate path object names with 8149 glyphs. 8150 8151 However the GL_STANDARD_FONT_NAME_NV usage would still be 8152 guaranteed. The GL_STANDARD_FONT_NAME_NV usage by providing 8153 the required set of pre-compiled font outlines built-in into the 8154 driver directly (using IP unencumbered font outlines such as 8155 the DejaVu fonts). 8156 8157 This design means that applications that use the approach 8158 (copied from the Overview) will work: 8159 8160 glPathGlyphRangeNV(glyphBase, 8161 GL_SYSTEM_FONT_NAME_NV, "Helvetica", GL_BOLD_BIT_NV, 8162 0, numChars, emScale); 8163 glPathGlyphRangeNV(glyphBase, 8164 GL_SYSTEM_FONT_NAME_NV, "Arial", GL_BOLD_BIT_NV, 8165 0, numChars, emScale); 8166 glPathGlyphRangeNV(glyphBase, 8167 GL_STANDARD_FONT_NAME_NV, "Sans", GL_BOLD_BIT_NV, 8168 0, numChars, emScale); 8169 8170 In this case, the two initial glPathGlyphRangeNV calls 8171 will fail to populate the range of path objects from 8172 [glyphBase,glyphBase+numChars-1] but the third call will populate 8173 the range. 8174 8175 This allows NV_path_rendering to be implemented with ZERO 8176 dependencies on the system to provide glyphs from system fonts while 8177 applications can still utilize fonts in their path rendering. 8178 8179 While this is an allowed implementation approach, actual 8180 implementations should make reasonable efforts to provide access 8181 to system fonts if possible. 8182 8183 96. What is GL_DASH_OFFSET_RESET_NV for? 8184 8185 RESOLVED: OpenVG supports the concept of a "dash phase reset" 8186 (see VG_DASH_PHASE_RESET) that controls whether or not the dash 8187 pattern (with its offset) resets at "move to" command boundaries 8188 within a path's command sequence. 8189 8190 Rather than use a boolean value (as OpenVG does), the 8191 GL_DASH_OFFSET_RESET_NV path parameter takes an enumeration 8192 consisting of GL_MOVE_TO_RESETS_NV and GL_MOVE_TO_CONTINUES_NV 8193 to be more explicit about how the dash offset reset parameter 8194 affects the dash pattern. 8195 8196 Technically, what this specification calls the "dash offset" 8197 is what OpenVG calls its "dash phase". This specification 8198 uses "dash phase" to mean what OpenVG calls "dash phase reset" 8199 because the word "reset" is built into the GL token values. 8200 8201 When there is a dash phase reset, the dash offset is set to the 8202 value of the path's GL_DASH_OFFSET_NV parameter (consistent with 8203 OpenVG). 8204 8205 97. What APIs say "dash offset" and what APIs say "dash phase" and 8206 why does this extension use "dash offset"? 8207 8208 RESOLVED: PostScript, PDF, Cairo, Qt, XPS, SVG, and Silverlight 8209 use the "dash offset" for the offset to the dash pattern, same 8210 as this extension. 8211 8212 OpenVG, Quartz 2D, Java 2D, Illustrator, and Skia use the term 8213 "dash phase" for the identical functionality. 8214 8215 OFFSET makes more sense in the OpenGL context because lots of 8216 OpenGL tokens already use OFFSET in their token names. Core 8217 OpenGL 4.0 has 16 such tokens already. 8218 8219 98. What is the motivation for glTransformPathNV? 8220 8221 RESOLVED: Sometimes a path should be stroked with a stroke width 8222 that is constant in a particular space (such as window space). 8223 8224 Once example of this is SVG 1.2 Tiny's "non-scaling stroke" 8225 property. The stroke width is supposed to be maintained after 8226 transformation into pixel space. 8227 8228 This could be implemented with this extension by transforming 8229 the path object into the appropriate space so that the user-space 8230 stroke width will match the transformed space. 8231 8232 99. Should the specification say more about how arcs are transformed? 8233 8234 UNRESOLVED: Certainly yes, but I'm not sure exactly how to 8235 specify how arcs are transformed with a suitable level of 8236 formalism. 8237 8238 I'm not clear if partial elliptical arcs can be subjected to 8239 projective transformations and remain partial elliptical arcs. 8240 I believe they can. 8241 8242 100. How is glTransformPathNV different from OpenVG's vgTransformPath? 8243 8244 RESOLVED: The two commands are similar. 8245 8246 The OpenVG 1.1 version always converts vertical and 8247 horizontal line commands to generic line to commands where as 8248 glTransformPathNV does that only if the resulting transformed 8249 line segment is no longer either vertical or horizontal in the 8250 new coordinate system. This allows cases such as 90 degree 8251 rotations or scaling without rotation to preserve the compactness 8252 of vertical and horizontal line segments. 8253 8254 In OpenVG 1.1, the VG_MATRIX_PATH_USER_TO_SURFACE matrix 8255 used by vgTransformPath is a 3x3 projective matrix where as 8256 glTransformPathNV supports up to 4x4 projective matrices. 8257 Note that the z component of any transformed coordinate is 8258 effectively discarded by glTransformPathNV so the z row and 8259 column is not consequential to the resulting transformed path. 8260 The rationale for this is to allow the same 4x4 transform matrix 8261 array used by 3D to be used by glTransformPathNV. 8262 8263 In OpenVG 1.1, the matrix is implicitly supplied by the 8264 VG_MATRIX_PATH_UER_TO_SURFACE matrix whereas in glTransformPathNV, 8265 the matrix is explicitly specified. 8266 8267 XXX Perhaps there should be a special mode that uses the 8268 modelview-projection-viewport transform implicitly? 8269 8270 101. Can you provide an example of non-scaling strokes implemented with 8271 glTransformPathNV? 8272 8273 UNRESOLVED: To be written. 8274 8275 102. What happens if a command that creates a path from existing path 8276 objects has the result path name as one of the inputs? 8277 8278 RESOLVED: This is expected to just work. The new path object 8279 is created from the existing ones, then the new path object 8280 replaces any path object with the resulting path object name. 8281 8282 103. Should glTransformPathNV support projective transformations? 8283 8284 RESOLVED: No, such projective transformations could result 8285 in path commands transitioning from non-rational to rational 8286 boundaries. 8287 8288 If points on the path boundary are generated by non-rational 8289 boundaries, the resulting transformation, assuming a 8290 non-projective transformation, also results in non-rational 8291 boundaries. 8292 8293 104. Should there be a distinct stencil function state for path 8294 stenciling? 8295 8296 RESOLVED: YES. glPathStencilFunc sets the state. How the 8297 stencil state needs to be configured for path covering is 8298 different than how the stencil function is configured typically 8299 for path stenciling. 8300 8301 For example, stencil covering might use 8302 glStencilFunc(GL_NOT_EQUAL,0,~0) while path stenciling would 8303 use GL_ALWAYS for the path stenciling stencil test. 8304 8305 However there are other situations such as path clipping where it 8306 is useful to have the path stencil function configured differently 8307 such as glPathStencilFunc(GL_NOT_EQUAL, 0x00, 0x80) or other 8308 similar path clipping test. 8309 8310 105. Is there back- and front-facing path stencil function state? 8311 8312 RESOLVED: NO. There is a single stencil function, reference 8313 value, and read mask. The path stenciling operation doesn't 8314 have a sense of front- and back-facing. 8315 8316 106. Does the path stencil function state apply always or only if 8317 stencil testing is enabled? 8318 8319 RESOLVED: Always. If you want to avoid discarding samples 8320 from this test, use the GL_ALWAYS path stencil function (which 8321 is the initial context state). 8322 8323 107. Does the glPathStencilFuncNV state affect the operation of 8324 the stencil test during path cover operations? 8325 8326 RESOLVED: NO, the path stencil state updated by 8327 glPathStencilFuncNV only affects the path stencil (not cover) 8328 operations. 8329 8330 For the path cover operations, the *normal* stencil test applies. 8331 For the stencil test to apply to path cover operations, the 8332 stencil test (GL_STENCIL_TEST) must be enabled. 8333 8334 108. Should path objects be shared among rendering contexts in the 8335 same manner as display lists and texture objects? 8336 8337 RESOLVED: Yes. 8338 8339 See the "Additions to the AGL/GLX/WGL Specifications" section. 8340 8341 Because path objects are not "bound" there are stricter 8342 serialization requirements than for "bindable" objects such as 8343 programs and textures. 8344 8345 Due to NVIDIA driver bug 1315267, path objects were not actually 8346 shared among contexts prior to Driver release 320.xx (July 2013). 8347 8348 109. Should the kerning separations be 2D offsets or 1D horizontal 8349 translations? 8350 8351 UNRESOLVED: The specification is currently written for 1D 8352 horizontal translations. 8353 8354 TrueType fonts appears to provide 1D horizontal translations 8355 for kerning. 8356 8357 However a PostScript font can contain 2D offsets for kerning. 8358 8359 Are 2D offsets really used? 2D offsets seem like an unnecessary 8360 complication when they are unlikely to be common. 8361 8362 XXX Need to study this situation further. 8363 8364 If 99.99% of fonts never use 2D offsets, it is annoying to have 8365 them for the ultra minority that might. Not sure what the real 8366 situation is... 8367 8368 Perhaps we could provide tokens to query either 1D horizontal 8369 translations or the more general 2D offsets. But how would an 8370 application know whether a font actually specified 2D offsets 8371 or not?? 8372 8373 110. What is the initial miter limit of a path object? 8374 8375 RESOLVED: 4 to match the SVG specification. See: 8376 8377 http://www.w3.org/TR/SVG/painting.html#StrokeMiterlimitProperty 8378 8379 There is a lot of variability in initial miter limit values among 8380 path rendering APIs. The SVG initial miter limit is chosen 8381 because SVG is an open, web-based standard. 8382 8383 For Cairo, the initial miter limit is 10. 8384 8385 For Direct2D, the initial miter limit is 10. 8386 8387 For Flash, the initial miter limit is 3. 8388 8389 For PostScript, the initial miter limit is 10. 8390 8391 For Qt, the initial miter limit is 2 units of the stroke width. 8392 8393 For Skia, the initial miter limit is 4. 8394 8395 111. Should initial path object state such as miter limit, stroke width, etc. 8396 be determined by "latching" per-context initial value state for 8397 these parameters? 8398 8399 UNRESOLVED 8400 8401 Possibly. That would make it easier for a particular path 8402 rendering API's conventions initial conventions be consistently used 8403 to initialize path object parameters. 8404 8405 112. Should glPathFogGenNV's GL_FRAGMENT_DEPTH mode provide a 8406 perspective-divided value? 8407 8408 RESOLVED: No, -ze is provided rather than -ze/we. 8409 8410 Providing -ze/we would not interpolate properly over the path. 8411 Typically the modelview matrix used to compute ze is affine so we 8412 will be 1.0 in such cases and the lack of division won't matter. 8413 8414 If the modelview matrix is projective, the application can choose 8415 to interpolate we as a texture coordinate with glPathTexGenNV's 8416 GL_EYE_LINEAR mode and perform the division -ze/we during fragment 8417 coloring. 8418 8419 113. How should path color and texture coordinate generation be 8420 disabled? 8421 8422 RESOLVED: For color: 8423 8424 glPathColorGenNV(colorFormat, GL_NONE, GL_NONE/*colorFormat*/, NULL); 8425 8426 For texture coordinate generation: 8427 8428 glPathTexGenNV(GL_TEXTURE_0+i, GL_NONE, 0/*components*/, NULL); 8429 8430 The coeffs array could be an arbitrary pointer because it will 8431 only be dereferenced if the genMode is GL_NONE, but NULL is a 8432 suitable value to document this fact. 8433 8434 Querying the respective coefficients after path color or texture 8435 coordinate disabling commands above should return 16 zeros. 8436 8437 114. How should path color and texture coordinate generation interact 8438 with the GL_BOUNDING_BOX_OF_BOUNDING_BOXES_NV instanced cover 8439 mode? 8440 8441 RESOLVED: The effective bounding box is the union of all the 8442 instanced bounding boxes. 8443 8444 This is useful for something such as a line of text rendered as 8445 sequence of glyph path objects where the line of text should share 8446 a common gradient tied to the bounding box of the line of text. 8447 8448 115. How do I ignore kerning when using glGetPathSpacingNV? 8449 8450 RESOLVED: Pass in 0.0 for the kerningScale parameter. 8451 8452 116. How do I query the raw kerning parameters? 8453 8454 RESOLVED: Pass in 0.0 for the advanceScale parameter and 1.0 8455 for the kerningScale parameter. 8456 8457 117. Do I need to use GL_TRANSLATE_2D_NV when getting spacing 8458 information from glGetPathSpacingNV? 8459 8460 RESOLVED: Typically GL_TRANSLATE_X_NV is fine. 8461 8462 Typically most kerned fonts (particularly TrueType fonts) using 8463 kerning offsets that are horizontal only. PostScript technically 8464 allows 2D (x,y) kerning offsets and FreeType 2's FT_Get_Kerning 8465 API also returns 2D kerning vectors. 8466 8467 To support 2D kerning vectors, glGetPathSpacingNV accepts 8468 GL_TRANSLATE_2D_NV as well as GL_TRANSLATE_X_NV. 8469 8470 For most fonts, the Y offset can be expected to be zero. 8471 8472 118. Why have the /pathParameterTemplate/ parameter to 8473 glPathGlyphRangeNV and glPathGlyphsNV? 8474 8475 RESOLVED: Path object specified from glyphs often need parameters 8476 specified on a per-font basis that are distinct from the initial 8477 path object parameters in table 6.Y. 8478 8479 Rather than force an application to respecify the path parameters 8480 of all the path objects in a range of path objects for glyphs, 8481 it is more efficient for such glyph-initialized path objects 8482 to simply use parameters from another existing path object as 8483 a template. 8484 8485 For example, the default stroke width of 1.0 might need to be 8486 respecified for every path object corresponding to a range of 8487 glyphs for rendering stroked glyphs. If the emScale for a glyph 8488 is 2048 (typical of TrueType fonts), then 1.0 is too thin to be a 8489 discernable stroke width. A value such as 10% of the Em scale (so 8490 10% of 2048 would be 20.48) is likely to be a more useful value. 8491 8492 Similarly, GL_ROUND_NV or GL_BEVEL_NV are better join styles 8493 for stroking glyphs than the standard join style initial value 8494 GL_MITER_REVERT_NV. 8495 8496 A shared dash pattern for all path objects belonging to a single 8497 set of glyphs is much easier to specify from a template path 8498 object. 8499 8500 119. Are system font names and file names for fonts case-sensitive? 8501 8502 RESOLVED: Standard font names (such as "Mono" and "Missing" 8503 are case-sensitive). System font name names and file names for 8504 fonts should match the system's policy for case-sensitivity of 8505 font names and file names respectively. 8506 8507 Linux and other Unix-like operating systems have case-sensitive 8508 file names. Windows has case-insensitive file names. Windows and 8509 FontConfig-based systems have case-insensitive system font names. 8510 8511 120. Why have PathStencilDepthOffsetNV and PathCoverDepthFuncNV? 8512 8513 RESOLVED: These functions minimize the state changes needed 8514 to depth test path rendering consisting of several co-planar 8515 path layers (as is typical of path rendering content) against 8516 conventional depth-tested 3D rendering. 8517 8518 To properly depth test path rendering against conventional 3D 8519 rendering and other path rendering, particularly when a set of 8520 paths layer upon themselves, it is necessary to pull forward 8521 slightly the depth values generated during the stenciling step. 8522 This avoids Z-fighting when drawing path rendered layers that 8523 are logically co-planar. However when covering pixels (assuming 8524 the stencil test passed during covering), we unconditionally 8525 write un-offset depth values. 8526 8527 To depth-test path rendered content in this manner, follow the 8528 following pattern: 8529 8530 Perform the following initialization: 8531 8532 // Conventional initialization for depth testing and using path rendering 8533 glEnable(GL_DEPTH_TEST); 8534 glStencilFunc(GL_NOT_EQUAL, 0, 0xFF); 8535 glStencilOp(GL_KEEP, GL_KEEP, GL_ZERO); 8536 8537 // The additional calls for depth testing of path-rendering... 8538 glPathStencilDepthOffsetNV(-0.05, -1); // push stenciled path depth values slightly closer 8539 glPathCoverDepthFuncNV(GL_ALWAYS); 8540 8541 Clear the framebuffer, including the depth buffer: 8542 8543 // Clearing 8544 glClear(GL_COLOR_BUFFER_BIT | 8545 GL_STENCIL_BUFFER_BIT | 8546 GL_DEPTH_BUFFER_BIT); 8547 8548 For each rendered path object... 8549 8550 0) Make sure stencil testing is enabled (in case it was 8551 disabled to draw prior conventional 3D objects). 8552 8553 glEnable(GL_STENCIL_TEST); 8554 8555 1) Stencil step: 8556 8557 glStencilFillPathNV(pathObj, GL_COUNT_UP_NV, 0xFF); 8558 8559 2) Cover step: 8560 8561 glCoverFillPathNV(pathObj, GL_COUNT_UP_NV, 0xFF); 8562 8563 For conventional 3D objects... 8564 8565 0) Make sure stencil testing is disabled (in case it was 8566 enabled to draw prior path rendered objects). 8567 8568 glDisable(GL_STENCIL_TEST); 8569 8570 1) Draw normally: 8571 8572 draw_3d_object_normally(); 8573 8574 With this pattern, conventional and path rendered objects can 8575 be rendered in arbitrary order. 8576 8577 The above pattern shows path filling, but path stroking works 8578 the same. 8579 8580 Notice only the initialization calls to 8581 glPathStencilDepthOffsetNV and glPathCoverDepthFuncNV are 8582 actually "different" than conventional 3D or path rendering. 8583 8584 One potential disadvantage of this approach is that other objects 8585 with nearly identical depth values to the depth values of the 8586 path rendering content may be judged to pass the depth test when 8587 technically the other object's depth values are slightly closer. 8588 This is because the path stencil depth offset is pushing path 8589 rendering depth values slightly closer. While this is possible, 8590 this occurs in situations where the proper occlusion was nearly 8591 ambiguous because the depth values between the other object and 8592 the path rendering are so close. 8593 8594 121. What if the disadvantage of depth values having to be offset closer 8595 is deemed unacceptable (this will be rare). 8596 8597 RESOLVED: If 100% exact depth occlusion is crucial to the 8598 application, this can be achieved at some cost be stenciling 8599 a planar conservative bounding region for the path object into 8600 the stencil buffer, depth testing the rendering of this plane. 8601 This depth-tested plane region should not perform color writes 8602 but should set the most-significant bit of the stencil buffer 8603 (for an 8-bit stencil buffer, done with GL_REPLACE of 128). 8604 Then path rendering, with depth testing DISABLED, can use 8605 the glPathStencilFunc to discard stencil values without the 8606 most-significant bit set. Finally the plane region must 8607 be redrawn again to clear any stencil values left with the 8608 most-significant bit set. This approach essentially uses the 8609 depth plane region as a depth-tested proxy for the proper depth 8610 values for the path rendering. 8611 8612 122. How should the path stencil depth offset be described? 8613 8614 RESOLVED: The function is named glPathStencilDepthOffsetNV and 8615 the query tokens are GL_PATH_STENCIL_DEPTH_OFFSET_FACTOR and 8616 GL_PATH_DEPTH_OFFSET_UNITS. 8617 8618 Note that "polygon offset" does not appear in the name. Polygon 8619 offset isn't appropriate in the context of path rendering because 8620 paths aren't technically polygon primitives. The term "depth 8621 offset" is the actual name of the functionality that offsets 8622 depth values of polygons (the name of section 3.6.4 specifying 8623 glPolygonOffset is actually titled "Depth Offset"). 8624 8625 There's no perfect attribute category of state for path stencil 8626 depth offset factor and units to belong so the "polygon" category 8627 just like the polygon offset state. 8628 8629 123. Does glPointAlongPathNV have anything to do with the path's 8630 dashing state? 8631 8632 RESOLVED: No. 8633 8634 The arc length computation necessary for glPointAlongPathNV 8635 computes the arc length along the path (really a subpath) but 8636 ignores any gaps created by the dash pattern. 8637 8638 Knowing the dash count, pattern, offset, and reset state, you 8639 could adjust the distance passed to glPointAlongPathNV to account 8640 for dashing gaps, but this is something the application must do. 8641 8642 124. Should PostScript user path parser enforce the same error 8643 conditions as PostScript? 8644 8645 RESOLVED: No. 8646 8647 Section 4.6.1 (User Path Construction) in the PostScript Language 8648 Reference Manual explains user paths. 8649 8650 The section includes some restrictions. The "ucache" operator 8651 is optional but must be the first operator in a user path. 8652 The "setbbox" operator is required. The next operator must be an 8653 "absolute positioning operator (moveto, arc, or arcn)." 8654 8655 The grammar in 5.X.1.2.2 (PostScript Path Grammar) does not 8656 enforce these restrictions. In particular, the operators can 8657 appear in any order and none are required. 8658 8659 The rationale for this relaxed behavior is: 1) to make the 8660 parser easier to specify, 2) make the specification of a path 8661 object through a PostScript path grammar more consistent with 8662 specifying a path using glPathCommandsNV, and 3) not require 8663 specification of a user path bounding box that isn't relevant 8664 in the context of OpenGL rendering. 8665 8666 If a path command is used without a prior absolute positioning 8667 command, the initial position is assumed to be (0,0). So a string 8668 such as "40 50 lineto" would draw a line from (0,0) to (40,50). 8669 8670 125. The ISO PDF 32000 standard has additional path construction 8671 operators for rectangles and cubic Bezier curves with duplicated 8672 first or last control points. Should this extension have 8673 first-class path commands for these operators? 8674 8675 RESOLVED: Yes. These PDF operators correspond 8676 to the path commands GL_DUP_FIRST_CUBIC_CURVE_TO_NV, 8677 GL_DUP_LAST_CUBIC_CURVE_TO_NV, and GL_RECT_NV, corresponding to 8678 the operators "v", "y", and "r" respectively. 8679 8680 See Table 59 (Path Construction Operators) in the PDF 32000-1:2008 8681 specification (page 133). See: 8682 8683 http://www.adobe.com/devnet/acrobat/pdfs/PDF32000_2008.pdf [[ free version ]] 8684 http://www.iso.org/iso/iso_catalogue/catalogue_ics/catalogue_detail_ics.htm?csnumber=51502 8685 8686 These additional operators make path specification and storage 8687 more compact, help editing, and better semantically match the 8688 important PDF standard. PDF supports just absolute versions of 8689 these commands so relative versions are NOT provided. 8690 8691 The "m", "l'", "c", and "h" operators correspond to GL_MOVE_TO_NV, 8692 GL_LINE_TO_NV, GL_CUBIC_CURVE_TO_NV, and GL_CLOSE_PATH_NV 8693 respectively. 8694 8695 There is not a string grammar for glPathStringNV to encode 8696 PDF commands. 8697 8698 126. What is the GL_RESTART_PATH_NV path command for? 8699 8700 RESOLVED: It is useful to be able to concatenate path 8701 command sequences as if they are independent from each other. 8702 The GL_RESTART_PATH_NV provides a way to reset the state of 8703 path command processing back to its initial state when the first 8704 command of a path's command sequence is processed. 8705 8706 So you could use glPathSubCommandsNV to append a path sequence 8707 to an existing path object's sequence. By first appending a 8708 GL_RESTART_PATH_NV command, you make sure the result is consistent 8709 with drawing the path sequences independently. 8710 8711 Specifically, /sp/, /cp/ and /pep/ are re-initialized to (0,0) when 8712 a GL_RESTART_PATH_NV path command is encountered. 8713 8714 Additionally, this restart also has the effect of causing 8715 CIRCULAR_TANGENT_ARC_TO_NV to NOT draw an initial tangent line 8716 segment. So if you want to draw multiple independent circular 8717 arcs using the GL_CIRCULAR_TANGENT_ARC_TO_NV parameterization, 8718 you need a GL_RESTART_PATH_NV command just prior to each 8719 GL_CIRCULAR_TANGENT_ARC_TO_NV command. In this respect, 8720 GL_RESTART_PATH_NV is different from a GL_MOVE_TO_NV command to 8721 (0,0). 8722 8723 The GL_RESTART_PATH_NV does not by itself reset the dash 8724 offset, but if the path's GL_PATH_DASH_OFFSET_RESET_NV is set 8725 to GL_MOVE_TO_RESETS_NV, GL_RESTART_PATH_NV (as with any command 8726 that updates /sp/) will reset the dash offset. 8727 8728 127. <<Bogus issue removed.>> 8729 8730 128. How does the "stencil" and "cover" steps operate on a multisample 8731 framebuffer when the GL_MULTISAMPLE enabled is disabled? 8732 8733 RESOLVED: The "stencil" step respects the disabled GL_MULTISAMPLE 8734 enable and rendered aliased stencil coverage. 8735 8736 When MULTISAMPLE is disabled, "stencil" step coverage 8737 determinations are made at the pixel center. (This will result 8738 in an aliased appearance for the determined path coverage so 8739 stenciling and covering paths with GL_MULTISAMPLE disabled isn't 8740 recommended.) 8741 8742 All the (non-masked) stencil samples for the pixel are considered 8743 covered or not based on the pixel center's coverage determination. 8744 For example, if MULTISAMPLE is disabled for a multisample 8745 buffer and the pixel center is determined covered during 8746 glStencilFillPathNV or glStencilStrokePathNV (or instanced 8747 versions), all the samples are updated (INCR/DECR/INVERT for 8748 filling or REPLACE for stroking). 8749 8750 "non-masked" means that the glSampleMaskIndexedNV state applies. 8751 8752 The "cover" step also respects the disabled GL_MULTISAMPLE enable. 8753 8754 To maintain rendering invariances in order to guarantee 8755 conservative covering, both the "stencil" and "cover" step should 8756 be rendered with the same GL_MULTISAMPLE enable state. 8757 8758 129. What happens when a command or query takes a sequence of path object 8759 names and a named path object does not exist? 8760 8761 RESOLVED: The non-existent path is "skipped" in instanced 8762 commands such as glStencilFillPathInstancedNV (and the transform 8763 for the particular path name is skipped over). Notice the 8764 pseudo-code for these instanced path commands uses glIsPathNV 8765 to test if each path name exists. 8766 8767 Queries cannot simply ignore the invalid name as they return 8768 information. glGetPathSpacingNV treats the non-existent name as 8769 having zero space. glGetPathMetricRangeNV and GetPathMetricsNV 8770 return metric values of -1 for the metrics of non-existent 8771 path objects (as also occurs if the path object lacks metrics 8772 information). 8773 8774 No GL error is generated due to a non-existent path name. 8775 8776 (Early implementation prior to NVIDIA's OpenGL 4.3 implementation 8777 might crash or generate a GL_INVALID_OPERATION error. 8778 The behavior was a bug.) 8779 8780 130. Should glCallLists be extended to take the GL_UTF8_NV and 8781 GL_UTF16_NV date types? 8782 8783 RESOLVED: No. That might make sense in another extension since it 8784 would allow complex Unicode text to be rendered by glCallLists. 8785 8786 (An early version of this specification did call for supporting 8787 UTF sequences for glCallLists, but that behavior was never 8788 implemented and is now purged from the specification.) 8789 8790 131. Should glPathTexGenNV and glPathColorGenNV transform the plane 8791 equations for GL_EYE_LINEAR by the inverse transpose modelview 8792 matrix? 8793 8794 RESOLVED: Yes. 8795 8796 This matches the way glTexGenfv operates with GL_EYE_LINEAR 8797 texgen planes. This allows the eye plane equations to be 8798 specified in the current object-space. 8799 8800 (Early specifications, prior to revision 9, incorrectly failed 8801 to specify this transformation.) 8802 8803 132. Should new commands and queries be used to support generating 8804 GLSL fragment inputs? 8805 8806 RESOLVED: Add a new command to specify the path fragment 8807 input generation state but use the API introduced by the 8808 ARB_program_interface_query extension specification to query 8809 back the path fragment input generation state. 8810 8811 The new command is glProgramPathFragmentInputGenNV. Given a GLSL 8812 program object and a GL_FRAGMENT_INPUT_NV resource location, 8813 this command provides the linear function state with which to 8814 generate the specified interpolated fragment input. 8815 8816 The new GL_FRAGMENT_INPUT_NV token names the path fragment input 8817 resource. 8818 8819 The new program resource properties GL_PATH_GEN_MODE_NV, 8820 GL_PATH_GEN_COEFF_NV, and GL_PATH_GEN_COMPONENTS_NV name the 8821 path fragment input generation resources. 8822 8823 133. How should this specification interact with a Core profile context? 8824 8825 RESOLVED: See "Dependencies on Core Profile and OpenGL ES" 8826 section. 8827 8828 In summary: 8829 8830 Enough modelview and projection functionality from 8831 EXT_direct_state_access is required to make transformations of 8832 paths possible. 8833 8834 Fragment varyings of GLSL programs can be interrogated and these 8835 can be generated. 8836 8837 Exclude fixed-function fragment varying commands, queries, 8838 and GLSL built-in variables. 8839 8840 134. Existing path rendering systems typically specify 2D transforms. 8841 Such transforms are cheaper to load, concatenate, and render with. 8842 How are 2D transforms specified? 8843 8844 RESOLVED: Add new matrix commands. 8845 8846 Driver implementations can exploit these more compact matrix 8847 representations to accelerate path rendering where often matrix 8848 changes are frequent relative to the amount of rendering. The 8849 concatenation of two 3x2 matrices is 24 multiply-add operations; 8850 while the concatenation of two 4x4 matrices is 64 multiply-add 8851 operations, so requiring over 2.5x more math operations. 8852 8853 This table shows the correspondence between other path rendering 8854 APIs and the corresponding matrix routine so we need only populate 8855 the range of matrix representations used by major path rendering 8856 standards. 8857 8858 Standard Type Component order Corresponding GL load command 8859 --------------- ---------------- --------------- ----------------------------- 8860 Direct2D D2D_MATRIX_3X2_F [0,2,4] glMatrixLoad3x2fNV 8861 [1,3,5] 8862 Cairo cairo_matrix_t [0,2,4] glMatrixLoad3x2fNV 8863 [1,3,5] 8864 Skia SkMatrix [0,1,2] glMatrixLoadTranspose3x3fNV 8865 [3,4,5] 8866 [6,7,8] 8867 SkScalar [6] [0,2,4] glMatrixLoad3x2fNV 8868 [1,3,5] 8869 Qt QMatrix [0,2,4] glMatrixLoad3x2fNV 8870 [1,3,5] 8871 OpenVG VGfloat [9] [0,3,6] glMatrixLoad3x3fNV 8872 [1,4,7] 8873 [2,5,8] 8874 AGM BRVCoordMatrix [0,2,4] glMatrixLoad3x2fNV 8875 [1,3,5] 8876 Ghostscript gs_matrix [0,2,4] glMatrixLoad3x2fNV 8877 [1,3,5] 8878 8879 Along with the glMatrixLoad*NV commands, there are corresponding 8880 glMatrixMult*NV commands. 8881 8882 Queries should be rare so the existing queries returning all 16 8883 values of a current matrix are sufficient. 8884 8885 135. Does the "layout(location=2)", etc. syntax work for fragment inputs? 8886 8887 RESOLVED: Yes, assuming separate shader objects support. 8888 The ARB_separate_shader_objects functionality (made core in 8889 OpenGL 4.1) supports layout qualifiers to annotate locations on 8890 arbitrary fragment shader inputs. 8891 8892 Example: A fragment shader could include the statement: 8893 8894 layout(location=4) in vec4 eye_space; 8895 8896 This would ensure that the location queried with 8897 GetProgramResourceLocation(program, GL_FRAGMENT_INPUT_NV, 8898 "eye_space") will return 4. 8899 8900 136. What data types work with glProgramPathFragmentInputGenNV? 8901 8902 RESOLVED: Just floating-point scalars and vectors. 8903 8904 Half-precision and double-precision varyings considered 8905 floating-point, and hence are allowed, but implementations may 8906 interpolate double-precision at single-precision. 8907 8908 Matrix, array, structure, boolean, and integer data types are 8909 not supported. 8910 8911 Generated values are intrinsically floating-point (they are 8912 basically interpolants) hence the floating-point restriction. 8913 8914 Restricting the generation to floating-point scalars and vectors 8915 shouldn't be a hardship. 8916 8917 137. How can a fragment varying (or fragment input for GLSL) be driven 8918 to a constant value? 8919 8920 RESOLVED: Use the GL_CONSTANT genMode for this. 8921 8922 Example: This command: 8923 8924 GLfloat float4_constant[4] = { 1, 2, 3, 4 }; 8925 glPathTexGenNV(GL_TEXTURE0, GL_CONSTANT, 4, float4_constant); 8926 8927 is equivalent to: 8928 8929 GLfloat coefficients[3*4] = { 0,0,1, 0,0,2, 0,0,3, 0,0,4 }; 8930 glPathTexGenNV(GL_TEXTURE0, GL_OBJECT_LINEAR, 4, coefficients); 8931 8932 In the latter form, the zeros in the coefficients array would be 8933 multiplied by the object-space X and Y so would always evaluate 8934 (s,t,r,q) to (1,2,3,4) just as the former GL_CONSTANT version 8935 would. 8936 8937 GL_CONSTANT also works with glPathColorGenNV and 8938 glProgramPathFragmentInputGenNV. 8939 8940 138. What happens to fragment inputs that are not configured by 8941 glProgramPathFragmentInputGenNV? 8942 8943 RESOLVED: Such variables are forced to constant zero. 8944 8945 The default genMode is GL_NONE and this results in a fragment 8946 input outputting sc, tc, rc, and qc for its first, second, 8947 third, and fourth components respectively. These values 8948 are all zero in the case of fragment input generation with 8949 glProgramPathFragmentInputGenNV (whereas with glPathTexGenNV, 8950 they take on the value of the respective texture coordinate 8951 set's current values). 8952 8953 139. The fragment input generation state includes floating-point coefficients 8954 but the ARB_program_interface_query extension provides no way 8955 to query floating-point state so how can this state be queried? 8956 8957 RESOLVED: This extension adds glProgramResourceIndexfvNV to 8958 allow floating-point program resource state to be queried. 8959 8960 140. Can a program object with a vertex shader be used to cover paths? 8961 8962 RESOLVED: Yes. 8963 8964 141. Is there a technical explanation of this extension beyond the 8965 specification itself? 8966 8967 RESOLVED: Yes, check out the SIGGRAPH Asia 2012 paper 8968 "GPU-accelerated Path Rendering": 8969 8970 https://dl.acm.org/citation.cfm?id=2366145.2366191 8971 http://developer.download.nvidia.com/devzone/devcenter/gamegraphics/files/opengl/gpupathrender.pdf 8972 8973 There is an accompanying annex to this paper titled "Programming 8974 NV_path_rendering": 8975 8976 http://developer.nvidia.com/sites/default/files/akamai/gamedev/files/nvpr_annex.pdf 8977 8978 142. Should conic sections (rational quadratic Bezier segments) be supported? 8979 8980 RESOLVED: Yes, Skia supports these. 8981 8982 The GL_CONIC_CURVE_TO_NV and GL_RELATIVE_CONIC_CURVE_TO_NV path 8983 commands take five path coordinates: 8984 8985 x1,y1, x2,y2, w 8986 8987 The first two pairs of coordinates are control points similar to 8988 the GL_QUADRATIC_CURVE_TO_NV and GL_RELATIVE_QUADRATIC_CURVE_TO_NV 8989 path commands. The fifth coordinate "w" is a homogeneous coordinate 8990 that applies to the middle (extrapolating) control point. 8991 8992 Skia parameterizes its SkPath::kConic_Verb conic curve path 8993 command in the same manner. (See Skia's SkConic class in 8994 skia/include/core/SkGeometry.h for details.) 8995 8996 When the "w" is 1.0, the behavior of the GL_CONIC_CURVE_TO_NV and 8997 GL_RELATIVE_CONIC_CURVE_TO_NV commands behave identically to the 8998 GL_QUADRATIC_CURVE_TO_NV and GL_RELATIVE_QUADRATIC_CURVE_TO_NV 8999 commands respectively; this case corresponds to a parabolic segment. 9000 9001 When "w" is less than 1.0, the resulting conic is a partial 9002 elliptical arc. When "w" is greater than 1.0, the resulting 9003 conic is a hyperbolic arc. 9004 9005 See Table 5.pathEquations (Path Equations) for the specific 9006 rational quadratic Bezier equations for the GL_CONIC_CURVE_TO_NV 9007 and GL_RELATIVE_CONIC_CURVE_TO_NV path commands. 9008 9009 The GL_RELATIVE_CONIC_CURVE_TO_NV path command is not supported 9010 by Skia but is trivial to support and maintains a symmetry that 9011 general-purpose path commands should have relative versions. 9012 9013 143. What happens when the "w" (5th coordinate) of a conic section 9014 path command is non-positive? 9015 9016 RESOLVED: Match Skia's behavior and treat the path command as 9017 a line segment from the current control point to the interpolating 9018 control point (x2,y2). 9019 9020 At the limit when w nears zero, partial elliptical arcs would 9021 become a line segment. 9022 9023 144. Should "smooth" conic sections be supported similar to 9024 GL_SMOOTH_QUADRATIC_CURVE_TO_NV? 9025 9026 RESOLVED: No. Conceptually, there's no problem supporting 9027 smooth conic sections, however no standard supports smooth conic 9028 sections to justify the feature. 9029 9030 145. Should there be a "Character alias" for the absolute and relative 9031 conic curve commands? 9032 9033 RESOLVED: Yes, "W" for GL_CONIC_CURVE_TO_NV and "w" for 9034 GL_RELATIVE_CONIC_CURVE_TO_NV are appropriate. 9035 9036 146. Should there be a rational cubic path command? 9037 9038 RESOLVED: No way! 9039 9040 Rational cubic segments are subject to topological transitions 9041 when transformed projectively (as is possible when a path is 9042 transformed by the--potentially projective--modelview-projection 9043 transform!). 9044 9045 147. Why are rounded rectangles supported? 9046 9047 RESOLVED: Rounded rectangles are popular in web content. The W3C's 9048 "CSS Backgrounds and Borders Module Level 3" candidate recommendation 9049 specifies rounded rectangles and they are popular in web content. 9050 9051 http://www.w3.org/TR/css3-background/ 9052 9053 Native paths commands for rounded rectangles allow such content 9054 to be specified and rasterized with less overhead than comparable 9055 specification of the same path with multiple line and arc (or 9056 conic) commands. 9057 9058 http://www.w3.org/TR/css3-background/#corners 9059 9060 148. Should multiple parameterization for rounded rectangles be 9061 supported? 9062 9063 RESOLVED: Yes. 9064 9065 Both circular and elliptical corners are supported with either 9066 uniform (all corners have the same x- and y-axis radii) or 9067 per-corner radii. 9068 9069 Also relative and absolute versions are supported (including 9070 adding an absolute version of GL_RECT_NV for completeness). 9071 9072 149. Should negative x, y, width, height, and radii parameters be allowed 9073 for rectangles and rounded rectangles? 9074 9075 RESOLVED: Yes. The formulas operate reasonably with negative values. 9076 9077 Negative values allow the winding order to be reversed. 9078 9079 GL_RECT_NV already allowed negative values. 9080 9081 150. Should the "stencil" and "cover" path operations be combined 9082 into a single command? 9083 9084 RESOLVED: Yes, these commands are commonly used in sequence and 9085 profiling shows combining the commands can provide a small but 9086 measurable CPU efficiency benefit by reducing name translation, 9087 object locking overhead, and error checking. 9088 See the commands: 9089 9090 glStencilThenCoverFillPathNV 9091 glStencilThenCoverStrokePathNV 9092 9093 These commands are specified to behave like a "stencil" command 9094 on a path followed immediately by a "cover" command on the same 9095 path. 9096 9097 There are also instanced versions: 9098 9099 glStencilThenCoverFillPathInstancedNV 9100 glStencilThenCoverStrokePathInstancedNV 9101 9102 These commands can be display listed. 9103 9104 Indeed, one advantage of the Instanced versions of the 9105 glStencilThenCover* commands is the instanced array can be copied 9106 into the display list once. While a display list optimizer 9107 could recognize this same benefit, it is simpler to be explicit 9108 that there is a single set of transform values used by both the 9109 instanced "stencil" and "cover" operations. 9110 9111 151. Should there be a way to get glyph indices for a particular font face 9112 to perform advanced text shaping? 9113 9114 RESOLVED: Yes, see glPathGlyphIndexArrayNV, 9115 glPathMemoryGlyphIndexArrayNV, and glPathGlyphIndexRangeNV. 9116 9117 Advanced text shaping APIs such as HarfBuzz and Pango generate 9118 combine text with a font face and provide a sequence of glyph 9119 indices with corresponding positions to render the text. 9120 9121 Mozilla and Google have both confirmed the requirement for this. 9122 9123 Advanced text shaping requires more knowledge of scripts and 9124 font metrics than can be expressed through NV_path_rendering. 9125 There is no interest to attempt, or even try to attempt, exposing 9126 sufficient font metrics for advanced text shaping. Instead 9127 the presumption is that one or more higher-level libraries 9128 (e.g. HarfBuzz + FreeType 2) are used to perform text shaping. 9129 9130 While glGetPathSpacingNV is useful and sufficient for providing 9131 basic kerning of Latin and other common scripts, but is 9132 well-understood to be insufficient for advanced text shaping. 9133 9134 152. Should glPathGlyphIndexRangeNV take the range of path objects 9135 as a parameter or return the base & count of path names created 9136 from the specified font's glyph indices? 9137 9138 RESOLVED: glPathGlyphIndexRangeNV operates like glGenPathsNV 9139 to first get an unassigned range of path object names based on 9140 the number of glyph indices in the font face. Then specifies 9141 the path object for every glyph index. 9142 9143 This requires returning a pair of GLuint values for the base 9144 and count. Additionally there is a return value to indicate 9145 whether and, if not why not, the path objects for the glyphs 9146 are assigned and specified. 9147 9148 153. Why were glPathGlyphIndexArrayNV and glPathMemoryGlyphIndexArrayNV 9149 added? 9150 9151 RESOLVED: Web browsers such as Chrome and other applications 9152 relying on glyph indices rely on arranging glyph indices of 9153 several fonts together so controlling the order of glyph index 9154 arrangement proves important. glPathGlyphIndexRangeNV returns 9155 a dynamically allocated range (implicitly using glGenPathsNV) 9156 and this proved not well-suited for actual use of glyph indices. 9157 9158 154. Why glPathMemoryGlyphIndexArrayNV added? 9159 9160 RESOLVED: Also web sites today very often provide server-supplied 9161 fonts via the Web Open Font Format (WOFF) standard. This means 9162 fonts are provided by font representations in system memory 9163 rather than accessed by file name or system font name. 9164 9165 155. Why is GL_FONT_NUM_GLYPH_INDICES_NV added? 9166 9167 RESOLVED: This is a relevant per-font parameter that is useful 9168 to ensure that glyphs used by glyph index know the proper bounds 9169 on the glyph indices. 9170 9171 This per-font parameter is an integer so is not scaled by the 9172 emScale. 9173 9174 156. Why does glPathMemoryGlyphIndexArrayNV take a face index? 9175 9176 RESOLVED: Implementations are likely to use FreeType 2's 9177 FT_New_Memory_Face to implement this functionality. The first 9178 face index is zero so normally zero should be passed for the 9179 face index. 9180 9181 157. If a face index for glPathMemoryGlyphIndexArrayNV corresponds to 9182 a bitmap font or otherwise isn't suitable for providing path 9183 objects, what happens? 9184 9185 UNRESOLVED: Probably GL_FONT_UNINTELLIGIBLE_NV should be 9186 returned. 9187 9188 158. Is glyph index zero special? 9189 9190 RESOLVED: According to SNFT conventions, glyph index zero 9191 corresponds to the font face's missing glyph. Therefore at 9192 least once glyph outline should always exist. 9193 9194 159. Why as GL_FONT_CORRUPT_NV renamed to GL_FONT_UNINTELLIGIBLE_NV? 9195 9196 RESOLVED: Because it is hard to distinguish between a font being 9197 corrupt and simply not being supported by the implementation. 9198 Unintelligible is less misleading and more honest about the 9199 situation. 9200 9201 160. Are there alternatives to STANDARD_FONT_FORMAT_NV? 9202 9203 RESOLVED: Not currently. There might be a need in the future 9204 to identify fonts or glyph outlines with some other token if 9205 the font does use the SNFT format. PostScript, TrueType, and 9206 OpenType font formats are all SNFT formats. The Web Open Font 9207 Format should be supportable too because it contains a magic 9208 number with which to identify the format of the binary data. 9209 9210 161. Is the memory provided by glPathMemoryGlyphIndexArrayNV referenced 9211 after the command is issued? 9212 9213 RESOLVED: No. The GL implementation is responsible for copying 9214 from the system memory buffer provided. This likely requires 9215 copying the entire buffer. 9216 9217 (Perhaps another font target to allowed referenced access to the 9218 font data may be a good idea though it would likely require all 9219 path objects specified by glPathMemoryGlyphIndexArrayNV to be 9220 deleted before freeing the memory. Referencing client system 9221 memory is generally considered taboo for GL implementations 9222 beyond the duration of a GL command or query's execution however. 9223 Copying the buffer avoids any ambiguity and provides for reliable 9224 operation, tracing, and network extensibility.) 9225 9226 162. What if glPathGlyphIndexArrayNV or glPathMemoryGlyphIndexArrayNV 9227 attempt to specify more path objects than the font supports 9228 glyph indices? 9229 9230 RESOLVED: Path objects that would correspond to glyph indices 9231 that are beyond the maximum glyph index in the font face are 9232 not disturbed. 9233 9234 For example, if a font face contains 258 glyph indices, but 9235 the numGlyphs parameter to glPathGlyphIndexArrayNV is 300, the 9236 command silently acts as if 258 glyph indices were requested. 9237 No GL error is generated in this case. Also the path objects 9238 named firstPathName+258 and beyond are not disturbed. 9239 9240 The rationale for this behavior is to avoid needless errors or 9241 complexity if an application overestimates the number of glyph 9242 indices a font has. 9243 9244 163. What concrete reasons might GL_FONT_TARGET_UNAVAILABLE_NV be 9245 generated? 9246 9247 RESOLVED: Here are some situations... 9248 9249 The Win32 API lacks a way to load a font from a file name. 9250 If FreeType 2 is unavailable (say its DLL is missing or 9251 the GL implementation simply does not support it), this 9252 would cause use of the GL_FILE_NAME_NV target to return 9253 GL_FONT_TARGET_UNAVAILABLE_NV. 9254 9255 Linux implementations for the X Window System are likely to use 9256 FontConfig to map system font names (such as "Arial") to some 9257 font file. If the FontConfig shared library is unavailable, 9258 cannot be initialized, is a very old version, or its configuration 9259 files are missing or corrupt, the GL_SYSTEM_FONT_NAME_NV font 9260 target could return GL_FONT_TARGET_UNAVAILABLE_NV. 9261 9262 These situations are possible and so applications should 9263 anticipate that GL_FONT_TARGET_UNAVAILABLE_NV might be returned 9264 but properly configured systems should not be returning this 9265 value. Developers debugging this condition should check 9266 ARB_debug_output messages for an explanation. 9267 9268 164. What path glyph specification commands support which font targets? 9269 9270 RESOLVED: 9271 9272 The FILE_NAME_NV, SYSTEM_FONT_NAME_NV, and STANDARD_FONT_NAME_NV 9273 font targets are for glPathGlyphsNV and glPathGlyphRangeNV. 9274 9275 The FILE_NAME_NV and SYSTEM_FONT_NAME_NV font targets are for 9276 glPathGlyphsNV, glPathGlyphRangeNV, glPathGlyphIndexArrayNV, 9277 and glPathGlyphIndexRangeNV. STANARD_FONT_NAME_NV does not 9278 apply to these commands because standard font name support 9279 Unicode character point access to glyphs but not glyph indices. 9280 9281 The STANDARD_FONT_FORMAT_NV font target is just for the 9282 glPathMemoryGlyphIndexArrayNV command. 9283 9284 165. Why is the GL_PATH_STROKE_BOUND_NV parameter supported? 9285 9286 RESOLVED: The path's stroke approximation bound helps the 9287 GL implementation and an application bound the amount of 9288 approximation error allowed when cubic Bezier path segments or 9289 partial elliptical arcs are stenciled. 9290 9291 Theory for offset curves indicates determining if a point is 9292 within a given offset of a cubic Bezier curve (the generating 9293 curve for the offset curve) amounts to solving a 5th degree 9294 polynomial equation. That is not tractable in real-time graphics 9295 so some approximation of the actual offset curve is assumed. 9296 9297 By comparison solve the point containment problem for a sample 9298 position with respect to the offset curve of a quadratic Bezier 9299 segment requires solving only a 3rd degree polynomial which is 9300 tractable for modern GPUs. The assumption here is that stroke 9301 point containment with respect to quadratic Bezier segments 9302 and linear segments, as well as capping and join geometry, can 9303 be tractably solved without analytical approximation (though 9304 numerical issues may still limit the accuracy at the limits of 9305 available numerical precision). 9306 9307 With this in mind, there should be some intuitive bound on 9308 the approximation error allowed. The GL_PATH_STROKE_BOUND_NV 9309 path parameter provides such an intuitive limit expressed as a 9310 percentage of the path's stroke width. 9311 9312 166. Should the radii passed to the GL_ROUNDED_RECT*_NV and 9313 GL_RELATIVE_ROUNDED_RECT*_NV support negative values? 9314 9315 RESOLVED: Yes. 9316 9317 However, the x or y radii are negated if the width or height 9318 respectively is negative. This behavior ensures that a rectangle 9319 with reversed winding can be specified (useful for cutting out 9320 rounded rectangular "holes" in paths) by simply flipping the 9321 width or height sign while leaving the radii values positive. 9322 9323 The use of the /sign/ function in the specification of the /rrect/ 9324 function enforces this behavior. 9325 9326 This is important because the GL_ROUNDED_RECT_NV and 9327 GL_ROUNDED_RECT4_NV (and relative versions) specify a single 9328 circular radius per-rectangle or per-corner respectively without 9329 providing an x & y radii. Without the /sign/ terms, it would 9330 not be possible to use the these commands and specify a reverse 9331 winding rounded rectangle. 9332 9333 Still negative values are allowed for the radii and the formula 9334 should be applied as specified. Negative radii permit "fins" 9335 and "crossed roundings" to be added rounded rectangles. 9336 9337 167. Should CLOSE_PATH_NV count as specifying the start position 9338 (sp) for the purposes of determining if the PostScript path 9339 commands CIRCULAR_CCW_ARC_TO_NV or CIRCULAR_CW_ARC_TO_NV should 9340 change sp to ncp? 9341 9342 RESOLVED: No. The PostScript semantic appears to be that 9343 a CLOSE_PATH_NV does not set the "current point" to valid. 9344 This is based on inspection of Ghostscript behavior. 9345 9346 For this reason, the "other than CLOSE_PATH_NV" phrase is placed 9347 in the paragraph describing how when these PostScript arc commands 9348 change sp. 9349 9350 168. What is the initial glProgramPathFragmentInputGenNV state for all 9351 fragment inputs? 9352 9353 RESOLVED: See the "Program Object Resource State" table. 9354 9355 The GL_PATH_GEN_MODE_NV initial state for every fragment program 9356 resource is GL_NONE. 9357 9358 The GL_PATH_GEN_COMPONENTS_NV initial state is zero for the 9359 number of path fragment input components. 9360 9361 The sixteen PATH_GEN_COEFF_NV coefficient values are initially 9362 all zero. 9363 9364 169. If glGetProgramResourceiv or glGetProgramResourcefvNV are used on 9365 fragment program resources that are not floating-point scalars 9366 are vectors, what happens? 9367 9368 RESOLVED: While glProgramPathFragmentInputGenNV cannot be used to 9369 change such program resources, their state can be queried but 9370 simply always returns the intial values. 9371 9372 The rationale for this is that implementations already have 9373 to return the initial state for fragment inputs that have 9374 not yet been specified. Also the ARB_program_interface_query 9375 specification specifies returning innocuous or invalid 9376 information in preference to generating errors when the query 9377 does not apply to the program resource. 9378 9379 Always writing back some data in the absence of an error also 9380 makes it easier to notice buffer overflow errors since they are 9381 not skipped when GL errors are generated. 9382 9383 Note that an error *should* be generated by 9384 glGetProgramResourceiv and glGetProgramResourcefvNV if 9385 GL_PATH_GEN_*_NV queries are performed on a programInterface 9386 other than GL_FRAGMENT_INPUT_NV. 9387 9388 170. Should we allow fragment input generation on half and double 9389 precision GLSL attributes? 9390 9391 RESOLVED: No, just single-precision fragment inputs can be 9392 generated. 9393 9394 Double-precision attributes only support flat interpolation and 9395 that makes no sense for paths. 9396 9397 Half-precision attributes could be supported but have 9398 no particular advantage on NVIDIA GPUs as half-precision 9399 interpolation actually happens in single-precision anyway. 9400 9401 glProgramPathFragmentInputGenNV generates GL_INVALID_OPERATION when 9402 passed a double-precision or half-precision fragment input 9403 (just as it does for any other inappropriate program resource 9404 such as a matrix). 9405 9406 171. With glProgramPathFragmentInputGenNV, what fragment input values are 9407 generated when the component would normally be the texture 9408 coordinate set component for glPathTexGenNV? 9409 9410 RESOLVED: Zero. 9411 9412 glProgramPathFragmentInputGenNV is specified in terms of PathTexGenNV 9413 but there are no fixed-function way to drive varyings. But 9414 this specification language says such under-specified varyings 9415 will be zero: "Because there is no associated texture coordinate 9416 set, the sc, tc, rc, and qc values when discussing PathTexGenNV 9417 are always zero when generating fragment input variables." 9418 9419 172. Should glProgramPathFragmentInputGenNV be able to control the 9420 path generation of "gl_" prefixed built-in variables? 9421 9422 RESOLVED: No. 9423 9424 glProgramPathFragmentInputGenNV operates on only fragment inputs 9425 that are user-defined, scalar/vector (not matrices, structures, 9426 arrays, or opaque types such as samplers), and single-precsion. 9427 9428 Built-ins such as gl_TexCoord[0], gl_Color, gl_FogFragCoord 9429 are generated with glPathTexGenNV, glPathColorGenNV, and 9430 glPathFogGenNV respectively. 9431 9432 173. How does this extension interact with OpenGL ES 2 and 3? 9433 9434 RESOLVED: Same as the Core Profile in complete OpenGL. See Issue 9435 133 and the "Dependencies on Core Profile and OpenGL ES" section. 9436 9437 174. OpenGL ES normally does not use or require double-precision 9438 floating-point. Does the OpenGL ES version of this extension support 9439 the double-precision entry points MatrixLoaddEXT, etc.)? 9440 9441 RESOLVED: Yes. This is a conscious choice, and only 9442 double-precision support for CPU-side operations is required. See 9443 https://github.com/KhronosGroup/OpenGL-Registry/pull/119#issuecomment-341121022 9444 for background. 9445 9446Revision History 9447 9448 Rev. Date Author Changes 9449 ---- -------- --------- -------------------------------------------- 9450 2 08/26/11 mjk Initial version 9451 3 05/31/12 mjk Fix glPathStencilDepthOffsetNV to accept 9452 a GLfloat second parameter; add _BIT to the 9453 FONT_*_NV metric token names 9454 4 07/06/12 mjk Issue #128 9455 5 07/27/12 mjk Fix getPathName return value sense; 9456 Issue #129 and #130; UTF-8 and UTF-16 9457 decoding fixes. 9458 6 05/23/13 mjk Fix typo in Table 5.pathEquations 9459 7 06/25/13 mjk Fix token names missing _BIT_NV suffix 9460 8 08/01/13 mjk Bad argument order in instanced example 9461 9 08/22/13 mjk Fix GL_EYE_LINEAR behavior 9462 10 09/09/13 mjk Add core profile + smaller matrix support 9463 11 09/10/13 mjk Add conic segment path commands 9464 12 09/18/13 mjk Add rounded rectangles, GL_RELATIVE_RECT_NV, 9465 missing new matrix language, fix typos 9466 13 10/21/13 mjk <fontStyle> parameter for PathGlyphsNV 9467 and PathGlyphRangeNV 9468 14 11/05/13 dsn Use consistent argument names 9469 15 11/08/13 mjk Add StencilThenCover* commands 9470 16 11/11/13 mjk Add PathGlyphIndexRange command 9471 17 01/07/14 mjk Fix typos 9472 18 01/07/14 mjk Add PathGlyphIndexArray and 9473 PathMemoryGlyphIndexArray commands and 9474 FONT_NUM_GLYPH_INDICES_NV path query; 9475 renamed FONT_CORRUPT_NV to FONT_UNINTELLIGIBLE_NV 9476 19 02/12/14 mjk Document GL_PATH_STROKE_BOUND_NV 9477 20 02/14/14 mjk Fix rounded rectangle radii sign behavior 9478 (see issue 166) 9479 21 02/19/14 mjk Refashion the rrect function 9480 22 02/22/14 mjk PostScript arc behavior; see issue 167 9481 23 03/06/14 mjk Document FONT_NUM_GLYPH_INDICES_BIT_NV 9482 interactions; STANDARD_FONT_FORMAT_NV only 9483 for glPathMemoryGlyphIndexArrayNV 9484 24 03/18/14 mjk Update glPathFragmentInputGenNV state 9485 and query specification; issues 168-171 9486 25 03/19/14 mjk Better NVpr 1.3 explanation 9487 26 03/20/14 mjk Issue 172 9488 27 04/15/14 mjk ES interactions same as Core Profile 9489 28 05/02/14 mjk Updated status 9490 29 05/15/14 mjk Matrix*Tranpose to Matrix*Transpose 9491 30 05/29/14 mjk Release 1.3 driver details 9492 31 07/02/14 dkoch Fix a variety of typos and inconsistencies 9493 Update ES interactions 9494 Fix pseudocode (float vs double, renderBoundingBox) 9495 32 07/24/14 mjk Fix Equation 5.generalParametricArc typos, 9496 thanks to Chris Hebert 9497 33 08/19/14 mjk Add missing 1.3 additions to revisions section 9498 34 08/27/14 mjk Remove bogus polygon offset issue 127; my mistake 9499 35 09/09/14 mjk Intro: fix translate mode, add StencilThenCover 9500 36 11/01/17 Jon Leech Add issue 174 on double-precision ES support 9501