textureWrap()

Changes the way textures behave when a shape’s uv coordinates go beyond the texture.

In order for texture() to work, a shape needs a way to map the points on its surface to the pixels in an image. Built-in shapes such as rect() and box() already have these texture mappings based on their vertices. Custom shapes created with vertex() require texture mappings to be passed as uv coordinates.

Each call to vertex() must include 5 arguments, as in vertex(x, y, z, u, v), to map the vertex at coordinates (x, y, z) to the pixel at coordinates (u, v) within an image. For example, the corners of a rectangular image are mapped to the corners of a rectangle by default:

// Apply the image as a texture.
texture(img);

// Draw the rectangle.
rect(0, 0, 30, 50);

If the image in the code snippet above has dimensions of 300 x 500 pixels, the same result could be achieved as follows:

// Apply the image as a texture.
texture(img);

// Draw the rectangle.
beginShape();

// Top-left.
// u: 0, v: 0
vertex(0, 0, 0, 0, 0);

// Top-right.
// u: 300, v: 0
vertex(30, 0, 0, 300, 0);

// Bottom-right.
// u: 300, v: 500
vertex(30, 50, 0, 300, 500);

// Bottom-left.
// u: 0, v: 500
vertex(0, 50, 0, 0, 500);

endShape();

textureWrap() controls how textures behave when their uv's go beyond the texture. Doing so can produce interesting visual effects such as tiling. For example, the custom shape above could have u-coordinates are greater than the image’s width:

// Apply the image as a texture.
texture(img);

// Draw the rectangle.
beginShape();
vertex(0, 0, 0, 0, 0);

// Top-right.
// u: 600
vertex(30, 0, 0, 600, 0);

// Bottom-right.
// u: 600
vertex(30, 50, 0, 600, 500);

vertex(0, 50, 0, 0, 500);
endShape();

The u-coordinates of 600 are greater than the texture image’s width of 300. This creates interesting possibilities.

The first parameter, wrapX, accepts three possible constants. If CLAMP is passed, as in textureWrap(CLAMP), the pixels at the edge of the texture will extend to the shape’s edges. If REPEAT is passed, as in textureWrap(REPEAT), the texture will tile repeatedly until reaching the shape’s edges. If MIRROR is passed, as in textureWrap(MIRROR), the texture will tile repeatedly until reaching the shape’s edges, flipping its orientation between tiles. By default, textures CLAMP.

The second parameter, wrapY, is optional. It accepts the same three constants, CLAMP, REPEAT, and MIRROR. If one of these constants is passed, as in textureWRAP(MIRROR, REPEAT), then the texture will MIRROR horizontally and REPEAT vertically. By default, wrapY will be set to the same value as wrapX.

Note: textureWrap() can only be used in WebGL mode.