command_buffer: Implement path rendering functions for CHROMIUM_path_rendering

gpu/GLES2/extensions/CHROMIUM/CHROMIUM_path_rendering.txt

 Name
 
     CHROMIUM_path_rendering
 
 Name Strings
 
     GL_CHROMIUM_path_rendering
 
 Version
 
@@ skipping 13 matching lines @@
     Accepted by the <matrixMode> parameter of MatrixLoadfCHROMIUM and
     MatrixLoadIdentityCHROMIUM:
     MODELVIEW_CHROMIUM                                0x1700
     PROJECTION_CHROMIUM                               0x1701
 
     Accepted by the <pname> parameter of GetIntegerv,
     GetFloatv:
     MODELVIEW_MATRIX_CHROMIUM                         0x0BA6
     PROJECTION_MATRIX_CHROMIUM                        0x0BA7
 
+    Accepted by the <pname> parameter of GetIntegerv:
+    MAX_TEXTURE_COORDS_CHROMIUM                       0x8871
+
+    Accepted by the <pname> parameter of PathParameter{if}CHROMIUM:
+    PATH_STROKE_WIDTH_CHROMIUM                        0x9075
+    PATH_INITIAL_END_CAP_CHROMIUM                     0x9077
+    PATH_TERMINAL_END_CAP_CHROMIUM                    0x9078
+    PATH_JOIN_STYLE_CHROMIUM                          0x9079
+    PATH_MITER_LIMIT_CHROMIUM                         0x907a
+
+    Accepted by the <value> parameter of PathParameter{if}CHROMIUM:
+    FLAT_CHROMIUM                                     0x1D00
+    SQUARE_CHROMIUM                                   0x90a3
+    ROUND_CHROMIUM                                    0x90a4
+    BEVEL_CHROMIUM                                    0x90A6
+    MITER_REVERT_CHROMIUM                             0x90A7
+
+    Accepted by the <fillMode> parameter of StencilFillPathCHROMIUM and
+    StencilFillPathInstancedCHROMIUM:
+    COUNT_UP_CHROMIUM                                 0x9088
+    COUNT_DOWN_CHROMIUM                               0x9089
+
+    Accepted by the <genMode> parameter of PathTexGenCHROMIUM:
+    OBJECT_LINEAR_CHROMIUM                            0x2401
+    EYE_LINEAR_CHROMIUM                               0x2400
+
+    Accepted by the <coverMode> parameter of CoverFillPathCHROMIUM,
+    CoverFillPathInstancedCHROMIUM, CoverStrokePathCHROMIUM and
+    CoverStrokePathInstancedCHROMIUM:
+    BOUNDING_BOX_CHROMIUM                             0x908d
+
+    Accepted by the <transformType> parameter of
+    StencilFillPathInstancedCHROMIUM, StencilStrokePathInstancedCHROMIUM,
+    CoverFillPathInstancedCHROMIUM, and CoverStrokePathInstancedCHROMIUM:
+    TRANSLATE_X_CHROMIUM                              0x908E
+    TRANSLATE_Y_CHROMIUM                              0x908F
+    TRANSLATE_2D_CHROMIUM                             0x9090
+    TRANSLATE_3D_CHROMIUM                             0x9091
+    AFFINE_2D_CHROMIUM                                0x9092
+    AFFINE_3D_CHROMIUM                                0x9094
+    TRANSPOSE_AFFINE_2D_CHROMIUM                      0x9096
+    TRANSPOSE_AFFINE_3D_CHROMIUM                      0x9098
+
+    Accepted by the <coverMode> parameter of CoverFillPathInstancedCHROMIUM,
+    CoverStrokePathInstancedCHROMIUM:
+    BOUNDING_BOX_OF_BOUNDING_BOXES_CHROMIUM           0x909C
+
+
 
 New Procedures and Functions
 
     void MatrixLoadfCHROMIUM(enum matrixMode, float* matrix);
 
     Takes a pointer to a 4x4 matrix stored in column-major order as 16
     consecutive floating-point values. The matrixMode specifies which
     matrix, MODELVIEW_CHROMIUM or PROJECTION_CHROMIUM is used.
 
     The funcition specifies either modelview or projection matrix
     to be used with path rendering API calls.
 
     void MatrixLoadIdentityCHROMIUM(enum matrixMode);
 
     Effectively calls MatrixLoadf with the identity matrix.
 
