Codecov Report

Merging #2063 (e2f0fea) into master (45986c6) will decrease coverage by 0.04%.
The diff coverage is n/a.

❗ Current head e2f0fea differs from pull request most recent head 5da8c5e. Consider uploading reports for the commit 5da8c5e to get more accurate results

@@            Coverage Diff             @@
##           master    #2063      +/-   ##
==========================================
- Coverage   13.94%   13.90%   -0.05%     
==========================================
  Files         189      189              
  Lines       15821    15817       -4     
  Branches     4179     4169      -10     
==========================================
- Hits         2207     2199       -8     
- Misses      13460    13464       +4     
  Partials      154      154              

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 45986c6...5da8c5e. Read the comment docs.

I personally don’t see much value in adding this, there are already great libraries built on top of SFML which offer this (or it’s relatively simple to roll your own) and although it seems simple on the surface, a line shape like this can actually get quite complex use cases.

although it seems simple on the surface, a line shape like this can actually get quite complex use cases.

Isn't that rather a reason for adding a line shape to SFML?

In the past, it was often recommended that sf::RectangleShape can be used for lines. And while technically true (at least for non-rounded ends), it adds a lot of overhead for someone who simply wants to draw a few debug graphics.

It's well possible that there may be further feature requests though, e.g. end style (rectangular, pointy, rounded, arrow), line style (constant, dotted, dashed), etc.

Regarding implementation, I like the current one, as it is fairly simple. One possible change would be to cache the offset vector perpendicular to the direction (see comment).

Isn't that rather a reason for adding a line shape to SFML?

Sorry I don't quite understand how? It would mean we have to implement or at least consider the more complex use-cases as well as dealing with further feature requests (as you say). It would also like make the implementation/API much less simple than it currently is

someone who simply wants to draw a few debug graphics.

Yeah this use-case has been mentioned a few times in this discussion but I struggle to get on board with it. Debug lines are easily done with existing primitives, with this new class only offering the benefit of thickness, which is not something I've ever desired with my debug tools.

Based on my experience using lines with thickness (for end products, not debugging) there are a couple of things I've needed in my own implementations that I would question for this one:

• How should textures be applied? With the current implementation I believe the texture would not rotate with the line, which is often what I would want/expect
• Will we offer any control over the orientation of the ends of the line? A common use-case given for this is line graphs, but with any thickness larger than a couple of pixels the joins between the lines won't look good. In my own implementations i've made the ends of the line vertical for cases like this, but this is quite case-specific

with this new class only offering the benefit of thickness

It's more than just setThickness. We can't dismiss how this class provides much improved semantics as well. It lets you reason about lines as lines as opposed to stretched and rotated rectangles. Being able to set the end point is a much more friendly API.

How should textures be applied? With the current implementation I believe the texture would not rotate with the line, which is often what I would want/expect

Currently line segments can use any two start and end points while the rotation remains zero. An alternative solution is to dynamically update the rotation to match the direction to the end point. Then we just store a length and thickness internally. This approach might be friendlier to applying textures.

Will we offer any control over the orientation of the ends of the line? A common use-case given for this is line graphs, but with any thickness larger than a couple of pixels the joins between the lines won't look good.

This is why we also ought to consider sf::CurveShape for drawing curves comprised of many line segments.

While I can understand most arguments against a sf::LineShape, I still think that it should be implemented.

The fact that just about every SFML extension library has added such a line shape in one way or another and we have a multiple implementations in the community wiki is a strong indication that this is something SFML should provide out of the box.

• Thor's Line Function
• Thor's Arrow Class
• SelbaWard's Line
• SelbaWard's Spline
• Wiki: Drawable Line Shape
• Wiki: Line with thickness
• Wiki: Line Segment with thickness
• Wiki: Line Shape

Additionally, it's an often requested feature, which is also a good measure to show what people want - interestingly enough, each of these requests, is immediately followed by a link to one of the implementations above.

• sf::Line
• sf::LineShape
• A simple sf::Line
• sf::LineShape and sf::EllipseShape
• Drawing bold lines
• Many more on IRC/Discord

With that, I believe it's quite undeniable that there is demand for such a functionality.

Now for some of the arguments...

