Tegra-Supported OpenGL ES 2.0 Extensions


Extension support in EGL and GLES differs on a device-by-device and OS-by-OS basis on Tegra. Applications should always query for extension support on the target platform. Some of the Khronos-general GLES extensions supported on most Tegra platforms include the following. The specifications for these extensions may be found at:

http://www.khronos.org/registry/gles/

Vertex and Geometry Extensions
GL_EXT_packed_float RGB floating-point textures in one 32bpp format
GL_OES_mapbuffer Low-overhead buffer updates
GL_OES_vertex_half_float 16-bit float vertex support (1 sign bit, 5 exponent bits, 10 mantissa bits)
FBO and Renderbuffer Extensions
GL_OES_EGL_image Cross-API images
GL_OES_EGL_image_external Cross-API images
GL_OES_EGL_sync Command-stream synchronization
GL_OES_fbo_render_mipmap Mipmap-level FBO support
GL_OES_rgb8_rgba8 24 and 32bpp FBOs
Texture Format Extensions
GL_EXT_bgra Reversed RGBA texture support
GL_EXT_texture_compression_dxt1 DXT1 texture support
GL_EXT_texture_compression_latc LA compressed textures
GL_EXT_texture_compression_s3tc DXT3/5 texture support
GL_EXT_texture_format_BGRA8888 Reversed RGBA texture support
GL_OES_compressed_ETC1_RGB8_texture ETC1 textures
GL_OES_texture_float Note that 32-bit floating point textures are accepted, but are converted to 16-bit floating point textures internally, and thus use of this extension is not recommended.
GL_OES_texture_half_float 16-bit (1 sign bit, 5 exponent bits, 10 mantissa bits)
Texture Feature Extensions
GL_EXT_texture_filter_anisotropic Anisotropic mipmap filtering
GL_EXT_texture_array 1D arrays of 2D textures
GL_EXT_unpack_subimage Limited stride support for texture updates
GL_EXT_occlusion_query_boolean  


The list below highlights some of the NV-specific extensions and the links to their specifications in the Khronos registry. Several of these extensions do not yet appear in the registry; the specs for these extensions are included at the end of the chapter.

EGL_NV_system_time http://www.khronos.org/registry/egl/extensions/NV/EGL_NV_system_time.txt
GL_NV_coverage_sample http://www.khronos.org/registry/gles/extensions/NV/EGL_NV_coverage_sample.txt
GL_NV_depth_nonlinear http://www.khronos.org/registry/gles/extensions/NV/EGL_NV_depth_nonlinear.txt
GL_NV_draw_buffers http://www.khronos.org/registry/gles/extensions/NV/GL_NV_draw_buffers.txt
GL_NV_draw_path Documented at the end of the chapter
GL_NV_fbo_color_attachments http://www.khronos.org/registry/gles/extensions/NV/GL_NV_fbo_color_attachments.txt
GL_NV_platform_binary Deprecated; use source-code shaders
GL_NV_read_buffer http://www.khronos.org/registry/gles/extensions/NV/GL_NV_read_buffer.txt
GL_NV_read_depth http://www.khronos.org/registry/gles/extensions/NV/GL_NV_read_depth_stencil.txt
GL_NV_read_stencil http://www.khronos.org/registry/gles/extensions/NV/GL_NV_read_depth_stencil.txt
GL_NV_shader_framebuffer_fetch Documented at the end of the chapter
GL_NV_texture_compression_s3tc_update http://www.khronos.org/registry/gles/extensions/NV/GL_NV_texture_compression_s3tc_update.txt
GL_NV_texture_npot_2D_mipmap http://www.khronos.org/registry/gles/extensions/NV/GL_NV_texture_npot_2D_mipmap.txt

Other Extension Specs

The following extensions specs are not yet in the Khronos registry site. They are included at the end of this chapter.

NV_draw_path

Name

NV_draw_path

Name Strings

GL_NV_draw_path

Contact

Jussi Rasanen, NVIDIA Corporation (jrasanen 'at' nvidia.com)

