Vector graphics rendering in Unreal Engine: Part 2
Building a dynamic rectangle widget with independent rounded corners and border widths.
When I first made the argument for the type of graphics API that we’ve now integrated, I used the example of a simple box style with a background color and rounded corners. It seems trivial, but this is the type of thing that’s currently pretty laborious to build with Unreal Engine’s UI tools, requiring either a 9-sliced texture asset or a UI material with a complex signed distance function to pull off the rounded corners.
But the CSS spec allows for quite a bit more flexibility than that simple example demonstrated. We can round corners independenly, for example:
(If you’re wondering about the practicality of that technique, I’m using it on this very blog: Notice how the top-left corners of the code blocks’ main content boxes are the only ones that are squared, and how only the top corners of the “tabs” displaying the filenames are rounded.)
Independent borders can also be applied via CSS:
That’s a technique I use very often, for example, to highlight the active item in a navigation list:
- Lorem
- Ipsum
- Dolor
- Sit Amet
Building on the work we did in Part 1, we’re going to build a UMG widget that implements these features using Skia.
A brief exploration of Skia’s API
One of Skia’s principal raisons d’être is to serve as the rendering engine behind Google Chrome, but its API is quite a bit lower-level than the CSS specification, so you won’t find a simple SkCanvas method that directly does what we’re aiming for. Since it’s open-source, we could dig through Chromium’s source code to try and find its implementation of these features, but my experience with reading Google source code leads me to suspect that, wihout assistance, we’d run into a maze of abstractions that would take quite a while to trace down to the actual Skia calls we’re interested in.
Instead, we’ll take a look at Skia’s API and forge our own path (pun intended). The simplest place to start is with SkRect. We can draw a simple rectangle, without rounded corners, like this:
That will draw a 100 × 100 white rectangle on a black background, anchored to the top left corner of the surface. Thinking of a rectangle in terms of each side’s offset from the origin is not overly difficult, but also not the most intuitive thing in the world. Most Skia types, including SkRect, also have static methods to construct them from various sets of parameters, like this one that takes offsets and dimensions, so you don’t need to manually add the top and left offsets to the width and height to derive the correct bottom and right offsets:
But what if we want rounded corners? Skia also has an SkRRect to represent rounded rectangles, but we want independently rounded corners. Instead, we’ll try to come up with a solution using the path-drawing API.
Using the SkPath API
(Important: If you’re reading this because you’re trying to actually achieve the end goal, and not just for entertainment or general education, you may want to skip ahead to the next section.)
SkPath represents an arbitrary vector path, of the sort that you might create with the ubiquitous “pen tool” in an application like Inkscape, Figma, or Adobe Illustrator. In Skia, we define a path by issuing a sequence of commands, which you can think of as describing actions to be performed by a virtual pen.
The main commands we’re interested in are:
moveTo(x, y), which raises the pen from the surface and presses its tip down at a new set of coordinateslineTo(x, y), which draws a straight line from the pen’s current location to the new set of coordinatesarcTo(oval, startAngle, sweepAngle, forceMoveTo), which draws an inscribed arc with lengthsweepAnglearound the perimeter ofoval, beginning atstartAngle.forceMoveToindicates whether the pen should be lifted from the surface at its current position before beginning the arc.
Looking at the example shape at the top of this post, we can easily picture each of the arcs and lines we would need to draw the shape:
For each corner, we need to define the “oval” as an SkRect with a width and height of 2 × that corner’s radius, and offset it to sit flush with the bounding box at that corner. Then we call arcTo on that oval with the correct starting angle, and a sweep angle of 90°. Then we call lineTo with the coordinates of the starting point for the next arc.
But before we bring this knowledge into a UMG widget and go about trying to parameterize it with UPropertys, let’s spin up a quick Skia fiddle
and hard-code our values to make sure we know what we’re doing:
That looks good to me! Next, let’s try substituting those hard-coded magic numbers with variables.
Still looks good , so we haven’t broken anything yet. It’s still pretty noisy to read, so maybe we could try something slightly more declarative, with a simple loop?
Also works . It’s debatable whether that’s easier to read than the previous example, but I think I slightly prefer it, so we’ll stick with it.
Variable borders
Drawing the variable-width borders for our rounded rectangle will be a little bit trickier. At a high level, what we want to do is this:
- Create an
outerpath, which is the one we’ve been working with so far, covering the outer bounds of the shape. - Create an
innerpath, which is the shape of the negative space in the center. Looking at the second example shape at the top of this post,innerwould represent the shape of the purple section. - Draw the
outerpath with the main fill color. - Subtract
innerfromouter, and draw the result of that with the border color.
Why paint the fill color first, and why use the outer shape for that instead of just using the fill color to draw the inner path? Because if the border color is semi-transparent, we want the fill color to show through behind it, as demonstrated here:
Mind you, there’s nothing forcing us to implement the CSS spec, so we could do it differently if we wanted to. But given that the border is conceptually aligned to the interior of the rectangle (i.e., it doesn’t add additional width/height to the shape, it consumes part of the existing width/height), this setup makes sense to me.
The tricky part is figuring out how to draw this inner path. Here’s the diagram, but it’s a little less obvious how to derive it from our properties:
The inner bounding box is pretty straightforward:
where is the border-width of the specified side.
The size of an inner corner oval is defined like this:
where is the radius of the corner in question, and / are the border-widths of the corresponding horizontal / vertical side.
But SkRect actually has a method to make a new rect by insetting an existing one, which would make our math much simpler:
/** Returns SkRect, inset by (dx, dy). */
;It doesn’t validate the result, so we would end up with a negative width or height for the top-right and bottom-left corners in our example, since the corresponding border widths are larger than the corner radii. But we could easily make a helper function to constrain the minimum dimensions:
Let’s put it all together and see how it goes. To start, we’ll just draw the inner path over the outer path with a different color — we’re just validating that the inner path has the correct shape for now.
That looks like the result we were aiming for
, so now we can refactor to the method I mentioned earlier, where we first paint the outer path with the fill color, and then draw the border over top of that. But to do that, we need to figure out how to subtract the inner path from the outer path.
Boolean path operations
Traditionally, whether any given path contour is positive or negative is determined by its “winding.” This is similar to how 3D graphics APIs infer the normal direction of a triangle: if the points of a closed path contour are drawn in clockwise order, we have a positive shape (i.e., one whose interior will be filled). If they’re drawn counter-clockwise, then we have a negative shape (i.e., one that cuts a “hole” out of a positive shape).
But we’ve already drawn our inner path clockwise, and it would be kind of a pain to refactor our code to draw it counter-clockwise instead. Fortunately, Skia paths have a “fill type” property, which can be configured with the SkPathFillType enum to change the standard behavior. One of the options is SkPathFillType::kInverseWinding, which is exactly what we want. But we don’t actually have to configure it manually in our case — SkPath has a helper method, reverseAddPath, that lets us append a new path to an existing path as if the new one were inverse-wound.
Here’s the updated code:
// ...
And here’s the result
! Feel free to play around with the opacity of the border color (the first two digits in the SkColor hex) to see the alpha-blending behavior — here it is
with the border opacity at 50%.
A much simpler method
At this point it’s only right to admit that I lied to you pretty egregiously at the top of this post. Or to be more precise, I failed to investigate Skia’s API thoroughly enough when I originally implemented this feature in my own project, and only discovered my error during the course of writing this post about it.
Instead of first rewriting my implementation, and then writing this post to reflect that (as if I had actually done it properly the first time around), I thought it would be illuminating to walk through the entire journey I took to get here — first, because it offers a nice exploration of Skia’s path-drawing APIs, but second (and more importantly) because it makes for an important lesson: don’t make premature assumptions, and always RTFM (read the freaking manual).
Remember when I said this?
One of Skia’s principal raisons d’être is to serve as the rendering engine behind Google Chrome, but its API is quite a bit lower-level than the CSS specification, so you won’t find a simple
SkCanvasmethod that directly does what we’re aiming for.
That is not quite correct. Sort of the opposite of correct, actually. SkRRect does exactly what we’re aiming for, with a single SkCanvas draw call and a much simpler API.
From Skia’s API reference :
SkRRect describes a rounded rectangle with a bounds and a pair of radii for each corner.
Emphasis mine (which is the part I missed the first time around). Hilariously, if you expand the full description, it later explicitly spells out the fact that it can be used to “[implement] CSS properties that describe rounded corners.” Sigh.
SkRRect implementation
The most flexible SkRRect API requires us to specify both the x and y radius for each corner, while the less flexible ones allow only a global x and y radius which would be applied to all corners uniformly. We’ll need to use the former, which means we need to convert our array of scalar radii to an array of vector radii. Our UMG widget’s API will allow either one or four scalars (uniform or per-corner), so instead of just writing each value twice, we’ll use a simple <algorithm> import to transform our existing array, and refactor to the Unreal equivalent once we get to the UMG implementation.
Here’s the result
, which is as expected. To draw the border, we will still need to create a path, but instead of tracing it manually, we can build it from SkRRects. First, we need to build the inner SkRRect with the correct bounds and radii. We can use, with one minor adjustment, the formulas we came up with earlier (and write a similar helper function).
// ...
That gets us the correct result for opaque borders
, so we just need to build a path from the two SkRRects to get the correct alpha blending for semi-transparent borders:
// ...
And that’s it ! We have a comprehensive Skia implementation of a rounded rectangle with independent corner radii and border widths. Now we can bring it into Unreal Engine.
Implementing the UMG widget
We’ll start with the basic boilerplate:
UCLASS()
For our UPropertys, I’m sorely tempted to try out the new UMG Viewmodel plugin
, but that would add an additional plugin dependency to our own plugin, and one that’s in Beta at that. I also haven’t had the chance to give it a test drive yet, so I’m not sure if it would be a good fit for this project, and I’m definitely not equipped to give it a detailed write-up in this (already long) post. So we’ll save that investigation for another time. For now, we’ll just manually implement some getters and setters so we can request a redraw when the properties change.
We’ll create UStructs for the corner radii and border widths. We could have just used FVector4f for these, but I like the ergonomics of having meaningfully-named fields here. Using custom structs also gives us a convenient hook to customize the UMG details panel for these properties, which we’ll want to do eventually to make it easier to set them to uniform values.
// ...
USTRUCT(BlueprintType)
USTRUCT(BlueprintType)
// ...Add equality-checking utilities to both for good measure:
// ...
USTRUCT(BlueprintType)
// ...Then fill out the class properties:
// ...
UCLASS()
// ...
// ...Whew. Gotta love that Unreal boilerplate. I really wish we could write UHT extensions from user code, because that is begging to be its own UProperty specifier, but hopefully UMG Viewmodel and its FieldNotify specifier will ease some of the burden down the road.
On to the meat of the implementation. We’ll start by converting a few variables to Skia-friendly types.
// ...
Note that SkScalar is just a typedef for float. We could use SkScalar instead of float here, under the assumption that maybe one day they’ll be doubles, or maybe there’s some preprocessor definition that can change it to double and maybe one day we’ll want to use that. But UHT is finicky about parsing UProperty declarations typed with non-Unreal typedefs, so we have to use the concrete type in a bunch of places anyway. But we will use SkColor (a typedef for uint32) since it helpfully clarifies what the type represents.
Next up is transforming the corner radii scalars to vectors. We could make FCanvasRectCorners iterable by defining float* begin() and float* end() methods, and then use Unreal’s std::transform equivalent like this:
// ...
But that’s a pretty wildly overengineered solution, with a non-zero runtime cost (exacerbated by needing to capture skScale into our lambda) without any tangible benefit, so we’ll just transform them inline instead.
// ...
Importantly though: however it gets done, we need to multiply all user-provided properties by the scale parameter before using them to draw anything. This is mainly because of Slate/UMG’s DPI-scaling features. We want designers to be able to specify those properties in “Slate units,” which are basically abstracted, hardware-agnostic pixel-equivalents (much like the CSS px unit).
On a standard 1080p display, scale will usually be 1. But on, say, a 4k display, it will be closer to 2. That means that a widget with a “desired size” of 300x100 will be drawing closer to 600x200 actual hardware pixels. The size parameter already has that scaling baked in, because it matches the render target’s size, which is mapped 1:1 to hardware pixels. But features like border widths, corner radii, or anything else that we expect the user to specify in Slate units, will need to be scaled to match.
Beyond that, the MVP is pretty much a 1:1 translation of our Skia fiddle. Here’s the bird’s-eye view, excluding the boilerplate we wrote earlier:
// ...
And here’s the result, rendering in UMG:
Any of those properties in the Details panel on the right can be edited, and the preview will update in real-time. Try it out!
What’s next?
There are plenty of optimizations we could make at this point. For example, as we observed earlier, if we’re not rendering semi-transparent borders, we can just render two SkRRects on top of each other instead of creating a compound path for the border shape. If the border is zeroed out or fully transparent, we can skip one of the SkRRects altogether. If the corner radii are zeroed out, we can just use a plain SkRect (or for that matter, just clear the canvas with the fill color). I’ll leave all of that as an exercise for the reader (which is to say, this post has gone on long enough and it’s time for me to move on).
In the next entry in this series, we’ll explore using Skia to render SVG images in UMG.