It's well possible that there may be further feature requests though, e.g. end style (rectangular, pointy, rounded, arrow), line style (constant, dotted, dashed), etc.
~ Bromeon

It would mean we have to implement or at least consider the more complex use-cases as well as dealing with further feature requests (as you say). It would also like make the implementation/API much less simple than it currently is
~ Jonny

There are many potential more complex use cases for other shapes as well (dotted outlines, rounded rectangles, different colored for each side outline, etc.). Just because there's a potential for additional feature requests, doesn't mean that we have to follow through with these requests, nor that they will actually happen. It's good to discuss some of those points for the initial implementation and define what problem the sf::LineShape solves, but it's not a good argument against the feature overall.

On the other hand, why are things like an arrow class or a rounded line or a spline not something SFML should have from the get go?

What worries me about lines with thickness, is that they are just rotated rectangles. Thus, the overlap between this class and sf::RectangleShape is close to 100%. The only thing that differs is how to define the shape, but the shape itself is still a rectangle. So maybe a better option would be to provide alternative ways to build a rectangle?
~ Laurent

I believe this highly depends on the API we build for sf::LineShape. Yes, it might be very similar to a rectangle shape underneath, but if the access APIs work with start/end points, then the usage becomes quite different and does justify a dedicated class for me.

A dedicated LineShape can add thickness to the sides only.

That's not obvious. It would feel strange / inconsistent to have outline only on two sides. That's in my opinion a good example of what kind of problems we'd get with a line-with-thickness class
~ Laurent

This is certainly something we need to make a decision on. Should a line only have an outline on the "long" side or all around it? Or should it be configurable?

Are there any additional arguments?

My personal design goals for a sf::LineShape class are:

• Needs to fully implement the sf::Shape interface
• "Simple" API to handling the two end points / constructing a line
• Needs to clearly define the scope of the class:
  • No arrows
  • No rounded ends
  • No joints
  • Just a line between two points with an optional thickness

@eXpl0it3r Thanks a lot for the detailed research, this greatly summarizes the discussion!

This is certainly something we need to make a decision on. Should a line only have an outline on the "long" side or all around it? Or should it be configurable?

I think the most straightforward approach would be if line didn't have an outline at all -- or, the line itself is the outline.

This is how user software like Microsoft Word does it. There, shapes have the following properties:

• Fill
  • Color
  • Gradient
  • Texture
• Outline
  • Color
  • Weight (= thickness)
  • Dashes (dotted, dashed, straight)
  • Arrows

For line-like shapes (lines, arrows, curves), the Fill property is simply disabled, because it's meaningless. So everything is determined through the outline.

Back to SFML, this shows a LSP issue with sf::Shape. We have both fill and outline properties, although not all shapes support them. I see multiple options:

1. Add a new intermediate interface sf::AreaShape or sf::FilledShape which provides methods regarding texture, texture rect, fill color. These methods would be moved down from sf::Shape. All existing shapes would inherit the new interface, while sf::Line would inherit the (now reduced) sf::Shape.
2. Define a meaning for texturing/filling lines. Is that a feature that's really useful? Can it be provided in an intuitive way?
3. Make some methods do nothing for sf::Line. This is quite ugly and like Java's UnsupportedOperationException shows bad OOP design.

Fixed minor merge conflict.

Rebasing to keep up with master. No changes.

Fixed trivial merge conflict.

Rebased and reformatted because of #2159

Rebased and fixed compiler error.

Rebased because it's been a while and because I needed to convert some size_ts to std::size_ts.

Consider calling this sf::LineSegmentShape so that we can use sf::LineShape for a more full-fledged line class.

@eXpl0it3r @Bromeon: would you be in favour of this PR if we rename it as sf::LineSegmentShape and make it clear that this is just a basic primitive over a line with some thickness, and then we can build on top of it (e.g. sf::LineShape could be a bunch of sf::LineSegmentShape, or we could have a sf::FancyLineSegmentShape where we can add rounded edges/arrows and stuff like that).

What do you think?

Rebased to catch up with master. No changes required.

Rebased to get new CI jobs.

Fixed small merge conflict with master.

I'm not interested in maintaining or discussing this anymore so I'm closing it (again). If motivation returns we can resurrect this but it's not worth keeping this open in the meantime.