Allegro.cc - Online Community

Allegro.cc Forums » Off-Topic Ordeals » a grievance with the API...

This thread is locked; no one can reply to it. rss feed Print
a grievance with the API...
Mark Oates
Member #1,146
March 2001
avatar

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
Second in Command
February 2005
avatar

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.

“Throughout history, poverty is the normal condition of man. Advances which permit this norm to be exceeded — here and there, now and then — are the work of an extremely small minority, frequently despised, often condemned, and almost always opposed by all right-thinking people. Whenever this tiny minority is kept from creating, or (as sometimes happens) is driven out of a society, the people then slip back into abject poverty. This is known as "bad luck.”

― Robert A. Heinlein

André Silva
Member #11,991
May 2010
avatar

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
Member #794
November 2000
avatar

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
Member #7,827
October 2006
avatar

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

"For in much wisdom is much grief: and he that increases knowledge increases sorrow."-Ecclesiastes 1:18
[SiegeLord's Abode][Codes]:[DAllegro5]:[RustAllegro]

Chris Katko
Member #1,881
January 2002
avatar

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

Most of Google seems to agree.

-----sig:
“Programs should be written for people to read, and only incidentally for machines to execute.” - Structure and Interpretation of Computer Programs

Mark Oates
Member #1,146
March 2001
avatar

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
Second in Command
February 2005
avatar

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.

“Throughout history, poverty is the normal condition of man. Advances which permit this norm to be exceeded — here and there, now and then — are the work of an extremely small minority, frequently despised, often condemned, and almost always opposed by all right-thinking people. Whenever this tiny minority is kept from creating, or (as sometimes happens) is driven out of a society, the people then slip back into abject poverty. This is known as "bad luck.”

― Robert A. Heinlein

Johan Halmén
Member #1,550
September 2001

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.

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Years of thorough research have revealed that the red "x" that closes a window, really isn't red, but white on red background.

Years of thorough research have revealed that what people find beautiful about the Mandelbrot set is not the set itself, but all the rest.

Gideon Weems
Member #3,925
October 2003

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.

Go to: