The new graphics API in SFML 2

[Laurent]

Yeah, but I wanted to get rid of all these SetPointXxx functions. People usually don't know where the point at index N is located, since the geometry was built automatically. Thus it's hard to figure out which color to map to which point to get the desired result; a ColorGradient would be a simple (but limited) way to do that.

And since full flexibility can be achieved with sf::VertexArray anyway, high-level classes don't need to provide all the possible features.

Another solution is to subdivide geometry to allow more complex color gradients. But then Nexus is right, it's hard to get the color at a given position. And people that use a single color wouldn't be able to find it back easily with the getter.

[Laurent]

I think I'll start with the simplest API for sf::Shape: a single fill color/outline color, and for texturing I'll use a texture rect instead of allowing to change the texture coordinates of each point.

[Mikademus]

Well, if you're thinking of specialised classes for rects and other shapes, then adjust the API accordingly.

Rect:
enum Poiint { topLeft, topRight, bottomLeft, bottomRight }
setColour( Point point, Colour colour );
...

And similar enums and methods for the other shapes. For the generic Shape class I don't think you can get away from the setColour( index, colour ), and people that need that class should not really have any problems with understanding that interface.

[Laurent]

And similar enums and methods for the other shapes

And what would these enums be, for other shapes such as circle, star or triangle?

[Mikademus]

And similar enums and methods for the other shapes

And what would these enums be, for other shapes such as circle, star or triangle?

Well, for manual point setting I would imagine sticking with the vanilla setPoint/Colour/etc( index ) of Shape, but you could have methods like Star::setStarType() taking some preset star types (the enums { fivePoint, sevenPoint, etc }) but it is not elegant.

My point is that I don't think you'll be able to create an alternative to the setPointXxx() solution that retains flexibility. The Gradient class will not really be simpler but will be less useful and adjustable, and removing gradients isn't a good idea at all.

[Laurent]

removing gradients isn't a good idea at all

Do you really think people used them a lot?

[Mikademus]

Can only talk for myself, but I use individual colours for points pervasively in my project. In particular in my GUI system. I appreciate the desire to improve a library, and I would rank the benefits and motivations for doing so as follows

1) Increased stability
2) Improved and additional functionality (features and flexibility)
3) Increased usability (accessibility)
4) Increased efficiency
5) Improved elegance (code aesthetics)

In this case removing the facility would reduce functionality and kill existing code, will not really increase usability, and any elegance effect would be subjective.

[Edit]
Unless I misunderstood something and the ability to set individual point (vertex) colours, texture coordinates etc will be retained without losing functionality, but in another form.

[Nexus]

I think having only the possibility to set a texture by setting each point's texture coordinate is too user-unfriendly. So either use only one texture per shape, or write a function that automatically assigns tex coords. Would the setting of point-wise tex coords be much more work when one used sf::VertexArray instead of sf::ConvexShape?

About gradients, I don't know whether people have used them a lot. I once used them for a GUI button... But again, I prefer to keep a single color like in the old API. Point colors can then be added without API breaks, if necessary -- or be treated by sf::VertexArray.

[Laurent]

I use individual colours for points pervasively in my project

Can you show me a typical use case of what you do?

In this case removing the facility would reduce functionality and kill existing code, will not really increase usability, and any elegance effect would be subjective.

Like I said, people don't know where points are located (point 0 could be the one on the left, on the right, in the middle, ...), so how could they assign colors to them? It can only work if they set the points positions themselves.

I think having only the possibility to set a texture by setting each point's texture coordinate is too user-unfriendly.

Yeah. That's why I want to have a "texture rect" property instead. Even for ConvexShape (it's a property of the Shape base class).

Would the setting of point-wise tex coords be much more work when one used sf::VertexArray instead of sf::ConvexShape?

No, I think it doesn't make any difference. The only difference between Shape and VertexArray is that Shape builds a list of triangles out of a convex shape, and computes the outline automatically. But once you have the points positions, the rest is straight-forward if you use a VertexArray, it's just a matter of assigning color and texcoords to the vertices -- it wouldn't be easier if it was implemented in sf::Shape.

But again, I prefer to keep a single color like in the old API. Point colors can then be added without API breaks, if necessary -- or be treated by sf::VertexArray

I don't want to mix several colors in one entity, people can't handle that. A "global" color and a "point" color is already too confusing for people. There are definitely too many threads about that on the forum

[gsaurus]

Keep it simple with the most common functionalities. Everything else fit in "advanced features" with VertexArray (I liked Vertex/Mesh :lol:, cleaner).

Use a single texture, don't forget to repeat it along the shape and provide transformations for the way the texture is applied (I think that scaling the texture is commonly used)

Eventually you can create a static function on ConvexShape to generate a VertexArray for those who want full access to a shape as a VertexArray, but doesn't know exactly how to build it efficiently.

[Nexus]

If you say the point-wise functionality isn't much more complicated to achieve with sf::VertexArray, then I agree to keep sf::Shape very simple, that is, one color and one texture per shape.

About the texture rect... Where is it located in a sf::Shape? Do you compute a bounding rect around all points, i.e. take min/max of X and Y point coordinates?

[Laurent]

Use a single texture, don't forget to repeat it along the shape

That's an interesting point. If I provide a "texture rect" property, people won't be able to repeat a texture on a shape, only take a sub-rectangle of it (unless  a rect bigger than the texture is used, but it's not very clean).

About the texture rect... Where is it located in a sf::Shape? Do you compute a bounding rect around all points, i.e. take min/max of X and Y point coordinates?

Absolutely. I map the texture rect on the bounding rect of the points, and interpolate the texture coordinates accordingly for each point.

[gsaurus]

Well, by default you may repeat the texture rect along the shape (or trunk if the texture rect is bigger than the shape) instead of distorting it to fit the shape bounds.
You may provide a SetTextureTransform(sf::Transform) to allow users to define the texture offset (position relative to the top-left bound of the shape), scale and rotation.
Stretching the texture to fit the shape bounds is a scale operation based on the shape bounds and the texture rect.

Or you can separate the texture mapping in a separated class, like TextureMapping, where you define those things separately (source texture, subrect and transformation). Then Shape have a getter and setter for the TextureMapping (that mapping class could be used for other things too, but I prefer not to think about it now..).

Or if you think it's too confusing, instead of all of that just provide a stretch property that can be activated to make the texture rect fit the shape bounds, and deactivated to have the texture at it's original size repeated or trunked by the bounds.

I think that the important is to think about what users will want to do more often with textures over shapes, and to keep in mind that some won't use textures at all anyway (that's why the TextureMapping possibility)

[Laurent]

Well, I want things to be simple. I don't want to start thinking about complicated texturing stuff.

A stretch property wouldn't be enough, you need to be able to define a sub-rect (position and size) inside the texture.

[gsaurus]

Yes, off course. Where I said texture, I meant sub-rect of the texture.

Possible example with TextureMapping class:

Code: [Select]

sf::Shape myShape;

sf::TextureMapping texMap;
texMap.SetTexture(someTexture);
texMap.SetTextureSubrect(someRect);
texMap.Scale(2.f, 2.f);
// the subrect of the texture will be repeated along the shape, with a scale of 2x
myShape.SetTextureMapping(texMap);
The example is illustrative only, need refinement.

It also makes easier to use the same mapping for several shapes.