Issue #678 new

Different functions for filled and outlined shapes

hahawoo avatarhahawoo created an issue

There are two issues with how things are at the moment:

  • The draw mode for shapes has to be specified all the time.
  • The draw mode is mixed in with the conceptually distinct geometry information, except with lines.

My proposal to fix these is to have different functions for filled and outlined shapes:

love.graphics.arc( x, y, radius, angle1, angle2, segments )
love.graphics.arcLine( x, y, radius, angle1, angle2, segments )
love.graphics.circle( x, y, radius, segments )
love.graphics.circleLine( x, y, radius, segments )
love.graphics.rectangle( x, y, width, height )
love.graphics.rectangleLine( x, y, width, height )
love.graphics.polygon( vertices )
love.graphics.polygonLine( vertices )
love.graphics.line( points )

Additional benefits are:

  • There are less characters to type.
  • It avoids the use of an enum. Using an enum, you have to be aware of what other values the enum can have. Here, the information is in the function name.
  • Consistency of some sort. To the best of my knowledge, no other function which takes an argument to change the "style" of the function has such an argument without a default. (See love.audio.newSource, Source:seek, love.filesystem.newFileData, etc.)

The only drawback I can see is that there are simply more functions. But, I think they result in a net decrease of complexity.

Comments (6)

  1. criptych

    I've used APIs with a similar convention and rather liked it. What about using "drawX" and "fillX" for lines and fills, respectively? This would echo the generic "draw" function and match the use of verbs as function names throughout most of LOVE.

    If I'm not mistaken, dropping the enum may also help performance, but only slightly.

  2. hahawoo

    That's cool that it's used successfully elsewhere. And it's an interesting observation about verbs as function names, I hadn't thought of that.

    An issue with drawX and fillX though might be that fillX functions would be the only functions which drew something to the screen and didn't start with draw (Edit: Actually that's not right, print and printf don't start with draw either). I guess it could be drawFilledX, but that's getting a bit too long. Alternatively it could be drawX and drawXLine. But I'm still a fan of X and XLine, just because I like the primitives being concise.

  3. hahawoo

    The two types of points could have their own functions too, which removes a function, an enum, and an element of global state.

  4. kikito

    If we ever went this route, I would vote to name the functions 'strokeXXX' and 'fillXXX' respectively. Stroke and fill are common verbs on drawing APIs.

  5. hahawoo

    The problem I see with strokeShape and fillShape is that the verbs don't really say what they do, for example strokeCircle doesn't "stroke a circle". Well... maybe it does? I dunno, just seems slightly strange to me at the moment.

    drawStrokedCircle or drawOutlinedCircle or drawCircleLine seem to say what they do more accurately, I think, maybe, to me.

    The word "stroke" and verbs (stroke/fillShape) are inconsistent with love.graphics.line, which uses the word "line" and is a noun. I guess strokeLine would be possible?

    I'm still a fan of the nouns shape and shapeLine though. It's a good point that most LÖVE functions are verbs, but to note, not all are:

    love.graphics.origin
    love.math.noise
    love.math.random
    love.math.randomNormal
    love.filesystem.lines
    

    They could be made into verbs though:

    love.graphics.goToOrigin -- Something better than this. :D
    love.math.generateNoise
    love.math.generateRandom
    love.math.generateRandomNormal
    love.filesystem.iterateLines
    

    Still, I'm not sure whether this consistency would be worth it.

  6. hahawoo

    Or...

    love.graphics.draw
    love.graphics.drawText
    love.graphics.drawTextWrapped
    love.graphics.drawArc
    love.graphics.drawArcLine
    love.graphics.drawCircle
    love.graphics.drawCircleLine
    love.graphics.drawRectangle
    love.graphics.drawRectangleLine
    love.graphics.drawPolygon
    love.graphics.drawPolygonLine
    love.graphics.drawLine
    

    To quote from Bret Victor's Learnable Programming:

    This example assumed a hypothetical graphics library which was designed for autocomplete -- all of the drawing functions begin with "draw", so the completion list would appear as the designer intended.*

    * Strangely, I don't actually know of any APIs that are intentionally designed with autocomplete in mind. I do know many APIs, such as Processing, that are designed for brevity, which is irrelevant in an environment with good autocomplete.

    If this is a good idea, then maybe something like this is too:

    love.graphics.coordPop
    love.graphics.coordPush
    love.graphics.coordRotate
    love.graphics.coordScale
    love.graphics.coordShear
    love.graphics.coordTranslate
    
  7. Log in to comment
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.