+    uint GenPathsCHROMIUM(sizei range)
+
+    Returns an integer /n/ such that names /n/, ..., /n+range-1/ are
+    previously unused (i.e. there are /range/ previously unused path object
+    names starting at /n/).  These names are marked as used, for the
+    purposes of subsequent GenPathsCHROMIUM only, but they do not acquire
+    path object state until each particular name is used to specify
+    a path object.
+
+    void DeletePathsCHROMIUM(uint path, sizei range)
+
+    Deletes a path object where /path/ contains /range/ names of path objects to
+    be delete. After a path object is deleted, its name is again unused.
+    Unused names in /paths/ are silently ignored.
+
+    void PathCommandsCHROMIUM(uint path, sizei numCommands,
+                        const ubyte* commands, sizei numCoords,
+                        enum coordType, const void* coords)
+
+    Specifies a path object commands for /path/ where /numCommands/
+    indicates the number of path commands, read from the array
+    /commands/, with which to initialize that path's command sequence.
+    These path commands reference coordinates read sequentially from the
+    /coords/ array.  The type of the coordinates read from the /coords/
+    array is determined by the /coordType/ parameter must be
+    FLOAT, otherwise INVALID_ENUM is generated.
+
+    The /numCommands/ elements of the /commands/ array must be tokens
+    or character in Table 5.pathCommands.  The command sequence matches
+    the element order of the /commands/ array.  Each command references
+    a number of coordinates specified by "Coordinate count" column of
+    Table 5.pathCommands, starting with the first (zero) element of
+    the /coords/ array and advancing by the coordinate count for each
+    command.  If any of these /numCommands/ command values are not
+    listed in the "Token" or "Character aliases" columns of Table
+    5.pathCommands, the INVALID_ENUM error is generated.
+
+    The INVALID_OPERATION error is generated if /numCoords/ does not
+    equal the number of coordinates referenced by the command sequence
+    specified by /numCommands/ and /commands/ (so /numCoords/ provides a
+    sanity check that the /coords/ array is being interpreted properly).
+    The error INVALID_VALUE is generated if either /numCommands/ or
+    /numCoords/ is negative.
+
+    The error INVALID_OPERATION is generated if /path/ is
+    not an existing path object.
+
+    If the PathCommandsCHROMIUM command results in an error, the path object
+    named /path/ is not changed; if there is no error, the prior contents
+    of /path/, if /path/ was an existent path object, are lost and the
+    path object name /path/ becomes used.
+
+    void PathParameterfCHROMIUM(uint path, enum pname, float value)
+    void PathParameteriCHROMIUM(uint path, enum pname, int value)
+
+    The commands specify the value of path parameters for the specified path
+    object named /path/.  The error INVALID_OPERATION is generated if /path/ is
+    not an existing path object.
+
+    Each parameter has a single (scalar) value.
+
+    /pname/ must be one of the tokens in the "Name" column of
+    Table 5.pathParameters.
+    The required values or range of each allowed parameter name token
+    is listed in Table 5.pathParameter's "Required Values/Range" column.
+
+    For values of /pname/ listed in Table 5.pathsParameters, the specified
+    parameter is specified by /value/ when /value/ is a float or int,
+    or if /value/ is a pointer to a float or int, accessed through that
+    pointer.  The error INVALID_VALUE is generated if the specified
+    value is negative for parameters required to be non-negative in
+    Table 5.pathParameters.  Values specified to be clamped to the [0,1] range
+    in Table 5.pathParameters are so clamped prior to setting the
+    specified path parameter to that clamped value.
+
+    The error INVALID_VALUE is generated if the specified parameter value
+    is not within the require range for parameters typed float or integer.
+    The error INVALID_ENUM is generated if the specified parameter value
+    is not one of the listed tokens for parameters typed enum.
+
+    void PathStencilFuncCHROMIUM(enum func, int ref, uint mask)
+
+    Configures the stencil function, stencil reference value, and stencil read
+    mask to be used by the StencilFillPathCHROMIUM and StencilStrokePathCHROMIUM
+    commands described subsequently. The parameters accept the same values
+    allowed by the StencilFunc command.

[piman, 2014/04/24 22:26:36]

Why do we need a separate state from the regular GL state?

[Kimmo Kinnunen, 2014/04/25 12:46:30]

Tried to answer this in the added "Issues" section. (Different use-case in
practice, so values differ.)