Tero Karras, NVIDIA Corporation (tkarras 'at' nvidia.com)

Notice

Copyright NVIDIA Corporation, ©2008

Status

NVIDIA Proprietary

Version

Last Modified: 2008/09/16

NVIDIA Revision: 0.11

Number

XXXX Not Yet XXXX

Dependencies

Written based on the wording of the OpenGL 2.0 Specification.

Requires OpenGL-ES 2.0.

Overview

This extension adds functionality to render planar Bezier paths. Use cases for this extension include acceleration of vector graphics content and text rendering.

A path is defined as a number of segments, representing either straight lines, or quadratic or cubic Bezier curves, and can be either filled or stroked. Filling corresponds to generating the fragments that lie within the interior of the path. Stroking corresponds to generating the fragments that lie within a region defined by sweeping a straight-line pen along the path.

Path segments are specified using a command array and a vertex coordinate array. When a path is drawn, the command array is processed sequentially. There are two categories of commands: ones that cause a path segment to be drawn, and ones that affect how path is rendered. Depending on its type, each command consumes a variable number of coordinates from the vertex coordinate array.

When filling a path, the order in which the path segments are specified is disregarded. The only requirement is that they form zero or more closed contours. If a path contains unclosed contours, its interior and thus the resulting set of fragments is undefined. The contours of a path may have self-intersecting geometry and overlap with each other. For such paths, the interior is determined using a fill rule. Two fill rules, even-odd and non-zero, are provided. The direction of path segments matters only with the non-zero fill rule, as explained below.

When stroking a path, additional cap and join styles may be applied at the start and end of path segments. Joins are automatically generated between pairs of segments whose corresponding commands are adjacent. Caps are generated based on explicit path commands.

Rendering quality can be controlled per path by specifying the maximum deviation from the ideal curve in window space.

Path Rendering Pipeline

The path rendering pipeline consists of three stages: transformation and texture coordinate generation, fill and stroke rasterization, and fragment shader. This extension provides a minimal fixed function transformation and texture coordinate generation stage. Programmable vertex shaders are not supported in the context of path rendering.

Path Definition

Paths are defined as a combination of an immutable sequence of commands and an associated mutable sequence of vertex coordinates. Each command consumes zero or more vertex coordinates. Path commands are represented as unsigned bytes, whereas the data type of the vertex coordinates is specified separately for each path. Path vertices are always two-dimensional.

The following table lists the available path commands:

Path Command Coords Notes
MOVE_TO_NV 2 Change the current position.
LINE_TO_NV 2 Draw a straight line.
QUADRATIC_BEZIER_TO_NV 4 Draw a quadratic Bezier curve.
CUBIC_BEZIER_TO_NV 6 Draw a cubic Bezier curve.
START_MARKER_NV 0 Record the current position.
CLOSE_NV 0 Draw line to the recorded position.
STROKE_CAP0_NV 0 Use cap style 0 in adjacent segment.
STROKE_CAP1_NV 0 Use cap style 1 in adjacent segment.
STROKE_CAP2_NV 0 Use cap style 2 in adjacent segment.
STROKE_CAP3_NV 0 Use cap style 3 in adjacent segment.
Transformation and Texture Coordinate Generation

Path vertices specified by the vertex coordinate sequence are converted to the homogenous form (x, y, 0, 1) by the transformation stage, and then transformed from model space to clip space using the MATRIX_PATH_TO_CLIP_NV matrix.

To facilitate texture mapping and color gradients, the path vertices are also transformed using each of the MATRIX_PATH_COORD[0-3]_NV matrices. A built-in fragment shader varying array gl_PathCoord of type vec4 receives the corresponding interpolated values. The number of elements in the gl_PathCoord array is 4. Although gradients and texture coordinates can also be implemented using the gl_FragCoord built-in fragment shader variable, it is generally more efficient to use gl_PathCoord, avoiding unnecessary per-fragment matrix multiplications.

MATRIX_PATH_COORD[0-3]_NV and MATRIX_PATH_TO_CLIP_NV can define a homogenous perspective transformation. It is up to the fragment shader to normalize the interpolated coordinates if necessary.

