VGContext¶
The VGContext is your canvas for 2D vector graphics. It wraps a NanoVG rendering context and gives
you everything you need to draw crisp, resolution-independent shapes, gradients, images and text
directly on top of your OpenGL scene. You build a shape by describing a path, choose how it is
painted with a VGColor or a
VGPaint, and then fill or stroke it.
Looking for a walkthrough?
This page is the exhaustive class reference. If you are just getting started, the Vector Graphics user guide walks you through creating a context, drawing your first shapes, colors, gradients, images and text with small runnable examples.
Usage¶
Everything you draw happens between a beginFrame and an endFrame call. Inside that frame you open
a path, describe your geometry, pick a color and then fill it.
use GL\VectorGraphics\{VGContext, VGColor};
// create a context once, antialiasing enabled
$vg = new VGContext(VGContext::ANTIALIAS);
// ... inside your render loop, after clearing the screen:
$vg->beginFrame($windowWidth, $windowHeight, $devicePixelRatio);
$vg->beginPath();
$vg->rect(100, 100, 200, 120);
$vg->fillColor(VGColor::red());
$vg->fill();
// dispatch all queued draw commands to the GPU
$vg->endFrame();
Constants¶
Context flags¶
Pass these to the constructor, combined with the bitwise OR operator (|).
| Constant | Value | Meaning |
|---|---|---|
VGContext::ANTIALIAS |
1 | Smooth the edges of shapes and text. |
VGContext::STENCIL_STROKES |
2 | More accurate stroke rendering for overlapping shapes. |
VGContext::DEBUG |
4 | Enable extra error checks while developing. |
Path winding¶
Used with pathWinding and arc to control solid versus hole subpaths.
| Constant | Value | Meaning |
|---|---|---|
VGContext::CCW |
1 | Counter-clockwise winding (solid shapes). |
VGContext::CW |
2 | Clockwise winding (holes). |
VGContext::SOLID |
1 | Alias of CCW, reads better when filling. |
VGContext::HOLE |
2 | Alias of CW, reads better when cutting holes. |
Line caps and joins¶
Used with lineCap and lineJoin.
| Constant | Value | Meaning |
|---|---|---|
VGContext::LINECAP_BUTT |
0 | Flat cap flush with the line end. |
VGContext::LINECAP_ROUND |
1 | Rounded cap. |
VGContext::LINECAP_SQUARE |
2 | Square cap extending past the line end. |
VGContext::LINEJOIN_BEVEL |
3 | Beveled corner. |
VGContext::LINEJOIN_MITER |
4 | Sharp mitered corner. |
Frame Lifecycle¶
beginFrame¶
Begins drawing a new frame.
Example:
$vg->beginFrame($windowWidth, $windowHeight, $devicePixelRatio);
// draw commands here
$vg->endFrame();
- arguments
-
float$windowWidthThe width of the window in pixels.float$windowHeightThe height of the window in pixels.float$devicePixelRatioThe device pixel ratio.
- returns
-
void
cancelFrame¶
cancelFrame
- returns
-
void
endFrame¶
Ends drawing the current frame.
Example:
$vg->beginFrame($windowWidth, $windowHeight, $devicePixelRatio);
// draw commands here
$vg->endFrame();
- returns
-
void
Render State¶
The context keeps a stack of render states (transform, styles, scissor). Wrap changes in
save / restore to keep them local.
save¶
Saves the current render state onto a state stack.
Example:
- returns
-
void
restore¶
Restores the render state from the state stack.
Example:
- returns
-
void
reset¶
Resets the current render state to default values.
- returns
-
void
shapeAntiAlias¶
shapeAntiAlias
- arguments
-
int$enabled
- returns
-
void
globalAlpha¶
globalAlpha
- arguments
-
float$alpha
- returns
-
void
globalCompositeOperation¶
globalCompositeOperation
- arguments
-
int$op
- returns
-
void
globalCompositeBlendFunc¶
globalCompositeBlendFunc
- arguments
-
int$sfactorint$dfactor
- returns
-
void
globalCompositeBlendFuncSeparate¶
globalCompositeBlendFuncSeparate
function globalCompositeBlendFuncSeparate(int $srcRGB, int $dstRGB, int $srcAlpha, int $dstAlpha) : void
- arguments
-
int$srcRGBint$dstRGBint$srcAlphaint$dstAlpha
- returns
-
void
Fill & Stroke Style¶
These decide how the next fill or stroke is painted.
fillColor¶
Sets the fill color.
Example:
- arguments
-
\GL\VectorGraphics\VGColor$colorThe fill color.
- returns
-
void
strokeColor¶
Sets the stroke color.
Example:
- arguments
-
\GL\VectorGraphics\VGColor$colorThe stroke color.
- returns
-
void
fillColori¶
Sets the fill color using integer values.
- arguments
-
int$rThe red component (0-255).int$gThe green component (0-255).int$bThe blue component (0-255).int$aThe alpha component (0-255), where 255 is fully opaque.
strokeColori¶
Sets the stroke color using integer values.
- arguments
-
int$rThe red component (0-255).int$gThe green component (0-255).int$bThe blue component (0-255).int$aThe alpha component (0-255), where 255 is fully opaque.
fillColorVec4¶
Sets the fill color using a Vec4 object.
- arguments
-
\GL\Math\Vec4$vecA vector containing the RGBA components of the color.
strokeColorVec4¶
Sets the stroke color using a Vec4 object.
- arguments
-
\GL\Math\Vec4$vecA vector containing the RGBA components of the color.
fillPaint¶
fillPaint
- arguments
-
\GL\VectorGraphics\VGPaint$paint
- returns
-
void
strokePaint¶
strokePaint
- arguments
-
\GL\VectorGraphics\VGPaint$paint
- returns
-
void
strokeWidth¶
Sets the stroke width.
Example:
- arguments
-
float$sizeThe stroke width.
- returns
-
void
miterLimit¶
miterLimit
- arguments
-
float$limit
- returns
-
void
lineCap¶
lineCap
- arguments
-
int$cap
- returns
-
void
lineJoin¶
lineJoin
- arguments
-
int$join
- returns
-
void
Gradients & Paints¶
Each of these returns a VGPaint you hand to
fillPaint or strokePaint.
linearGradient¶
Creates a linear gradient paint object.
function linearGradient(float $sx, float $sy, float $ex, float $ey, \GL\VectorGraphics\VGColor $icol, \GL\VectorGraphics\VGColor $ocol) : \GL\VectorGraphics\VGPaint
The gradient is defined by the start and end points, as well as the colors at these points.
$x1 = 50;
$y1 = 150;
$x2 = 350;
$y2 = 450;
$color1 = new VGColor(0.051, 0.682, 0.914, 1.0);
$color2 = new VGColor(0.169, 0.961, 0.596, 1.0);
$paint = $vg->linearGradient($x1, $y1, $x2, $y2, $color1, $color2);
- arguments
-
float$sxThe x-coordinate of the start point of the gradient.float$syThe y-coordinate of the start point of the gradient.float$exThe x-coordinate of the end point of the gradient.float$eyThe y-coordinate of the end point of the gradient.\VGColor$icolThe color at the start point of the gradient.\VGColor$ocolThe color at the end point of the gradient.
boxGradient¶
Creates a box gradient paint object.
function boxGradient(float $x, float $y, float $w, float $h, float $r, float $f, \GL\VectorGraphics\VGColor $icol, \GL\VectorGraphics\VGColor $ocol) : \GL\VectorGraphics\VGPaint
$x = 100;
$y = 100;
$width = 200;
$height = 100;
$radius = 10;
$feather = 20;
$color1 = new VGColor(0.051, 0.682, 0.914, 1.0);
$color2 = new VGColor(0.169, 0.961, 0.596, 1.0);
$paint = $vg->boxGradient($x, $y, $width, $height, $radius, $feather, $color1, $color2);
- arguments
-
float$xThe x-coordinate of the top left corner of the box.float$yThe y-coordinate of the top left corner of the box.float$wThe width of the box.float$hThe height of the box.float$rThe corner radius of the box.float$fThe feathering amount (how much the gradient fades).\VGColor$icolThe color inside the box.\VGColor$ocolThe color outside the box.
radialGradient¶
Creates a radial gradient paint object.
function radialGradient(float $cx, float $cy, float $inr, float $outr, \GL\VectorGraphics\VGColor $icol, \GL\VectorGraphics\VGColor $ocol) : \GL\VectorGraphics\VGPaint
The gradient is defined by the center point and two radii, with the color transitioning from the inner to the outer radius.
$cx = 150;
$cy = 150;
$innerRadius = 50;
$outerRadius = 100;
$color1 = new VGColor(0.914, 0.051, 0.682, 1.0);
$color2 = new VGColor(0.961, 0.596, 0.169, 1.0);
$paint = $vg->radialGradient($cx, $cy, $innerRadius, $outerRadius, $color1, $color2);
- arguments
-
float$cxThe x-coordinate of the center of the gradient.float$cyThe y-coordinate of the center of the gradient.float$inrThe inner radius of the gradient.float$outrThe outer radius of the gradient.\VGColor$icolThe color at the inner radius.\VGColor$ocolThe color at the outer radius.
Images & SVG¶
Turn a Texture2D into a
VGImage, or draw a parsed
SVGImage straight into the frame.
imageFromTexture¶
Creates a VGImage object from a given texture.
function imageFromTexture(\GL\Texture\Texture2D $texture, int $repeatMode = \GL\VectorGraphics\VGImage::REPEAT_NONE, int $filterMode = \GL\VectorGraphics\VGImage::FILTER_LINEAR) : \GL\VectorGraphics\VGImage
This will upload the texture to the GPU.
- arguments
-
\GL\Texture\Texture2D$textureThe texture to create the image from.int$repeatModeThis can be either VGImage::REPEAT_XY, VGImage::REPEAT_X, VGImage::REPEAT_Y, or VGImage::REPEAT_NONE. This controls how the image is repeated when the shape is larger than the image. The default is VGImage::REPEAT_NONE.int$filterModeThis can be either VGImage::FILTER_LINEAR or VGImage::FILTER_NEAREST. This controls how the image is filtered when it is scaled. The default is VGImage::FILTER_LINEAR.
imageFromHandle¶
Creates a VGImage object from a given texture handle.
function imageFromHandle(int $handle, int $width, int $height, int $repeatMode = \GL\VectorGraphics\VGImage::REPEAT_NONE, int $filterMode = \GL\VectorGraphics\VGImage::FILTER_LINEAR) : \GL\VectorGraphics\VGImage
This will reference the texture already uploaded to the GPU.
$image = $vg->imageFromHandle($handle, $width, $height, VGImage::REPEAT_XY, VGImage::FILTER_LINEAR);
- arguments
-
int$handleThe GPU handle of the texture.int$widthThe width of the texture.int$heightThe height of the texture.int$repeatModeThis can be either VGImage::REPEAT_XY, VGImage::REPEAT_X, VGImage::REPEAT_Y, or VGImage::REPEAT_NONE. This controls how the image is repeated when the shape is larger than the image. The default is VGImage::REPEAT_NONE.int$filterModeThis can be either VGImage::FILTER_LINEAR or VGImage::FILTER_NEAREST. This controls how the image is filtered when it is scaled. The default is VGImage::FILTER_LINEAR.
imageSize¶
imageSize
- arguments
-
int$imageint$wint$h
- returns
-
void
deleteImage¶
deleteImage
- arguments
-
int$image
- returns
-
void
drawSVG¶
Renders a parsed SVGImage as vector paths into the current frame.
function drawSVG(\GL\VectorGraphics\SVGImage $svg, float $x = 0.0, float $y = 0.0, ?float $w = null, ?float $h = null) : void
When $w and $h are omitted the SVG is drawn at its native size, otherwise it is scaled to fit the given width/height.
Only solid fills/strokes are rendered; gradient paints are skipped for now. Alpha masks (mask="url(#id)") are honoured as a 1-bit (hard edged) clip.
- arguments
-
\SVGImage$svgThe parsed SVG image to draw.float$xThe x-coordinate of the top left corner.float$yThe y-coordinate of the top left corner.float|null$wTarget width; null draws at native width.float|null$hTarget height; null draws at native height.
Transforms¶
Transforms are applied on top of each other and stored in the render state, so they respect
save / restore.
resetTransform¶
resetTransform
- returns
-
void
transform¶
transform
- arguments
-
float$afloat$bfloat$cfloat$dfloat$efloat$f
- returns
-
void
translate¶
translate
- arguments
-
float$xfloat$y
- returns
-
void
rotate¶
rotate
- arguments
-
float$angle
- returns
-
void
skewX¶
skewX
- arguments
-
float$angle
- returns
-
void
skewY¶
skewY
- arguments
-
float$angle
- returns
-
void
scale¶
scale
- arguments
-
float$xfloat$y
- returns
-
void
currentTransform¶
currentTransform
- arguments
-
\GL\Buffer\FloatBuffer$buffer
- returns
-
void
transformPoint¶
Transforms a point using the current transformation matrix.
- arguments
-
float$xThe x-coordinate of the point.float$yThe y-coordinate of the point.
- returns
-
\GL\Math\Vec2The transformed point as a Vec2 object.
transformVec2¶
Transforms a vector using the current transformation matrix.
- arguments
-
\GL\Math\Vec2$vecThe vector to transform.
- returns
-
\GL\Math\Vec2The transformed vector.
transformPointCurrent¶
transformPointCurrent
- arguments
-
float$dstxfloat$dstyfloat$srcxfloat$srcy
- returns
-
void
Scissoring¶
Limit drawing to a rectangular region. Like transforms, scissors are part of the render state.
scissor¶
scissor
- arguments
-
float$xfloat$yfloat$wfloat$h
- returns
-
void
intersectScissor¶
intersectScissor
- arguments
-
float$xfloat$yfloat$wfloat$h
- returns
-
void
resetScissor¶
resetScissor
- returns
-
void
Building Paths¶
Open a new path with beginPath, then describe it with these commands before you
fill or stroke it.
beginPath¶
Begins a new path.
Example:
- returns
-
void
moveTo¶
moveTo
- arguments
-
float$xfloat$y
- returns
-
void
lineTo¶
lineTo
- arguments
-
float$xfloat$y
- returns
-
void
bezierTo¶
bezierTo
- arguments
-
float$c1xfloat$c1yfloat$c2xfloat$c2yfloat$xfloat$y
- returns
-
void
quadTo¶
quadTo
- arguments
-
float$cxfloat$cyfloat$xfloat$y
- returns
-
void
arcTo¶
arcTo
- arguments
-
float$x1float$y1float$x2float$y2float$radius
- returns
-
void
closePath¶
closePath
- returns
-
void
pathWinding¶
pathWinding
- arguments
-
int$dir
- returns
-
void
arc¶
arc
- arguments
-
float$cxfloat$cyfloat$rfloat$a0float$a1int$dir
- returns
-
void
rect¶
Creates a rectangle path.
Example:
- arguments
-
float$xThe x-coordinate of the top-left corner.float$yThe y-coordinate of the top-left corner.float$wThe width of the rectangle.float$hThe height of the rectangle.
- returns
-
void
roundedRect¶
roundedRect
- arguments
-
float$xfloat$yfloat$wfloat$hfloat$r
- returns
-
void
roundedRectVarying¶
roundedRectVarying
function roundedRectVarying(float $x, float $y, float $w, float $h, float $radTopLeft, float $radTopRight, float $radBottomRight, float $radBottomLeft) : void
- arguments
-
float$xfloat$yfloat$wfloat$hfloat$radTopLeftfloat$radTopRightfloat$radBottomRightfloat$radBottomLeft
- returns
-
void
ellipse¶
ellipse
- arguments
-
float$cxfloat$cyfloat$rxfloat$ry
- returns
-
void
circle¶
Creates a circle path.
Example:
- arguments
-
float$cxThe x-coordinate of the center.float$cyThe y-coordinate of the center.float$rThe radius of the circle.
- returns
-
void
Rendering Paths¶
fill¶
Fills the current path with the current fill color or paint.
Example:
- returns
-
void
fillEvenOdd¶
fillEvenOdd
- returns
-
void
stroke¶
Strokes the current path with the current stroke color or paint.
Example:
- returns
-
void
Clipping¶
clip¶
clip
- returns
-
void
resetClip¶
resetClip
- returns
-
void
saveClip¶
saveClip
- returns
-
void
restoreClip¶
restoreClip
- returns
-
void
Fonts & Text¶
Load a font once with createFont, then set the size and alignment
(using the VGAlign constants) before drawing with
text or textBox.
createFont¶
createFont
- arguments
-
string$namestring$filename
- returns
-
int
createFontAtIndex¶
createFontAtIndex
- arguments
-
string$namestring$filenameint$fontIndex
- returns
-
int
findFont¶
findFont
- arguments
-
string$name
- returns
-
int
addFallbackFontId¶
addFallbackFontId
- arguments
-
int$baseFontint$fallbackFont
- returns
-
int
addFallbackFont¶
addFallbackFont
- arguments
-
string$baseFontstring$fallbackFont
- returns
-
int
resetFallbackFontsId¶
resetFallbackFontsId
- arguments
-
int$baseFont
- returns
-
void
resetFallbackFonts¶
resetFallbackFonts
- arguments
-
string$baseFont
- returns
-
void
fontSize¶
fontSize
- arguments
-
float$size
- returns
-
void
fontBlur¶
fontBlur
- arguments
-
float$blur
- returns
-
void
textLetterSpacing¶
textLetterSpacing
- arguments
-
float$spacing
- returns
-
void
textLineHeight¶
textLineHeight
- arguments
-
float$lineHeight
- returns
-
void
textAlign¶
textAlign
- arguments
-
int$align
- returns
-
void
fontFaceId¶
fontFaceId
- arguments
-
int$font
- returns
-
void
fontFace¶
fontFace
- arguments
-
string$font
- returns
-
void
text¶
Draws text at the specified position.
Example:
- arguments
-
float$xThe x-coordinate of the text position.float$yThe y-coordinate of the text position.string$stringThe text string to draw.
- returns
-
floatfloat The horizontal advance of the text.
textBox¶
textBox
- arguments
-
float$xfloat$yfloat$breakRowWidthstring$string
- returns
-
void
textBounds¶
Calculates the bounding box of the specified text and returns the horizontal advance.
Example:
$vg->fontSize(18.0);
$bounds = new Vec4();
$advance = $vg->textBounds(100, 100, "Hello, World!", $bounds);
echo "Text bounds: " . $bounds . "\n";
echo "Text advance: " . $advance . "\n";
- arguments
-
float$xThe x of the text position.float$yThe y of the text position.string$stringThe text string to measure.?\GL\Math\Vec4$boundsVec4 object in which the calculated bounds are stored [xmin, ymin, xmax, ymax].
- returns
-
floatThe horizontal advance of the text.
textBoxBounds¶
textBoxBounds
function textBoxBounds(float $x, float $y, float $breakRowWidth, string $string, ?\GL\Math\Vec4 &$bounds = NULL) : void
- arguments
-
float$xfloat$yfloat$breakRowWidthstring$string?\GL\Math\Vec4$bounds
- returns
-
void
textMetrics¶
textMetrics
- arguments
-
float$ascenderfloat$descenderfloat$lineh
- returns
-
void