+
+    void StencilFillPathCHROMIUM(uint path, enum fillMode, uint mask)
+
+    The function transforms into window space the outline of the path object
+    named /path/ based on the current modelview, projection and viewport,
+    transforms (ignoring any vertex and/or geometry shader or program that might
+    be active/enabled) and then updates the stencil values of all /accessible
+    samples/ (explained below) in the framebuffer.  Each sample's stencil buffer
+    value is updated based on the winding number of that sample with respect to
+    the transformed outline of the path object with any non-closed subpath
+    forced closed and the specified /fillMode/.
+
+    If /path/ does not name an existing path object, the command does
+    nothing (and no error is generated).
+
+    If the path's command sequence specifies unclosed subpaths (so not
+    contours) due to MOVE_TO_CHROMIUM commands, such subpaths are trivially
+    closed by connecting with a line segment the initial and terminal
+    control points of each such path command subsequence.
+
+    Transformation of a path's outline works by taking all positions on the
+    path's outline in 2D path space (x,y) and constructing an object space
+    position (x,y,0,1) that is then used similar to as with the (xo,yo,zo,wo)
+    position in section 2.12 ("Fixed-Function Vertex Transformation") of OpenGL
+    3.2 (unabridged) Specification (Special Functions) to compute corresponding
+    eye-space coordinates (xe,ye,ze,we) and clip-space coordinates
+    (xc,yc,zc,wc).  A path outline's clip-space coordinates are further
+    transformed into window space similar to as described in section 2.16
+    ("Coordinate Transformations").  This process provides a mapping 2D path
+    coordinates to 2D window coordinates.  The resulting 2D window coordinates
+    are undefined if any of the transformations involved are singular or may be
+    inaccurate if any of the transformations (or their combination) are
+    ill-conditioned.
+
+    The winding number for a sample with respect to the path outline,
+    transformed into window space, is computed by counting the (signed)
+    number of revolutions around the sample point when traversing each
+    (trivially closed if necessary) contour once in the transformed path.
+    This traversal is performed in the order of the path's command
+    sequence.  Starting from an initially zero winding count, each
+    counterclockwise revolution when the front face mode is CCW (or
+    clockwise revolution when the front face mode is CW) around the sample
+    point increments the winding count by one; while each clockwise
+    revolution when the front face mode is CCW (or counterclockwise
+    revolution when the front face mode is CW) around the sample point
+    decrements the winding count by one.
+
+    The /mask/ parameter controls what subset of stencil bits are affected
+    by the command.
+
+    The /fillMode/ parameter must be one of INVERT, COUNT_UP_CHROMIUM
+    or COUNT_DOWN_CHROMIUM; otherwise the INVALID_ENUM error
+    is generated.  INVERT inverts the bits set in the effective /mask/
+    value for each sample's stencil value if the winding number for the
+    given sample is odd.  COUNT_UP_CHROMIUM adds with modulo n arithmetic the
+    winding number of each sample with the sample's prior stencil buffer
+    value; the result of this addition is written into the sample's
+    stencil value but the bits of the stencil value not set in the
+    effective /mask/ value are left unchanged.  COUNT_DOWN_CHROMIUM subtracts
+    with modulo /n/ arithmetic the winding number of each sample with the
+    sample's prior stencil buffer value; the result of this subtraction is
+    written into the sample's stencil value but the bits of the stencil
+    value not set in the effective /mask/ value are left unchanged.
+
+    The value of /n/ for the modulo /n/ arithmetic used by COUNT_UP_CHROMIUM
+    and COUNT_DOWN_CHROMIUM is the effective /mask/+1.  The error INVALID_VALUE
+    is generated if /fillMode/ is COUNT_UP_CHROMIUM or COUNT_DOWN_CHROMIUM and
+    the effective /mask/+1 is not an integer power of two.
+
+    ACCESSIBLE SAMPLES WITH RESPECT TO A TRANSFORMED PATH
+
+    The accessible samples of a transformed path that are updated are
+    the samples that remain after discarding the following samples:
+
+        *   Any sample that would be clipped similar to as specified in section
+            2.22 ("Primitive Clipping") of OpenGL 3.2 (unabridged) Specification
+            (Special Functions) because its corresponding position in clip space
+            (xc,yc,zc,wc) or (xe,ye,ze,we) would be clipped by the clip volume
+            or enabled client-defined clip planes.
+
+        *   Any sample that would fail the pixel ownership test (section
+            4.1.1) if rasterized.
+
+        *   Any sample that would fail the scissor test (section 4.1.2)
+            if SCISSOR_TEST is enabled.
+
+    And for the StencilFillPathCHROMIUM and StencilStrokePathCHROMIUM commands
+    (so not applicable to the CoverFillPathCHROMIUM and CoverStrokePathCHROMIUM
+    commands):
+        *   Any sample that would fail the (implicitly enabled) stencil test
+            with the stencil function configured based on the path stencil
+            function state configured by PathStencilFuncCHROMIUM.  In the case
+            of the StencilFillPathCHROMIUM and StencilStrokePathCHROMIUM
+            commands and their instanced versions, the effective stencil read
+            mask for the stencil mask is treated as the value of
+            PATH_STENCIL_VALUE_MASK bit-wise ANDed with the bit-invert of the
+            effective /mask/ parameter value; otherwise, for the cover commands,
+            the stencil test operates normally.  In the case the stencil test
+            fails during a path stencil operation, the stencil fail operation is
+            ignored and the pixel's stencil value is left undisturbed (as if the
+            stencil operation was KEEP).
+
+        *   The state of the face culling (CULL_FACE) enable is ignored.
+
+    void StencilStrokePathCHROMIUM(uint path, int reference, uint mask)
+
+    Transforms into window space the stroked region of the path object named
+    /path/ based on the current modelview, projection and viewport transforms
+    (ignoring any vertex and/or geometry shader or program that might be
+    active/enabled) and then updates the stencil values of a subset of the
+    accessible samples (see above) in the framebuffer.
+
+    If /path/ does not name an existing path object, the command does
+    nothing (and no error is generated).
+
+    The path object's specified stroke width (in path space) determines
+    the width of the path's stroked region.
+
+    The stroke of a transformed path's outline
+    is the region of window space defined by the union of:
+
+        *   Sweeping an orthogonal centered line segment of the (above
+            determined) effective stroke width along each path segment
+            in the path's transformed outline.
+
+        *   End cap regions (explained below) appended to the initial
+            and terminal control points of non-closed command sequences
+            in the path.  For a sequence of commands that form a closed
+            contour, the end cap regions are ignored.
+
+        *   Join style regions (explained below) between connected path
+            segments meet.
+
+    Any accessible samples within the union of these three regions are
+    considered within the path object's stroke.
+
+    The /mask/ parameter controls what subset of stencil bits are affected
+    by the command.
+
+    A sample's stencil bits that are set in the effective /mask/ value
+    are updated with the specified stencil /reference/ value if the
+    sample is accessible (as specified above) and within the stroke of
+    the transformed path's outline.
+
+    Every path object has an initial and terminal end cap parameter
+    that is one of FLAT_CHROMIUM, SQUARE_CHROMIUM or
+    ROUND_CHROMIUM. There are no samples within a FLAT_CHROMIUM end cap.
+    The SQUARE_CHROMIUM cap extends centered and tangent to the given end
+    (initial or terminal) of the subpath for half the effective stroke
+    width; in other words, a square cap is a half-square that kisses
+    watertightly the end of a subpath.  The ROUND_CHROMIUM cap appends
+    a semi-circle, centered and tangent, with the diameter of the
+    effective stroke width to the given end (initial or terminal) of the
+    subpath; in other words, a round cap is a semi-circle that kisses
+    watertightly the end of a subpath.
+
+    Every path object has a join style that is one of BEVEL_CHROMIUM,
+    ROUND_CHROMIUM or MITER_REVERT_CHROMIUM.  Each path object also has a miter
+    limit value.  The BEVEL_CHROMIUM join style inserts a triangle with two
+    vertices at the outside corners where two connected path segments join and a
+    third vertex at the common end point shared by the two path segments.  The
+    ROUND_CHROMIUM join style inserts a wedge-shaped portion of a circle
+    centered at the common end point shared by the two path segments; the radius
+    of the circle is half the effective stroke width. The MITER_REVERT_CHROMIUM
+    join style inserts a quadrilateral with two opposite vertices at the outside
+    corners where the two connected path segments join and two opposite vertices
+    with one on the path's junction between the two joining path segments and
+    the other at the common end point shared by the two path segments.  However,
+    the MITER_REVERT_CHROMIUM join style behaves as the BEVEL_CHROMIUM style if
+    the sine of half the angle between the two joined segments is less than the
+    path object's PATH_STROKE_WIDTH value divided by the path's
+    PATH_MITER_LIMIT_CHROMIUM value.
+
+    void PathTexGenCHROMIUM(enum texCoordSet, enum genMode, int components,
+                      const float* coeffs)
+
+    The function controls how texture coordinate sets are computed for fragment
+    shading operations that occur as a result of CoverFillPathCHROMIUM or
+    CoverStrokePathCHROMIUM.

