What's going on with drawing sharp, odd-pixel-width lines in Cairo?

-------------------------------------------------------------------

First read the Cairo FAQ entry:

https://www.cairographics.org/FAQ/#sharp_lines

Here is a slightly different explanation, based on our

understanding as of July 2023:

There are no pixels on integer positions; if you draw a

single pixel line on any such integer position, it will

(half) shade the row/col of pixels on either side of that

position. The pixels are actually at N.5.

If the line width is a multiple of two, then the row/col of

pixels on either side of the integer coordinate will both be

full shaded. So if you draw a 2-pixel wide line at 1.0, the

pixel rows/cols at 0.5 and 1.5 will both be fully shaded and

you get what you asked for: 2 rows/cols of pixels that are

visible as intended.

However, if you want to shade just a single (sharp) row/col

of pixels, you must do so at N.5, which is where the pixels

actually "are". The first such row/col is at 0.5. the

second row/col is at 1.5 etc. etc.

So ... to draw a single pixel line on the first row/col, the

relevant x/y coordinate is 0.5.

Consequently, if you are drawing lines that can ever be an

odd number of pixels in width, you MUST shift the

coordinates by + (line_width * 0.5) in order to shade only

the pixels at that position (and adjacent ones, if the line

is 3, 5, 7 etc. pixels wide).

Below is a tiny test program that will allow you to

experiment with 0.5 offset to see its effect (it generates

/tmp/out.png which you should look at with a tool that can

zoom in to view pixels easily)

// gcc -o cairo-test cairo-test.c `pkg-config --cflags --libs cairo`

#include <stdio.h>

#include <cairo/cairo.h>

int main (int argc, char **argv) {

char* fn = "/tmp/out.png";

cairo_surface_t* cs = cairo_image_surface_create (CAIRO_FORMAT_ARGB32, 100, 100);

cairo_t* cr = cairo_create (cs);

cairo_set_source_rgba (cr, 1, 1, 1, 1);

cairo_set_line_width (cr, 1);

/* Experiment with using 0., 0.5, -0.5 and more for the value

* of y, and check which rows of pixels are shaded as a result.

*/

double y = 0.5;

cairo_move_to (cr, 0, y);

cairo_line_to (cr, 100.5, y);

cairo_stroke (cr);

cairo_surface_write_to_png (cs, fn);

cairo_destroy (cr);

cairo_surface_destroy (cs);

return 0;

}