Filling a Path

When filling a path, the path segments must form zero or more closed contours. If any of the contours are left open, the resulting set of fragments is undefined. This requirement can be rephrased as follows, depending on the value of FILL_RULE_NV:

NON_ZERO_NV:

Each two-dimensional point has an equal number of path segments starting and ending at it.

EVEN_ODD_NV

Each two-dimensional point has an even number of path segments starting or ending at it.

Note that for any two points to be considered identical, the binary representations of their coordinates must match exactly.

To determine the segments to draw, the path commands are processed sequentially. The following temporary values are maintained during the process:

Each path command is processed depending on its type as follows. c[i] is used to denote the i'th value in the vertex coordinate array.

MOVE_TO_NV:

Replace the current position.
cp = (c[i+0], c[i+1]), i += 2.

LINE_TO_NV:

Draw a straight line from <cp> to (c[i+0], c[i+1]).
cp = (c[i+0], c[i+1]), i += 2.

QUADRATIC_BEZIER_TO_NV:

Draw a quadratic Bezier curve from <cp> to (c[i+2], c[i+3]) using
(c[i+0], c[i+1]) as the control point.
cp = (c[i+2], c[i+3]), i += 4.

CUBIC_BEZIER_TO_NV:

Draw a cubic Bezier curve from <cp> to (c[i+4], c[i+5]) using
(c[i+0], c[i+1]) and (c[i+2], c[i+3]) as the control points.
cp = (c[i+4], c[i+5]), i += 6.

START_MARKER_NV:

Replace the start position.
sp = cp.

CLOSE_NV:

If <sp> is undefined, ignore the command.
Otherwise, draw a straight line from <cp> to <sp>.
cp = sp.

STROKE_CAP[0-3]_NV:

Ignore the command.

START_MARKER_NV and CLOSE_NV commands can be used to implement subpath closure found in many vector graphics content formats. For filled paths, an explicit LINE_TO_NV command to the start position will produce the same result as CLOSE_NV. For stroked paths, the difference is that CLOSE_NV will join the closing line segment to the segment following the START_MARKER_NV command.

A fill rule is applied to determine if any given point is contained within the interior of the path. The fill rules are defined by projecting a ray from the point in question to infinity and counting the intersections of the ray and path segments. When looking along the direction of the ray, segments intersecting from left to right increment the counter and right to left segment intersections decrement the counter. If the fill rule is NON_ZERO_NV, the point is within the interior if the final count is non-zero. If the fill rule is EVEN_ODD_NV, the point is within the interior if the final count is odd. The counter must support at least 255 intersections. For more complex paths, the results are undefined.

Curves may be approximated within a limit specified by the PATH_QUALITY_NV parameter. The limit defines the radius of a disc in the window space. Placing the disc at each sampling point, the following rules are used to determine whether to generate the corresponding fragments:

Stroking a Path

Stroking is performed by sweeping a straight-line pen along each path segment, generating fragments for the sampling points touched by the pen. Additionally, cap and join styles may be applied at the start and end of the segments.

Cap and join styles are selected for each path segment based on the path commands adjacent to the one specifying the segment, and the values of the path parameters. The general rule is that the end of a segment is joined to start of the following segment if they are specified by adjacent path commands. If the start or end of a segment is not joined, a cap is generated instead.

Fill rule is not applied when stroking. Instead, a fragment is generated for each sampling point inside the stroke. Even in case the stroke sweeps over a sampling point multiple times, only one fragment is generated.

Dashing is not supported directly. Instead, this extension allows implementing dashing in user code by generating the corresponding.

Paths are stroked in a coordinate space distinct from the path user space and the clip space. The transformation from the stroke space to the path user space is controlled by the MATRIX_STROKE_TO_PATH_NV matrix. Both the path user space and the stroke space are two-dimensional, and thus only the 2x2 upper-left components of the matrix are used.