[piman, 2014/04/24 22:26:36]

Can you describe how these texture coordinates interact with the GL state?
Is it expected that they will be picked up by a fragment shader? How are they
bound to input varyings? Are there additions to the glsl language to support
this?
Since my understanding is that Cover*Path* skips the vertex shader, what does it
mean exactly wrt a fully linked program? What happens to the fragment shader's
input varyings that are not filled by the vertex shader + rasterizer?

[Kimmo Kinnunen, 2014/04/25 12:46:30]

Good point, forgot these.

Added explanation that the values go to a new built-in variable array,
gl_TexCoord.

I added section for GLSL extension.
Added an answer in the "Issues" section. (They should be zeros)

+
+    /texCoordSet/ must be one of TEXTURE0 through
+    TEXTUREn where /n/ is one less than the implementation-dependent
+    value of MAX_TEXTURE_COORDS_CHROMIUM; otherwise INVALID_ENUM is generated.
+
+    /genMode/ must be one of NONE, OBJECT_LINEAR_CHROMIUM, or
+    EYE_LINEAR_CHROMIUM; otherwise INVALID_ENUM is generated.
+
+    /components/ must be 0 if /genMode/ is NONE or for other allowed
+    /genMode/ values must be one of 1, 2, 3, or 4; otherwise INVALID_VALUE
+    is generated.  /components/ determines how many texture coordinate
+    components of the texture coordinate set, how many coefficients read
+    from the /coeffs/ array, and the linear equations used to generate the
+    s, t, r, and q texture coordinates of the varying texture coordinate
+    set specified by /texCoordSet/.
+
+    In the following equations, coeffs[i] is the /i/th element (base
+    zero) of the /coeffs/ array; sc, tc, rc, and qa are the s, t, r,
+    and q texture coordinates of the texture coordinate set indicated
+    by /texCoordSet/ when the path is covered; and x, y, z, and w are
+    determined by the /genMode/ in the same manner as PathColorGenCHROMIUM's

[piman, 2014/04/24 22:26:36]

PathColorGenCHROMIUM isn't in this extension.

[Kimmo Kinnunen, 2014/04/25 12:46:30]

Removed. Added some explanation above.

+    /genMode/.
+
+    If the /components/ is 0, no values from the /coeffs/ array are
+    accessed and the s, t, r, and q coordinates of a covered fragment's
+    varying texture coordinate set for /texCoordSet/ are computed:
+
+        s = sc
+        t = tc
+        r = rc
+        q = qc
+
+    If the /components/ is 1 and /genMode/ is OBJECT_LINEAR_CHROMIUM, 3 values
+    from the /coeffs/ array are accessed and the s, t, r, and q coordinates of a
+    covered fragment's varying texture coordinate set for /texCoordSet/ are
+    computed:
+
+        s = coeffs[0] * x + coeffs[1] * y + coeffs[2]
+        t = tc
+        r = rc
+        q = qc
+
+    Alternatively if the /genMode/ is EYE_LINEAR_CHROMIUM, then 4 values are
+    accessed and the varying texture coordinate set for /texunit/ are
+    computed:
+
+        s = coeffs[0] * xe + coeffs[1] * ye + coeffs[2] * ze + coeffs[3] * we
+        t = tc
+        r = rc
+        q = qc
+
+    If the /components/ is 2 and /genMode/ is OBJECT_LINEAR_CHROMIUM, 6 values
+    from the /coeffs/ array are accessed and the s, t, r, and q coordinates of a
+    covered fragment's varying texture coordinate set for /texCoordSet/ are
+    computed:
+
+        s = coeffs[0] * x + coeffs[1] * y + coeffs[2]
+        t = coeffs[3] * x + coeffs[4] * y + coeffs[5]
+        r = rc
+        q = qc
+
+    Alternatively if the /genMode/ is EYE_LINEAR_CHROMIUM, then 8 values are
+    accessed and the varying texture coordinate set for /texunit/ are
+    computed:
+
+        s = coeffs[0] * xe + coeffs[1] * ye + coeffs[2] * ze + coeffs[3] * we
+        t = coeffs[4] * xe + coeffs[5] * ye + coeffs[6] * ze + coeffs[7] * we
+        r = rc
+        q = qc
+
+    If the /components/ is 3 and /genMode/ is OBJECT_LINEAR_CHROMIUM or 9 values
+    from the /coeffs/ array are accessed and the s, t, r, and q coordinates of a
+    covered fragment's varying texture coordinate set for /texCoordSet/ are
+    computed:
+
+        s = coeffs[0] * x + coeffs[1] * y + coeffs[2]
+        t = coeffs[3] * x + coeffs[4] * y + coeffs[5]
+        r = coeffs[6] * x + coeffs[7] * y + coeffs[8]
+        q = qc
+
+    Alternatively if the /genMode/ is EYE_LINEAR_CHROMIUM, then 12 values are
+    accessed and the varying texture coordinate set for /texunit/ are
+    computed:
+
+        s = coeffs[0] * xe + coeffs[1] * ye + coeffs[2]  * ze + coeffs[3]  * we
+        t = coeffs[4] * xe + coeffs[5] * ye + coeffs[6]  * ze + coeffs[7]  * we
+        r = coeffs[8] * xe + coeffs[9] * ye + coeffs[10] * ze + coeffs[11] * we
+        q = qc
+
+    If the /components/ is 4 and /genMode/ is OBJECT_LINEAR_CHROMIUM, 12
+    values from the /coeffs/ array are accessed and the s, t, r, and q
+    coordinates of a covered fragment's varying texture coordinate set for
+    /texCoordSet/ are computed:
+
+        s = coeffs[0] * x + coeffs[1]  * y + coeffs[2]
+        t = coeffs[3] * x + coeffs[4]  * y + coeffs[5]
+        r = coeffs[6] * x + coeffs[7]  * y + coeffs[8]
+        q = coeffs[9] * x + coeffs[10] * y + coeffs[11]
+
+    Alternatively if the /genMode/ is EYE_LINEAR_CHROMIUM, then 16 values are
+    accessed and the varying texture coordinate set for /texunit/ are
+    computed:
+
+        s = coeffs[0]  * xe + coeffs[1]  * ye + coeffs[2]  * ze + coeffs[3]  * we
+        t = coeffs[4]  * xe + coeffs[5]  * ye + coeffs[6]  * ze + coeffs[7]  * we
+        r = coeffs[8]  * xe + coeffs[9]  * ye + coeffs[10] * ze + coeffs[11] * we
+        q = coeffs[12] * xe + coeffs[13] * ye + coeffs[14] * ze + coeffs[15] * we
+
+    The state required for path color generation for each texture
+    coordinate set is a four-valued integer for the path texture
+    coordinate set generation mode and 16 floating-point coefficients.
+    The initial mode is NONE and the coefficients are all initially zero.
+
+    void CoverFillPathCHROMIUM(uint path, enum coverMode)

