gfx2-iconIn today’s Graphics 2.0 tutorial, we’ll explore how to use repeating fills on display objects. This allows you to fill a larger display object with a “tiled pattern” in a variety of repetition modes like repeat, mirror repeat, or clamp to edge. For each pattern, you can set the x and y offset of the fill, rotate the repeating fill, and even scale the fill, all independently of the object. In addition, you can apply these fill settings via explicit declaration or even a gradual transition to achieve a variety of animated effects.

Getting Started

Let’s begin by creating a basic 600×400 newRect() object, centered on the screen. We won’t bother filling this with any solid fill color, since we’ll be applying a repeating fill in the next step.

Now let’s set the default texture wrapping mode for both the x and y directions. This is achieved by using display.setDefault(), the same API you’ve used in the past for setting your app’s default fill color, text color, background color, etc. In Graphics 2.0, this has been extended to the texture wrapping mode as well.

The available texture wrapping modes are as follows:

  • “clampToEdge” — this is the default mode; it clamps the texture to either the x or y direction. Clamped fills will not repeat in the clamped direction.
  • “repeat” — the fill will repeat in a tiled manner across the entire span of the filled object, as if identical tiles were simply laid out in the same orientation, side by side.
  • “mirroredRepeat” — the fill will repeat in a mirrored pattern, wherein each neighboring tile will mirror the one beside it.

logo-150Next, we’ll fill the display object with a 300×300 image:

This is the exact same method as described in the Fills and Strokes tutorial. As you can see, the fill image is stretched to fill the entire width and height. Thus, with our minimal amount of code so far, we’re not seeing any behavioral changes with the new texture wrapping modes — but we’ll address that in a moment.

rect logo-repeat-0

Scaling the Fill

Obviously, filling the entire shape with one stretched image doesn’t result in a repeating fill. To get the intended visual repetition in place, we need to use scaling methods on the fill image. This requires just two additional lines of code:

However, the fill image is still stretched — the GPU simply takes the stretched fill texture and scales it to 50% on each axis. Thus, to make our fill pattern retain its correct 1:1 ratio across the repeated fill, we can use a simple algorithm to calculate the proper scaling ratios for the filled region, regardless of its width and height:

Now, let’s adjust the repeating fill by multiplying each scale setting by its appropriate factor:

The result is a 1:1 ratio for the fill repetition — meaning, the fill itself is at its original size of 300×300 pixels, repeating within the bounds of the filled object and overflowing outside the edges as expected.

Offsetting the Fill

One common factor you’ll notice in the previous examples is that the fill repetition is always centered within the filled object. No matter the scale, a fill “tile” will reside in the center of the object and then repeat outward in all directions, assuming you haven’t clamped either of the axes.

While this default centering will probably work in most cases, what if you want to offset the fill? For example, set the fill pattern to begin in the upper-left and then repeat to the right and downward? This is possible by adjusting the x and y values of the fill, as follows:

Instead of passing a specific pixel value to the x and y values, a value between -1 and 1 is required. This tells the GPU to offset the pattern by a full repetition in one of four directions. So, setting 0.5 as the x property will shift the pattern half of one repetition distance on the x axis.

One important distinction is that setting a positive x value will shift the pattern to the left, while a negative x value will shift the object to the right. Similarly, a positive y value will offset the pattern in an upward direction, and negative y downward.

Also, note that if your fill pattern tile is not a divisible size in relation to the larger object — for example, a 300×300 tile filling a 820×480 object — you’ll need to calculate the proper offset values between -1 and 1 to achieve the accurate “corner alignment.” In such instances, the offset values will not be a predictable 0.5 or -0.5.

Rotating the Fill

logo-repeat-4Lastly, you can rotate the fill independently of the object:

In this instance, rotation is performed in familiar degrees from 0 to 360. Rotation is applied around the center of the object and cannot be set to an anchor point (fills do not accept the anchorX or anchorY properties).

Transitioning the Fill

A final, powerful feature of repeating fills is the ability to transition them via basic Corona transitions. This allows you to shift, rotate, or scale the fill pattern within the filled object, and independently of any transition that is being performed upon the filled object.

This capability allows you to perform a variety of interesting effects upon an object, for example, a repeating water pattern “flowing” slowly across the filled object in an endless cycle:

In Summary

Repeating fills bring a variety of new visual and animated possibilities to Corona SDK. If you’re a Pro or Enterprise subscriber with access to Graphics 2.0 Daily Builds, please download a recent build and start experimenting with the possibilities!

Continue reading: 

Tutorial: Repeating Fills in Graphics 2.0