Conceptually, stroking a path consists of five steps. First, the path segments are transformed from the path user space to the stroke space using the inverse of the stroke-to-path matrix. Second, the set of points affected by the stroke is determined in the stroke space, using a straight-line pen that extends one unit into each direction. Third, the set of points is transformed from the stroke space back to the path user space using the stroke-to-path matrix. Fourth, the points are further transformed from the path user space to the clip space using the path-to-clip matrix. Fifth, a fragment is generated for each sampling point contained by the set of transformed points.

The stroke-to-path matrix allows specifying stroke width independent of how the path itself is transformed. Two common scenarios include scaling stroke, where the stroke width varies as the path-to-clip transformation changes, and non-scaling stroke, where the width remains constant in the clip space. For scaling stroke, the stroke-to-path matrix should be specified as an identity matrix multiplied by half of the desired stroke width in the path user space. For non-scaling stroke, it should be specified as the inverse of the path-to-clip matrix multiplied by half of the stroke width in the clip space.

The style of all joins is determined by the STROKE_JOIN_STYLE_NV path parameter, which can be set to one of the following values:

JOIN_MITER_NV:

Extend the incoming and outgoing stroke outlines until they intersect. If the distance between the intersection point and the center point exceeds STROKE_MITER_LIMIT_NV in the stroke space, apply a bevel join instead.

JOIN_ROUND_NV:

Connect the incoming and outgoing stroke outlines with a circular arc segment in the stroke space, corresponding to a radius of one unit.

JOIN_BEVEL_NV:

Connect the incoming and outgoing stroke outlines with a straight line.

JOIN_CLIPPED_MITER_NV:

Same as JOIN_MITER_NV if STROKE_MITER_LIMIT_NV is not exceeded. Otherwise, clip the extended outlines and connect them with a straight line. The clipping is done against a line whose distance from the center point is equal to STROKE_MITER_LIMIT_NV in the stroke space, and whose orientation is symmetrical with regards to the outlines.

The style of a start cap depends on the previous path command, and the style of an end cap depends on the next command. If the command is not STROKE_CAP[0-3]_NV, the cap style is STROKE_CAP_BUTT_NV. Otherwise, the style is determined by the corresponding STROKE_CAP[0-3]_STYLE_NV path parameter, each opf which can be set to one of the following values:

CAP_BUTT_NV:

Terminate the segment with a straight line connecting the two outline endpoints.

CAP_ROUND_NV:

Terminate the segment with a semicircle with radius equal to one in the stroke space.

CAP_SQUARE_NV:

Terminate the segment with a rectangle extending one unit along the path tangent.

CAP_TRIANGLE_NV:

Terminate the segment with a triangle with two vertices at the stroke outline endpoints, and a third vertex one unit along the path tangent.

As with fill, the path commands are processed sequentially, maintaining the following temporary values:

Each command is processed as follows, depending on its type:

MOVE_TO_NV:

LINE_TO_NV, QUADRATIC_BEZIER_TO_NV, and CUBIC_BEZIER_TO_NV:

START_MARKER_NV:

CLOSE_NV:

STROKE_CAP[0-3]_NV:

Path Programs

Paths are drawn using a special type of program object called a path program. Path programs function like normal program objects, except that they do not allow a vertex shader to be specified. Path programs are created with a new function CreatePathProgramNV().

Fragment Shader

Fragment shader depth values are obtained by transforming the homogenous vertex coordinates (x, y, 0, 1) into the clip space. This enables mixing 3D and path geometry using depth buffering.

Since path programs do not support vertex shaders, path fragment shaders cannot make use of user-defined varyings. Instead, this extension adds built-in variables gl_PathCoord[0-3] of type vec4 that receive interpolated vertex positions transformed with their respective MATRIX_PATH_COORD[0-3]_NV matrices.

The value of gl_FrontFacing is undefined when rendering paths.

The Rest of the Pipeline

When rendering paths, stencil functionality and backface culling are not applied. Blending, dithering, depth test, scissor test, polygon offset, and multisampling are applied as with other primitives.

Even though stencil test and operation are unavailable when rendering paths, the original contents of the stencil buffer are retained.

Path Buffers