[piman, 2014/04/24 22:26:36]

Do we need coverMode if there can only be BOUNDING_BOX_CHROMIUM?

[Kimmo Kinnunen, 2014/04/25 12:46:30]

This is the "API discussion", see below.

+
+    The command transforms into window space the outline of the path object
+    named /path/ based on the current modelview, projection and viewport
+    transforms (ignoring any vertex and/or geometry shader or program that might
+    be active/enabled) and rasterizes a subset of the accessible samples in the
+    framebuffer guaranteed to include all samples that would be have a net

[piman, 2014/04/24 22:26:36]

typo: "would be have" ->  "would have"

[Kimmo Kinnunen, 2014/04/25 12:46:30]

Done.

+    stencil value change if StencilFillPathCHROMIUM were issued with the same
+    modelview, projection, and viewport state.  During this rasterization, the
+    stencil test operates normally and as configured; the expectation is the
+    stencil test will be used to discard samples not determined "covered" by a
+    prior StencilFillPathCHROMIUM command.
+
+    If /path/ does not name an existing path object, the command does
+    nothing (and no error is generated).
+
+    /coverMode/ must be BOUNDING_BOX_CHROMIUM.
+
+    When /coverMode/ is BOUNDING_BOX_CHROMIUM, the subset of accessible pixels
+    that are rasterized are within a bounding box (expected to be reasonably
+    tight) surrounding all the samples guaranteed to be rasterized by
+    CoverFillPathCHROMIUM.  The bounding box must be orthogonally aligned to the
+    path space coordinate system.  (The area of the bounding box in path space
+    is guaranteed to be greater than or equal the area of the convex hull in
+    path space.) Each rasterized sample will be rasterized once and exactly once
+    when BOUNDING_BOX_CHROMIUM is specified.
+
+    While samples with a net stencil change /must/ be rasterized,
+    implementations are explicitly allowed to vary in the rasterization
+    of samples for which StencilFillPathCHROMIUM would /not/ change sample's
+    net stencil value.  This means implementations are allowed to (and,
+    in fact, are expected to) conservatively "exceed" the region strictly
+    stenciled by the path object.
+
+    CoverFillPathCHROMIUM /requires/ the following rasterization invariance:
+    calling CoverFillPathCHROMIUM for the same (unchanged) path object with
+    fixed (unchanged) modelview, projection, and viewport transform state
+    with the same (unchanged) set of accessible samples will rasterize
+    the exact same set of samples with identical interpolated values
+    for respective fragment/sample locations.
+
+    void CoverStrokePathCHROMIUM(uint path, enum coverMode)
+
+    The command operates in the same manner as CoverFillPathCHROMIUM except the
+    region guaranteed to be rasterized is, rather than the region within
+    /path/'s filled outline, instead the region within the /path/'s stroked
+    region as determined by StencilStrokePathCHROMIUM.  During this
+    rasterization, the stencil test operates normally and as configured; the
+    expectation is the stencil test will be used to discard samples not
+    determined "covered" by a prior StencilStrokePathCHROMIUM command.
+
+    /coverMode/ must be BOUNDING_BOX_CHROMIUM.
+
+    If /path/ does not name an existing path object, the command does
+    nothing (and no error is generated).
+
+    Analogous to the rasterization guarantee of CoverFillPathCHROMIUM with
+    respect to StencilFillPathCHROMIUM, CoverStrokePathCHROMIUM guarantees that
+    all samples rasterized by StencilStrokePathCHROMIUM, given the same
+    transforms and accessible pixels and stroke width, will also be rasterized
+    by the corresponding CoverStrokePathCHROMIUM.
+
+    CoverStrokePathCHROMIUM /requires/ the following rasterization invariance:
+    calling CoverStrokePathCHROMIUM for the same (unchanged) path object with
+    fixed (unchanged) modelview, projection, and viewport transform state and
+    with the same (unchanged) set of accessible samples will rasterize the exact
+    same set of samples with identical interpolated values for respective
+    fragment/sample locations.
+
+    void StencilFillPathInstancedCHROMIUM(sizei numPaths,
+                                          enum pathNameType, const void *paths,

[piman, 2014/04/24 22:26:36]

since pathNameType is always UNSIGNED_INT, why not omitting it and have paths be
a GLuint*?

[Kimmo Kinnunen, 2014/04/25 12:46:30]

"API discussion"

+                                          uint pathBase,
+                                          enum fillMode, uint mask,
+                                          enum transformType,
+                                          const float *transformValues);
+
+    The command stencils a sequence of filled paths.
+
+    The /pathBase/ is an offset added to the /numPaths/ path names read
+    from the /paths/ array (interpreted based on /pathNameType/).
+
+    The /pathNameType/ determines the type of elements of the /paths/
+    array and must be UNSIGNED_INT, otherwise INVALID_ENUM is generated.
+
+    The /transformType/ must be one of NONE, TRANSLATE_X_CHROMIUM,
+    TRANSLATE_Y_CHROMIUM, TRANSLATE_2D_CHROMIUM, TRANSLATE_3D_CHROMIUM,
+    AFFINE_2D_CHROMIUM, AFFINE_3D_CHROMIUM, TRANSPOSE_AFFINE_2D_CHROMIUM, or
+    TRANSPOSE_AFFINE_3D_CHROMIUM.
+
+    The /fillMode/ and /mask/ are validated identically to the same-named
+    parameters of StencilFillPathCHROMIUM.
+
+    The StencilFillPathInstancedCHROMIUM command is equivalent to:
+
+        const float *v = transformValues;
+        for (int i = 0; i<numPaths; i++) {
+          float m[16];
+
+          GetFloatv(MODELVIEW_MATRIX, m);  // save matrix
+          v = applyTransformType(transformType, v);
+          uint pathName;
+          bool stopEarly = getPathName(pathNameType, paths, pathBase, pathName);

[piman, 2014/04/24 22:26:36]

getPathName returns an int instead of a bool... make it consistent?

[Kimmo Kinnunen, 2014/04/25 12:46:30]

Done. (Made getPathName to return (GL)bool).

+          if (stopEarly)
+            return;
+          StencilFillPathCHROMIUM(pathName, fillMode, mask);
+          MatrixLoadfCHROMIUM(MODELVIEW, m);  // restore matrix
+        }
+
+    assuming these helper functions for applyTransformType and
+    getPathName:
+
+        const float *applyTransformType(enum transformType, const float *v)
+        {
+          float m[16];
+          switch (transformType) {
+          case NONE:
+            break;
+          case TRANSLATE_X_CHROMIUM:
+            // translate the MODELVIEW matrix with value v[0]
+            v++;
+            break;
+          case TRANSLATE_Y_CHROMIUM:
+            // translate the MODELVIEW matrix with value v[0]
+            v++;
+            break;
+          case TRANSLATE_2D_CHROMIUM:
+            // translate the MODELVIEW matrix with values v[0] and v[1]
+            v+=2;
+            break;
+          case TRANSLATE_3D_CHROMIUM:
+            // translate the MODELVIEW matrix with values v[0], v[1] and v[2]
+            v+=3;
+            break;
+          case AFFINE_2D_CHROMIUM:
+            m[0] =v[0]; m[4] =v[2]; m[8] =0; m[12]=v[4];
+            m[1] =v[1]; m[5] =v[3]; m[9] =0; m[13]=v[5];
+            m[2] =0;    m[6] =0;    m[10]=1; m[14]=0;
+            m[3] =0;    m[7] =0;    m[11]=0; m[15]=1;
+            v += 6;
+            // multiply the MODELVIEW matrix with m
+            break;
+          case TRANSPOSE_AFFINE_2D_CHROMIUM:
+            m[0] =v[0]; m[4] =v[1]; m[8] =0; m[12]=v[2];
+            m[1] =v[3]; m[5] =v[4]; m[9] =0; m[13]=v[5];
+            m[2] =0;    m[6] =0;    m[10]=1; m[14]=0;
+            m[3] =0;    m[7] =0;    m[11]=0; m[15]=1;
+            v += 6;
+            // multiply the MODELVIEW matrix with m
+            break;
+          case AFFINE_3D_CHROMIUM:
+            m[0] =v[0]; m[4] =v[3]; m[8] =v[6]; m[12]=v[9];
+            m[1] =v[1]; m[5] =v[4]; m[9] =v[7]; m[13]=v[10];
+            m[2] =v[2]; m[6] =v[5]; m[10]=v[8]; m[14]=v[11];
+            m[3] =0;    m[7] =0;    m[11]=1;    m[15]=0;
+            v += 12;
+            // multiply the MODELVIEW matrix with m
+            break;
+          case TRANSPOSE_AFFINE_3D_CHROMIUM:
+            m[0] =v[0]; m[4] =v[1]; m[8] =v[2];  m[12]=v[3];
+            m[1] =v[4]; m[5] =v[5]; m[9] =v[6];  m[13]=v[7];
+            m[2] =v[8]; m[6] =v[9]; m[10]=v[10]; m[14]=v[11];
+            m[3] =0;    m[7] =0;    m[11]=1;     m[15]=0;
+            v += 12;
+            // multiply the MODELVIEW matrix with m
+            break;
+          default:  // generate INVALID_ENUM
+          }
+          return v;
+        }
+
+        int getPathName(enum pathNameType, const void *&paths,
+                        uint pathBase, uint &pathName)
+        {
+          switch (pathNameType) {
+          case UNSIGNED_INT:
+            {
+              const uint *p = (const uint*)paths;
+              pathName = pathBase + p[0];
+              paths = p+1;
+              return 1;
+            }
+          default:  // generate INVALID_ENUM
+          }
+        }
+
+
+    void StencilStrokePathInstancedCHROMIUM(sizei numPaths,
+                                          enum pathNameType, const void *paths,
+                                          uint pathBase,
+                                          int reference, uint mask,
+                                          enum transformType,
+                                          const float *transformValues);
+
+    The command stencils a sequence of stroked paths and is equivalent to:
+
+        const float *v = transformValues;
+        for (int i = 0; i<numPaths; i++) {
+          float m[16];
+          GetFloatv(MODELVIEW_MATRIX, m);  // save matrix
+          v = applyTransformType(transformType, v);
+          uint pathName;
+          bool stopEarly = getPathName(pathNameType, paths, pathBase, pathName);
+          if (stopEarly)
+            return;
+          StencilStrokePathCHROMIUM(pathName, reference, mask);
+          MatrixLoadfCHROMIUM(MODELVIEW, m);  // restore matrix
+        }
+
+    assume the helper functions for applyTransformType and
+    getPathName defined above.
+
+    void CoverFillPathInstancedCHROMIUM(sizei numPaths,
+                                        enum pathNameType, const void *paths,
+                                        uint pathBase,
+                                        enum coverMode,
+                                        enum transformType,
+                                        const float *transformValues);
+
+    /coverMode/ must be BOUNDING_BOX_OF_BOUNDING_BOXES_CHROMIUM.
+
+    The command covers a sequence of filled paths and is equivalent to:
+
+        renderBoundingBox(FALSE,
+                          numPaths,
+                          pathNameType, paths,
+                          pathBase,
+                          transformType, transformValues);
+
+    assuming these helper functions for applyTransformType and
+    getPathName defined above as well as:
+
+        void renderBoundingBox(bool shouldRenderStroke,
+                               sizei numPaths,
+                               enum pathNameType,
+                               const void *paths,
+                               uint pathBase,
+                               enum transformType,
+                               const float *transformValues)
+        {
+          boolean hasBounds = FALSE;
+          float boundsUnion[4], bounds[4];
+
+          const float *v = transformValues;
+          for (int i = 0; i<numPaths; i++) {
+            uint pathName;
+            bool stopEarly = getPathName(pathNameType, paths, pathBase, pathName);
+            if (stopEarly)
+              return;
+            if (IsPath(pathName)) {
+              GetPathBoundingBox(pathName, shouldRenderStroke, bounds);
+              switch (transformType) {
+              case NONE:
+                break;
+              case TRANSLATE_X_CHROMIUM:
+                bounds[0] += v[0];
+                bounds[2] += v[0];
+                v += 1;
+                break;
+              case TRANSLATE_Y_CHROMIUM:
+                bounds[1] += v[0];
+                bounds[3] += v[0];
+                v += 1;
+                break;
+              case TRANSLATE_2D_CHROMIUM:
+                bounds[0] += v[0];
+                bounds[1] += v[1];
+                bounds[2] += v[0];
+                bounds[3] += v[1];
+                v += 2;
+                break;
+              case TRANSLATE_3D_CHROMIUM: // ignores v[2]
+                bounds[0] += v[0];
+                bounds[1] += v[1];
+                bounds[2] += v[0];
+                bounds[3] += v[1];
+                v += 3;
+                break;
+              case AFFINE_2D_CHROMIUM:
+                bounds[0] = bounds[0]*v[0] + bounds[0]*v[2] + v[4];
+                bounds[1] = bounds[1]*v[1] + bounds[1]*v[3] + v[5];
+                bounds[2] = bounds[2]*v[0] + bounds[2]*v[2] + v[4];
+                bounds[3] = bounds[3]*v[1] + bounds[3]*v[3] + v[5];
+                v += 6;
+                break;
+              case TRANSPOSE_AFFINE_2D_CHROMIUM:
+                bounds[0] = bounds[0]*v[0] + bounds[0]*v[1] + v[2];
+                bounds[1] = bounds[1]*v[3] + bounds[1]*v[4] + v[5];
+                bounds[2] = bounds[2]*v[0] + bounds[2]*v[1] + v[2];
+                bounds[3] = bounds[3]*v[3] + bounds[3]*v[4] + v[5];
+                v += 6;
+                break;
+              case AFFINE_3D_CHROMIUM:  // ignores v[2], v[5], v[6..8], v[11]
+                bounds[0] = bounds[0]*v[0] + bounds[0]*v[3] + v[9];
+                bounds[1] = bounds[1]*v[1] + bounds[1]*v[4] + v[10];
+                bounds[2] = bounds[2]*v[0] + bounds[2]*v[3] + v[9];
+                bounds[3] = bounds[3]*v[1] + bounds[3]*v[4] + v[10];
+                v += 12;
+                break;
+              case TRANSPOSE_AFFINE_3D_CHROMIUM:  // ignores v[2], v[6], v[8..11]
+                bounds[0] = bounds[0]*v[0] + bounds[0]*v[1] + v[3];
+                bounds[1] = bounds[1]*v[4] + bounds[1]*v[5] + v[7];
+                bounds[2] = bounds[2]*v[0] + bounds[2]*v[1] + v[3];
+                bounds[3] = bounds[3]*v[4] + bounds[3]*v[5] + v[7];
+                v += 12;
+                break;
+              default:  // generate INVALID_ENUM
+              }
+              if (bounds[0] > bounds[2]) {
+                float t = bounds[2];
+                bounds[2] = bounds[0];
+                bounds[0] = t;
+              }
+              if (bounds[1] > bounds[3]) {
+                float t = bounds[3];
+                bounds[3] = bounds[1];
+                bounds[1] = t;
+              }
+              if (hasBounds) {
+                if (bounds[0] < boundsUnion[0]) {
+                  boundsUnion[0] = bounds[0];
+                }
+                if (bounds[1] < boundsUnion[1]) {
+                  boundsUnion[1] = bounds[1];
+                }
+                if (bounds[2] > boundsUnion[2]) {
+                  boundsUnion[2] = bounds[2];
+                }
+                if (bounds[3] > boundsUnion[3]) {
+                  boundsUnion[3] = bounds[3];
+                }
+              } else {
+                for (int i=0; i<4; i++) {
+                  boundsUnion[i] = bounds[i];
+                }
+                hasBounds = TRUE;
+              }
+            }
+          }
+          if (hasBounds) {
+             Rectf(bounds[0], bounds[1], bounds[2], bounds[3]);
+          }
+        }
+
+    Where helper IsPath checks if the path is a defined,
+    GetPathBoundingBox returns bounding box for the path with or without
+    stroking, and Rectf renders a rectangle.
+
+    void CoverStrokePathInstancedCHROMIUM(sizei numPaths,

[piman, 2014/04/24 22:26:36]

Would it make sense to combine this with CoverFillPathInstancedCHROMIUM, and
having an enum to specify fill vs stroke?
It would save a bit on API footprint (thinking testing, security validation,
etc.)

Similarly maybe for CoverFillPathCHROMIUM vs CoverStrokePathCHROMIUM

I'd suggest the Stencil* versions as well, but they have different parameters
between the stroke and the fill versions, so it probably doesn't make as much
sense.

[Kimmo Kinnunen, 2014/04/25 12:46:30]

This is the "API discussion".

+                                          enum pathNameType, const void *paths,
+                                          uint pathBase,
+                                          enum coverMode,
+                                          enum transformType,
+                                          const float *transformValues);
+
+    /coverMode/ must be BOUNDING_BOX_OF_BOUNDING_BOXES_CHROMIUM.
+
+    The command covers a sequence of stroked paths and is equivalent to:
+
+        renderBoundingBox(TRUE,
+                          numPaths,
+                          pathNameType, paths,
+                          pathBase,
+                          transformType, transformValues);
+
+    assuming these helper functions defined above.
+
+
+
 Errors
 
     None.
 
 New State
 
     Get Value                  Type   Get Command  Initial  Description
     -------------------------  -----  ------------ -------- -------------------
     MODELVIEW_MATRIX_CHROMIUM  16xR   GetFloatv    all 0's  Current modelview
                                                             matrix for path rendering
     PROJECTION_MATRIX_CHROMIUM 16xR   GetFloatv    all 0's  Current projection
                                                             matrix for path rendering
