Images & Graphics

Until now, we have only been using solid colors to fill shapes. However, you can also use images or bitmaps as a fill pattern.

There are three steps required to do this:

1. Loading the image from disk into memory.
2. Uploading the texture to the GPU.
3. Creating a VGPaint from the texture that can be used as a fill pattern.

Loading Images

The first step is to load the image from disk into memory. This can be done with the Texture2D class.

$texture = Texture2D::fromDisk('/path/to/your/image.png', Texture2D::CHANNEL_RGBA, false);

In the Vector Graphics API, we only support RGBA (4-channel) images. The last parameter is a boolean that indicates whether the image should be flipped vertically. This is required because OpenGL and the Vector Graphics API have different coordinate systems.

Uploading the Texture

The next step is to upload the texture to the GPU.

$image = $vg->imageFromTexture($texture);

Note that there are two optional arguments that can be passed to this method:

1. Repeat Mode: This 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.

   

2. Filter Mode: This 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.

A full function call would look like this:

$image = $vg->imageFromTexture($texture, VGImage::REPEAT_XY, VGImage::FILTER_LINEAR);

Creating a Paint

The last step is to create a paint from the image. The paint is defined in global space and can be used to fill or stroke any shape.

// makePaint(x, y, width, height, angle, alpha)
$imagePaint = $image->makePaint(0, 0, 500, 500);

The makePaint method takes six arguments:

1. x: The x-coordinate of the top left corner of the paint.
2. y: The y-coordinate of the top left corner of the paint.
3. width: The width of the paint.
4. height: The height of the paint.
5. angle: The angle of the paint in radians. (The rotation is around the top left corner of the paint.)
6. alpha: The alpha value of the paint.

Using the Paint

The paint can now be used to fill or stroke any shape.

$vg->beginPath();
$vg->rect(0, 0, 500, 500);
$vg->fillPaint($imagePaint);
$vg->fill();

In Global Space?

The paint is defined in global space. This means that the paint will not be affected by the shape it is used to fill. This might be a bit counterintuitive at first.

A simple example to visualize this is to create a paint that covers the entire screen and then draw a rectangle in the middle of the screen with the paint.

$paint = $myImage->makePaint(0, 0, 512, 512);
$vg->beginPath();
$vg->rect(100, 100, 200, 200);
$vg->fillPaint($paint);
$vg->fill();