Path buffers facilitate efficient rendering of animated text or other instanced path geometry by making it possible to render multiple path objects with a single draw call. A path buffer contains a list of path object handles and associated translation vectors.

Invariance Rules

Changing path parameters, viewport, transformations and clipping parameters may result in a different set of pixels to be rendered.

New Procedures and Functions

uint CreatePath NV (         enum datatype, 
                            sizei numCommands,
                             const ubyte* commands );
void DeletePath NV (         uint path );
void PathVerticesNV (        uint path,
                             const void* vertices );
void PathParameterfNV (      uint path,
                             enum paramType,
                             float param ); void PathParameteriNV (      uint path,
                             enum paramType,                              int param ); uint CreatePathProgram NV (  void ); void PathMatrixNV(           enum target,                              const float* value ); void DrawPathNV (            uint path,                              enum mode ); uint CreatePathbuffer NV (   sizei capacity ); void DeletePathbuffer NV (   uint buffer ); void PathbufferPathNV (      uint buffer,                              int index,                              uint path ); void PathbufferPositionNV (  uint buffer,                              int index,                              float x,                              float y ); void DrawPathbufferNV (      uint buffer,                              enum mode );

New Types

None

New Tokens

Accepted as the <paramType> parameter of PathParameterNV:

PATH_QUALITY_NV                 0x8ED8 
FILL_RULE_NV                    0x8ED9
STROKE_CAP0_STYLE_NV            0x8EE0 STROKE_CAP1_STYLE_NV            0x8EE1 STROKE_CAP2_STYLE_NV            0x8EE2 STROKE_CAP3_STYLE_NV            0x8EE3 STROKE_JOIN_STYLE_NV            0x8EE8 STROKE_MITER_LIMIT_NV           0x8EE9

Values for the ILL_RULE_NV path parameter:

EVEN_ODD_NV                      0x8EF0
NON_ZERO_NV                      0x8EF1

Values for the CAP[0-3]_STYLE_NV path parameter:

CAP_BUTT_NV                      0x8EF4
CAP_ROUND_NV                     0x8EF5 CAP_SQUARE_NV                   0x8EF6 CAP_TRIANGLE_NV                  0x8EF7

Values for the JOIN_STYLE_NV path parameter:

JOIN_MITER_NV                    0x8EFC
JOIN_ROUND_NV                    0x8EFD
JOIN_BEVEL_NV                    0x8EFE
JOIN_CLIPPED_MITER_NV            0x8EFF

Accepted as the <target> parameter of PathMatrixNV:

MATRIX_PATH_TO_CLIP_NV           0x8F04
MATRIX_STROKE_TO_PATH_NV         0x8F05
MATRIX_PATH_COORD0_NV            0x8F08
MATRIX_PATH_COORD1_NV            0x8F09
MATRIX_PATH_COORD2_NV            0x8F0A
MATRIX_PATH_COORD3_NV            0X8F0B

Accepted as the <mode> parameter of DrawPathbufferNV:

FILL_PATH_NV                     0x8F18
STROKE_PATH_NV                   0x8F19

Accepted as path commands by CreatePathNV:

MOVE_TO_NV                      0x00
LINE_TO_NV 0x01
QUADRATIC_BEZIER_TO_NV 0x02
CUBIC_BEZIER_TO_NV 0x03
START_MARKER_NV 0x20
CLOSE_NV 0x21
STROKE_CAP0_NV 0x40
STROKE_CAP1_NV 0x41
STROKE_CAP2_NV 0x42
STROKE_CAP3_NV 0x43

Additions to Chapter 2 of the OpenGL ES Specification

Add the following error conditions to Chapter 2.8, under DrawArrays:

"An INVALID_OPERATION error is generated if the current program is a path program."

Add the following error conditions to Chapter 2.8, under DrawElements:

"An INVALID_OPERATION error is generated if the current program is a path program."

Add the following error conditions to Chapter 2.15, under AttachShader.

"An INVALID_OPERATION error is generated if the program is a path program and the shader is a vertex shader."