+    PATH_STENCIL_FUNC_CHROMIUM Z8     GetIntegerv  ALWAYS   path stenciling function
+    PATH_STENCIL_REF_CHROMIUM  Z+     GetIntegerv  0        path stenciling
+                                                            reference value
+    PATH_STENCIL_VALUE_MASK_CHROMIUM                        path stencil read
+                               Z+     GetIntegerv  1's      mask
+
+Tables
+    Table 5.pathCommands: Path Commands
+
+                                                       Character   Coordinate
+    Token                       Description            alias       count
+    ==========================  =====================  ==========  ==========
+    MOVE_TO_NV                  Absolute move          'M'         2

[piman, 2014/04/24 22:26:36]

nit: _CHROMIUM (here and below)

[Kimmo Kinnunen, 2014/04/25 12:46:30]

Done.

+                                current point
+    --------------------------  ---------------------  ----------  ----------
+    CLOSE_PATH_NV               Close path             'Z' or 'z'  0
+    --------------------------  ---------------------  ----------  ----------
+    LINE_TO_NV                  Absolute line          'L'         2
+    --------------------------  ---------------------  ----------  ----------
+    QUADRATIC_CURVE_TO_NV       Absolute quadratic     'Q'         4
+    CUBIC_CURVE_TO_NV           Absolute cubic         'C'         6
+                                Bezier segment
+    --------------------------  ---------------------  ----------  ----------
+
+    Table 5.pathParameters
+    Name                             Type     Required Values or Range
+    -------------------------------  -------  -----------------------------------------------
+    PATH_STROKE_WIDTH_CHROMIUM       float    non-negative
+    PATH_INITIAL_END_CAP_CHROMIUM    enum     FLAT, SQUARE_CHROMIUM, ROUND_CHROMIUM
+    PATH_TERMINAL_END_CAP_CHROMIUM   enum     FLAT, SQUARE_CHROMIUM, ROUND_CHROMIUM
+    PATH_JOIN_STYLE_CHROMIUM         enum     MITER_REVERT_CHROMIUM, BEVEL_CHROMIUM, ROUND_CHROMIUM
+    PATH_MITER_LIMIT_CHROMIUM        float    non-negative
 
 Revision History
 
     23/4/2014    Documented the extension