Understanding GradientFill

Home Back To Tips Page How it works inside!

The GradientFill function is one of the more obscure GDI functions, yet one which has much to recommend it for aesthetic purposes. But it is hard to use, and its documentation is profoundly obscure. The inadequate documentation discourages the use of this rather cool API.

I wrote the GradientFill Explorer because I got tired of fiddling with parameters and recompiling, or fiddling in the debugger, trying to get the effect I wanted.

The GradientFill Explorer allows you to play with the parameters to GradientFill and it generates code you can paste directly into your application. You will typically need to edit the x,y parameters to conform to your application (usually replacing the static integers with dynamically-computed values suitable for your application), and you may wish to change the rather simple variable names to names that are more suited for your environment.

The Gradient Filler interface

The specification of GradientFill is

BOOL GradientFill(HDC hdc, PTRIVERTEX pVertex, ULONG dwNumVertex, PVOID pMesh, ULONG dwNumMesh, ULONG dwMode)
BOOL CDC::GradientFill(TRIVERTEX * pVertex, ULONG nVertices, void * pMesh, ULONG nMeshelements, DWORD dwMode

(It is worth observing here that the people who wrote these specs appear to be functionally illiterate in several ways: the parameters are gratuitously changed in type and the use of Hungarian Notation is inconsistent within each call and between calls. This is an example of how HN demonstrates that it should not be used, because people who use it are most often like the authors of these two specifications: demonstrably incompetent to use it! I spot at least seven inconsistencies in two lines of code!)

The last parameter: The gradient fill mode

The last shall be first

The top left box of the interface lets you select the dwMode parameter, one of

• GRADIENT_FILL_RECT_H indicates a horizontal fill, with the colors moving left to right as they shade from one to another
• GRADIENT_FILL_RECT_V indicates vertical fill, with the colors moving top to bottom as they shade from one to another
• GRADIENT_FILL_TRIANGLE indicates a triangle fill.

Parameter: The TRIVERTEX array

The second argument to ::GradientFill or the first argument to CDC::GradientFill is a pointer to an array of TRIVERTEX values. Each color is represented by a pair of TRIVERTEX values, where the first element of the pair has an x,y coordinate that represents the top left corner of the region, and the second element of the pair has an x,y coordinate that represents the bottom right corner of the region. The first TRIVERTEX element represents the first color to be used, and the second TRIVERTEX element represents the second color to be used. The colors will flow smoothly from the left edge of the region to the right edge (for GRADIENT_FILL_RECT_H) or from the top edge of the region to the bottom edge (for GRADIENT_FILL_RECT_V). A simple gradient fill of black to white is illustrated here.

The list box in the TRIVERTEX section holds the elements. The edit controls and spin controls can be used to set the values. The x and y spin controls will not exceed whatever the limits of the sample control are, which will vary depending on your screen resolution. The expectation is that you will replace these values by something appropriate for your app.

You can select a color by using the R, G, and B edit controls, or the button ... to bring up a standard color selection dialog.

Note that the colors appear to use a "decimal" notation. They don't actually have a decimal representation, but the TRIVERTEXT fields are

typedef struct _TRIVERTEX {
LONG        x;
Long        y;
COLOR16     Red;
COLOR16     Green;
COLOR16     Blue;
COLOR16     Alpha;
} TRIVERTEX, *PTRIVERTEX;

According to the GradientFill documentation, the Alpha channel A is not actually used.

Having selected the parameters x, y, R, G, B and (the usused) A, the Add button will add this selection to the ListBox. The selection is always added to the end. If you do not want it there, the Up and Down buttons will move the selected item up or down, and the Remove button will remove it.

If you select an item, and click the Edit check box, the parameters for the item are set to the controls. Changing the value in the controls will immediately change the value in the ListBox, and if you are seeing the gradient displayed, you will see it change immediately in response to these edits. As shown in the screen shot below, the editing of the color from white to magenta is displayed, both in terms of changing the contents of the ListBox and in changing the actual image displayed

The point finder

Parameter: Number of vertices

The next parameter to GradientFill is the count of the number of TRIVERTEX elements, and this is computed automatically by the GradientFill Explorer.

Parameter: Mesh elements

The "mesh elements" explain to the API how to interpret the values.

For a GRADIENT_FILL_RECT_*, each mesh element has the indices of two elements of the TRIVERTEX array. One element represents the top left corner of the starting color (in this case, element 0) and one element represents the bottom right corner of the ending color (in this case, element 1). So a GRADIENT_RECT value represents a pair of TRIVERTEX elements.

To add a new value, select the UpperLeft and LowerRight values, which represent the indexes into the TRIVERTEX array, and click the Add button. The element will be added to the end of the ListBox. To change its position, select it and use the Up and Down buttons to shift its position.

To remove an element, select the element and click the Remove button.

To change the contents of an element, select the element, and click the Edit check box. The current values of the element will be copied to the controls, and changes in the controls will immediately change the value of the selected element. If a sample is being displayed, the sample will immediately change to correspond to the new settings.

Each element has a check box beside it. To see the effects of removing that element from the list, simply uncheck it. Note that the check boxes reference only the visual display in the GradientFill Explorer. If the data is saved to a .vtx file, or the code sample is used, the elements will be present. If it is desirable to actually remove them, then the Remove button must be used. Note there is no "undo" capability.

The sample dropdown

The code window

The code window shows the sample code you would write to create the gradient you draw. Using the Edit > Copy all code option this code can be placed in the Clipboard, and you can paste it into your program. Alternatively, you can take the binary vertex file, add it to your resource segement, and copy the VertexData source files into your project, and use the binary representation. The techniques and code for this are shown later in this article.

Normally the values in the code window are displayed in decimal. Unfortunately this makes the values hard to read, because the COLOR16 values end up being the familiar values multiplied by 256. The use of the pseudo-decimal notation in the comment shows this; color values range from 0.000 to 0.255.

TRIVERTEX tv[2] = {
{   0,     0,        0,        0,        0,    65280}, // [ 0] RGBA(  0.000,     0.000,     0.000,   255.000)
{ 120,    96,    65280,    65280,    65280,    65280}, // [ 1] RGBA(255.000,   255.000,   255.000,   255.000)
};

GRADIENT_RECT gr[1] = {
{0, 1},
};
BOOL result = dc.GradientFill(tv, 2, gr, 1, GRADIENT_FILL_RECT_H);

By using the Show colors in hex check box, the color values will be displayed in hexadecimal.

TRIVERTEX tv[2] = {
{   0,     0,   0x0000,   0x0000,   0x0000,   0xff00}, // [ 0] RGBA(  0.000,     0.000,     0.000,   255.000)
{ 120,    96,   0xff00,   0xff00,   0xff00,   0xff00}, // [ 1] RGBA(255.000,   255.000,   255.000,   255.000)
};

GRADIENT_RECT gr[1] = {
{0, 1},
};
BOOL result = dc.GradientFill(tv, 2, gr, 1, GRADIENT_FILL_RECT_H);

When things go bad

If you supply invalid parameters to GradientFill, and the operation returns FALSE, instead of seeing a blank image, the entire image background changes color and the error message for GetLastError is displayed:

Note that it is possible to provide a set of parameters to GradientFill that will produce no output, but will also produce no error, because the GradientFill has worked correctly but your parameters do not result in any actual display.

The Menus

Triangular Gradients

Triangular gradients are the Really Fun Part of GradientFill, but they are largely a deep mystery. My hope is that the GradientFill Explorer will help demystify some of the features of triangular gradients.

When you select GRADIENT_FILL_TRIANGLE, a slightly different interface appears. In this interface, the GRADIENT_RECT controls are replaced by the GRADIENT_TRIANGLE controls, as shown here.

Triangular gradients allow you to use two, three-color fills with a triangular fill pattern, and with multiple triangles you can easily get very fancy, such as the four-color example shown later, which is just two three-color triangular fills. The example from the GradientFill documentation is shown here. First, the TRIVERTEX values are set up:

Then the mesh parameters are selected:

This produces the 3-color filled area

A Triangular Gradient Tutorial

Consider the humble center-gradient image:

How do we create this with a single operation?

To give some concrete numbers here, we are going to make a 96 × 96 image. We need to identify the key points in the image, and there turn out to be 9. A key point is represented by its coordinates <x, y, color> so schematically we get the following

Next, I will assign vertex numbers to each of these points. How you assign them is up to you, but they should be a dense set of integers starting at 0. I chose to assign them left-to-right and top-to-bottom, but I could equally have assigned the integers 0..8 randomly to the points. But that would make it harder to understand and explain.

These numbers will tell me where I want to place the point in the TRIVERTEX array I'm about to create.

Next, I identify where the triangles are formed. For example I can see that there is one triangle as shown here:

From this information I can deduce that one of the entries in the GRADIENT_TRIANGLE array should be 0, 1 4, which produces the triangle

Image	GRADIENT_TRIANGLE	Cumulative		Image	GRADIENT_TRIANGLE	Cumulative
	0 1 2 3 4 5 6 7 8 0, 1, 4				0 1 2 3 4 5 6 7 8 4, 7, 8
	0 1 2 3 4 5 6 7 8 1, 2, 4				0 1 2 3 4 5 6 7 8 4, 7, 6
	0 1 2 3 4 5 6 7 8 2, 5, 4				0 1 2 3 4 5 6 7 8 3, 4, 6
	0 1 2 3 4 5 6 7 8 4, 5, 8				0 1 2 3 4 5 6 7 8 0, 4, 3

Which is exactly the parameters from the Gradient Filler Explorer

.vtx files

class VertexData

The VertexData class handles transformations to and from the packed binary representation of GradientFill data. It knows how to format the data for output and it knows how to read and parse the data from a file or resource. It is the primary interface to .vtx files, both as files and as resource data.

Summary of error codes for VertexData

Using .vtx files as resources

1. Create a .vtx file containing your gradient information
2. Select your .rc file, and right-click on it, selecting Add Resource...
3. When the dialog comes up, select the Import... option



4. When the file open dialog comes up, go to the right directory, and select *.vtx



5. After you open the file, you will be presented with an option to identify the type of the resource. Note that since I have been adding resources to this project already, my name (you can choose any name you like), "VERTEX", is already known as a possibility. Either type the name of your resource into the edit control, or click on one of the listed types.



6. The resource will be added as shown. Note that if you double-click on the resource it will show the resource in binary, and it can be edited (not recommended unless you've really studied the file format), but if you want to you can study the bytes and decode them in the file format specified. Note that I took the default symbol assigned, IDB_VERTEX7. You can change the symbol or its value using the Properties editor.



7. To use this, you could write

   VertexData vd;
   BOOL ok = vd.LoadVertexResource(AfxGetInstanceHandle(), MAKEINTRESOURCE(IDB_VERTEX7), _T("VERTEX"));
   PTRIVERTEX tv;
   ULONG vertexCount;
   PVOID mesh;
   ULONG meshCount;
   ULONG mode;
   ok = vd.FromBinary(tv, vertexCount, mesh, meshCount, mode);
   dc.GradientFill(tv, vertexCount, mesh, meshCount, mode);
   vd.Release();

The decode of the .vtx file

Notes on the development of the GradientFill Explorer

I was sitting here in Bristol England in January of 2008. I'm sure Bristol is a lovely city in the summer, but right now it is 40°F, pouring down rain, and with winds gusting to 20mph. Not a day to be outdoors in an electric cart. Yesterday was the same, and the next two days promise to be the same (afternote: they were). So what to do? I started browsing my laptop, and found this project which I started in August of 2005 and apparently forgot about. I'd used it just to create some rectangular fills I needed for one project, and I'd not bothered to add the triangular fill code. There was nothing to do but finish it. I alternated this with reading Simon Singh's book Fermat's Last Theorem, a fascinating history of the conquest of the most famous problem in mathematical history.

As the rain hits the window and the wind whistles around the corner of the hotel, I'm creating the images and tables of this Web page. I do not have FrontPage; I'm using Epsilon and editing raw HTML text (the header says it was created by FrontPage, but that's because I started with one of my existing pages which I downloaded and stripped). I'll have to convert the .bmp files to .gif or .jpg before I put this site up, because my laptop doesn't have any decent image processing software. But everything else is written in raw HTML. Those fancy tables-in-tables were all hand-done. I'm dangerous when I'm bored.

I added the multiple-point highlighting and scrollbar support at some 35,000 feet over the Atlantic Ocean, about an hour from Bristol.

Send mail to newcomer@flounder.com with questions or comments about this web site.
Copyright © 2008, The Joseph M. Newcomer Co./FlounderCraft Ltd., All Rights Reserved
Last modified: May 14, 2011