Add the following error conditions to Chapter 2.15, under LinkProgram.

"Linking a program without a vertex shader will not fail if the program is a path program."

Additions to Chapter 3 of the OpenGL ES Specification

Add a new section between sections 3.5 (Polygons) and 3.6 (Pixel Rectangles)

"3.6 Paths

This extension adds a new type of primitive, paths, to OpenGL ES'

primitives - points, lines, polygons, pixel rectangles and bitmaps.

3.6.1 Path objects

New path objects are created with the call: 

uint CreatePath NV (      enum datatype, 
                          sizei numCommands, 
                          const ubyte* commands );

where <datatype> is the vertex data type and it must be one of [UNSIGNED_]BYTE, [UNSIGNED_]SHORT, [UNSIGNED_]INT, FLOAT, FIXED, <numCommands> is the number of commands in the path definition and <commands> is a pointer to an unsigned byte array of commands. Valid commands are listed below. The function returns a non-zero handle to the object or 0 on error.

An INVALID_ENUM error is generated if <datatype> is not one of the values specified above. An INVALID_VALUE error is generated if <numCommands> is less than zero or <numCommands> is greater than zero and <commands> is NULL or the <commands> array contains an invalid command.

TODO note that path objects can be shared between multiple contexts.

Path objects are deleted with the command

void DeletePathNV( uint path );

where <path> is the handle to the path object to delete. If the path is assigned to one or more path buffers, path resources are freed only when the last reference to the path is removed. Path handle is invalid after a call to DeletePathNV. An INVALID_VALUE error is generated if the path object does not exist.

Path vertices are specified with the command

void PathVerticesNV( uint path,
                     const void* vertices );

where <path> is the handle to the path object and <vertices> is a pointer to an array of vertices. <vertices> must contain at least as many coordinate tuples as is consumed by the associated path commands, otherwise the results are undefined, and may lead to a program crash. If <vertices> contains more coordinates than consumed by the path commands, the rest are silently ignored.

An INVALID_VALUE error is generated if the specified <path> object does not exist or if <vertices> is NULL and the path command requires vertices.

Path parameters are set using the commands

void PathParameterfNV( uint path,
                       enum paramType,
                       float param );

void PathParameteriNV( uint path,
                       enum paramType,
                       int param );

where <path> is the path object handle, <paramType> is the parameter to set and <param> is the value of the parameter.

The following symbols are accepted as <paramType>:

PATH_QUALITY_NV

Maximum allowed deviation from the ideal path measured in pixels. The default value is 0.5 pixels.

FILL_RULE_NV

Fill rule to use for filling paths. <param> must be either EVEN_ODD_NV or NON_ZERO_NV. The default value is EVEN_ODD_NV.

STROKE_CAPn_STYLE_NV

Cap style for the cap index n used when stroking a path. The default values are CAP_BUTT_NV.

STROKE_JOIN_STYLE_NV

Join style used when stroking a path. The default value is JOIN_MITER_NV.

STROKE_MITER_LIMIT_NV

Miter limit used when stroking a path with miter joins. If a join angle exceeds the limit, a miter join is converted into a bevel join. The default value is 4.

If paramType is PATH_QUALITY_NV in PathParameteriNV(), param is converted to a float. If paramType is not PATH_QUALITY_NV in PathParameterfNV(), param is converted to an int.

An INVALID_VALUE error is generated if the <path> object does not exist.

An INVALID_ENUM error is generated if <paramType> is not any of the above.

An INVALID_VALUE error is generated if <paramType> is PATH_QUALITY_NV and <param> <= 0 or <paramType> is STROKE_MITER_LIMIT_NV and <param> < 1. An INVALID_ENUM error is generated if <paramType> is FILL_RULE_NV and param is not a valid fill rule, <paramType> is STROKE_CAPn_STYLE_NV and <param> is not a valid cap style, or <paramType> is STROKE_JOIN_STYLE_NV and <param> is not a valid join style.

Path transformations are set using the call

void PathMatrixNV( enum target,
                   const float* value );

where <value> must specify a 4x4 matrix.

