a grievance with the API...
Mark Oates

So, this has kinda been bothering me for awhile.

current API:

al_draw_circle(); // draws an outlined circle
al_draw_filled_circle(); // draws a filled circle

every time I want to use it, this is what I expect:

al_draw_circle(); // draws a filled circle
al_draw_outlined_circle(); // draws the stroke of the circle

This has happened a lot. Normally for something like this, I would defer to the methodology of the API and give it time to sink in, but I trip up every time when using the primitive functions in this regard and my mind can't seem to acclimate to it. So, I've decided to mention it, and am offering the possibility that the API could be incorrect.

Giving it some thought, here's some reasoning I've come up with:

  1. The filled primitive is more "primitive" than the outlined variation, which involves more intricate math to breakdown the stroke into smaller primitives. With that in mind, the outlined variation is a more complex function, or, the exception.

  2. In Photoshop, drawing a shape draws the fill. If you want to do effects with it (like add a stroke, make it gradient, textured, etc.) then you go to the layer style and add a stroke.

  3. Typically, OpenGL primitives are drawn as a fill. You can do GL_LINES, GL_LINE_STRIP, GL_LINE_LOOP, but those are more functional, they aren't reliable from a design standpoint - considering that stroke width is not an option, and modern displays have such widely varying pixel densities. Fill is more to the purpose I guess?

  4. The most correct way to do it might be to only offer two functions, al_draw_filled_circle() and al_draw_outlined_circle() (and no al_draw_circle()), since in most other drawing APIs, fill and stroke are attributes to how a shape is drawn (HTML5 Canvas, PostScript, Illustrator, Gimp, etc).

TLDR;

From a computer graphics standpoint I can't conceive of the stroke of a circle as the "circle", and a filled circle as the "other" one. :-/

Thoughts? :)

Arthur Kalliokoski

If someone gave you a pencil and paper and asked you to draw a circle, what would you do?

The filled primitive is more "primitive" than the outlined variation, which involves more intricate math to breakdown the stroke into smaller primitives

How so? The filled version not only has to do the chords (I assume that's what you mean by "stroke") but also has to fill it.

André Silva

I also trip up most of the time, but when it's time to fill in the parameters for the function, I always realize if there's a parameter missing or in excess.
I'm not sure I'm totally in favour of new names, whatever those might be. At least, you can always have #define al_draw_outlined_circle(...) al_draw_circle(...) and never use al_draw_circle.

Evert

I just double-checked the following two definitions on Wolfram Mathworld:
"A circle is the set of points in a plane that are equidistant from a given point O".
"An n-dimensional disk (sometimes spelled "disc") of radius r is the collection of points of distance <= r (closed disk) or < r (open disk) from a fixed point in Euclidean n-space."

This also echoes my own expectations of what al_draw_circle() should do. I would not opt for al_draw_disk() though since disk is a bit more obscure, and consistency between circle/rectangle/polygon is IMO more important.

Quote:

Thoughts? :)

I think you have an incorrect notion of what a circle is and there is nothing to fix. ;)

SiegeLord

al_draw_disk was considered, to mirror the mathematical definition, but was rejected because there isn't a good analogue for rectangles, ellipses etc.

Chris Katko

From a Mechanical Engineer's standpoint: I've never mistaken "circle" to mean a filled circle.

Most of Google seems to agree.

Mark Oates
Evert said:

I just double-checked the following two definitions on Wolfram Mathworld:
"A circle is the set of points in a plane that are equidistant from a given point O".

SiegeLord said:

al_draw_disk was considered, to mirror the mathematical definition, but was rejected because there isn't a good analogue for rectangles, ellipses etc.

From a Mechanical Engineer's standpoint: I've never mistaken "circle" to mean a filled circle.

Ok. The impression I get is that, from a mathematics standpoint there is some logic to it. I'm coming from a graphic design standpoint, so I'm inclined to distinguish stroke (outline) and fill in that way. However, according to the wolfram definition, a circle would still have an outline width of NULL. One would create a circle object, and then use the definition to draw a stroke or fill. But yea, I'm not advocating that, that's going down the rabbit hole. usability--.

If someone gave you a pencil and paper and asked you to draw a circle, what would you do?

Except I'm not drawing with a pencil, I'm drawing with a computer. (Or, I'm not drawing using the pencil tool, I'm drawing using the circle tool.) I see what you're saying though, point taken.

Quote:

How so? The filled version not only has to do the chords (I assume that's what you mean by "stroke") but also has to fill it.

I don't know what chords are (that sounds fancy). :P Is that like a pie slice? I'm referring to the stroke as the operation that is the outline. Illustrator, Photoshop, and Canvas for example.

It looks like SDL delineates drawshape() and drawfilledshape() like our current API... so that's a good sign... *cough*

Arthur Kalliokoski

http://en.wikipedia.org/wiki/Chord_%28geometry%29

Since it draws connected line segments to approximate a circle. Or it could draw lines tangent to the circle, almost the same.

Johan Halmén

A chord is a line that connects one point on the circle with another. Chords here mean either horizontal or vertical pixel rows that fill the circle area.

Drawing a circle simply means drawing the outline. In A4 the reault was a width of 1 pixel. When drawing with say Incscape, you might be able to define a zero width, which still is 1 pixel on the screen no matter how much you scale. In that sense, zero width is not the same as invisible.

Gideon Weems
Quote:

I think you have an incorrect notion of what a circle is and there is nothing to fix. ;)

Ah, but the question is about a representation of this abstract idea we call a circle and not the circle itself. Perhaps a more proper API would forgo al_draw_circle() entirely and instead provide al_draw_circle_perimeter() and al_draw_circle_area().

... That might be going a little overboard, though.

Thread #613310. Printed from Allegro.cc