The following values are accepted as the <target> parameter:

MATRIX_PATH_TO_CLIP_NV

Used for transforming path vertices into clip space when drawing a path.

MATRIX_STROKE_TO_PATH_NV

Used for transforming the pen when stroking a path. The vertices are subsequently transformed into clip space by MATRIX_PATH_TO_CLIP_NV matrix. Only the top-left 2x2 submatrix is used.

MATRIX_PATH_COORDn_NV

Used for generating values for gl_PathCoord[0-3] varyings for fragment shader by transforming vertex positions.

The default value for all matrices is the identity matrix.

An INVALID_ENUM error is generated if <target> is not any of the above. An INVALID_VALUE error is generated if value is NULL.

A path is rendered using the call

void DrawPathNV( uint path,
                 enum mode );

where <path> is the path to be drawn and <mode> must be either FILL_PATH_NV or STROKE_PATH_NV.

An INVALID_VALUE error is generated if the <path> does not exist. An INVALID_OPERATION error is generated if there is no current program, the current program is not a path program, stencil test is enabled, polygon mode is not GL_FILL, or shade model is not GL_SMOOTH. An INVALID_ENUM is generated if <mode> is not FILL_PATH_NV or STROKE_PATH_NV.

3.6.2 Path programs

A path program is a special type of program object that otherwise behaves like a normal program object, but allows attaching only a fragment shader.

Path programs are created using the command

uint CreatePathProgramNV( void )

The function returns 0 on error (i.e., OUT_OF_MEMORY).

TODO describe LinkProgram error conditions here for clarity?

3.6.3 Path buffers

Path buffers can be used for efficiently rendering multiple instances of a set of path objects with a single draw call. Each path in a path buffer has an associated position vector that allows specifying a model space position offset for that path. Path buffers are created using the function

uint CreatePathbufferNV( sizei capacity )

where <capacity> is the number of paths in a path buffer. This function returns a non-zero handle to a path buffer object or 0 on error.

An INVALID_VALUE error is generated if capacity < 0.

TODO note that path buffer objects can be shared between multiple contexts

Path buffers are deleted using the call

void DeletePathbufferNV( uint buffer );

where <buffer> is the handle to the path buffer. Path buffer handle is invalid after a call to DeletePathbufferNV.

An INVALID_VALUE error is generated if the path buffer does not exist.

A path can be added to or removed from a path buffer with the function

void PathbufferPathNV( uint buffer,
                       int index,
                       uint path );

where <buffer> is the path buffer object handle, <index> is the index of the path buffer slot and <path> is the path object handle. Path buffer paths are mutable and can be re-specified later. Calling PathbufferPathNV with <path> set to zero removes path from the path buffer and leaves the slot corresponding to <index> empty.

An INVALID_VALUE error is generated if the path buffer object <buffer> does not exist, or <index> is less than zero, or greater than or equal to the path buffer capacity.

Path buffer path position vector is specified using the call

void PathbufferPositionNV( uint buffer,
                           int index,
                           float x,
                           float y );

where <buffer> is the path buffer object handle, <index> is the index of the path buffer slot and <x> and <y> specify the translation. Path buffer path translations are mutable and can be re-specified later.

An INVALID_VALUE error is generated if the path buffer does not exist or index < 0 or index >= path buffer capacity.

All paths in a path buffer are rendered using the command

void DrawPathbufferNV( uint buffer,
                       enum mode );

An INVALID_VALUE error is generated if <buffer> does not exist. An INVALID_OPERATION error is generated if there is no current program, the current program is not a path program, stencil test is enabled, polygon mode is not GL_FILL, or shade model is not GL_SMOOTH. An INVALID_ENUM is generated if <mode> is not FILL_PATH_NV or STROKE_PATH_NV. The effect of a DrawPathbufferNV call is the same as if DrawPathNV was called for each individual path reference in the path buffer, ordered from the first index to the last."

 

 

 


NVIDIA® GameWorks™ Documentation Rev. 1.0.200608 ©2014-2020. NVIDIA Corporation. All Rights Reserved.