An Implementation for Generic Blend Modes

[Nexus]

For reference, here are the two files in the master branch of thomas9459's fork:
BlendMode.hpp
BlendMode.cpp

I don't want such hacks neither. But one of my goal for SFML 2 was to provide backward compatibility. Broken cases are rare, but they can exist, and if a game compiles / works with SFML 2.1 but not SFML 2.2 then it's clearly a problem.

I see. An option would also be to provide the int conversions, but not document them in the public API, or clearly mark them as deprecated, to discourage users from regarding the conversion as a feature. In the worst case we postpone blend modes to SFML 3, but introducing it now is also an opportunity to get feedback about them, so that the design can potentially be improved in SFML 3.

I've searched quickly on GitHub to get a rough overview how open source projects use SFML's blend mode. As far as I see it, those that exploit the integral convertibility are either SFML forks or bindings. What concerns me more is the fact that very few people use the code

sf::BlendMode::BlendNone

even though it's not correct C++03. It would also be possible to be backward compatible with that, though...

I'm fine with factors. What I'm more worried about are the equations: are min/max and inverse subtract really useful? I would like to see concrete use cases for them.

I agree. We can easily add needed functionality later, should it prove useful, but not remove it...


By the way, do you happen to know whether SFML's competitors provide a more advanced blend mode API? And do you consider the order of the 6 constructor parameters meaningful?

[Laurent]

By the way, do you happen to know whether SFML's competitors provide a more advanced blend mode API?

I don't know. From a quick look, it seems that SDL 2 still only supports the 4 simple modes that SFML currently supports.

And do you consider the order of the 6 constructor parameters meaningful?

Yes. But there could be overloads / default values. There are at least two common simplifications that can be made: equation is almost always "Add", and src/dst factors are often the same for color and alpha.

[Nexus]

Yes. But there could be overloads / default values. There are at least two common simplifications that can be made: equation is almost always "Add", and src/dst factors are often the same for color and alpha.

Maybe a

BlendMode(BlendFactor::Type source, BlendFactor::Type destination);

that could be extended by a BlendEquation::Type default parameter in the future?

I don't know. From a quick look, it seems that SDL 2 still only supports the 4 simple modes that SFML currently supports.

SDL supports the 4 basic modes. CrystalSpace offers a finite set of blend modes, but many more than 4. Ogre seems to have both a simple and an expert API.

I'm more and more unsure whether it's wise to expose the whole OpenGL stuff... Another point is that even if we had the full customization, there would still be a need for a lot more predefined modes, or else everybody has to search the internet to find out how to compose common blend modes with OpenGL.

One option is also that BlendMode initially provides limited customizability: only some important constructors, no public member variables. But this would only make sense if we don't aim at providing the full set of operations, and it would still introduce complexity (maybe even more because one has to use unnamed parameters instead of member assignments).

Something we should also keep in mind is pre-multiplied alpha blending, that could come with a modification in sf::Image or sf::Texture.


This is becoming quite a bit complex for a single commit. It might be worthwhile to create a separate Git branch for this feature, so people could test it, give feedback about API simplicity and compatibility with existing code... And then we could still make a final decision (even if it would only be "we won't merge it to master, but if you really need this feature, use that branch"). What do you think?

[Laurent]

Maybe a

BlendMode(BlendFactor::Type source, BlendFactor::Type destination);

that could be extended by a BlendEquation::Type default parameter in the future?

Yep.

It might be worthwhile to create a separate Git branch for this feature, so people could test it, give feedback about API simplicity and compatibility with existing code... And then we could still make a final decision (even if it would only be "we won't merge it to master, but if you really need this feature, use that branch"). What do you think?

This sounds wiser, yes

[Lolilolight]

Yes or you can do the blending in a fragment shader.

SFML provide render textures so you can do multipass rendering with shaders.

It's very powerfull and it's what I currently do in my project.


You'll also be able to call the draw function only one time for each objects using the same texture.

[Lolilolight]

Yes right but there are limitations with the hardware. ^^

And I really don't know in which cases the other blend modes can be usefull.

If someone have an example I'll be very interested to see it.

But normally there's an extension of GLSL which allow you to read the buffers values of your graphics card from a fragment shader but I really don't now how it works.

You haven't to do crappy work around and you can doing general blendmodes.

[Nexus]

Lolilolight, stop hijacking the thread without understanding what this feature request even is about. There are clearly meaningful scenarios for blend modes, if you don't believe that, search the forum, there have been several threads about it.

It would be really nice if further posts in this thread could focus on the initial request. This concerns not only Lolilolight, but also people who want to respond to him. Thanks.

[Lolilolight]

Ok I'll be looking for these threads, but if I've understand what you mean it's adding the posibility to do something like this with SFML ?

https://docs.unity3d.com/Documentation/Components/SL-Blend.html

[thomas9459]

Warning: Public history has been rewritten!
If you have cloned from my fork of SFML in order to try the new blending feature, you must run the following commands.

Code: [Select]

git reset --hard HEAD~4
git pull

Additionally, the commits are now located on the branch new_blending_api rather than on master. Sorry, about the history rewrite, but things will end up much cleaner this way.


So I have once again updated the code to reflect the discussion here. One important thing to note is that all of the blending changes have been moved to their own branch named new_blending_api. This means that any links to the code on Github should most likely be updated.

Inside the namespace sf, you can omit the sf:: prefixes.

If still applicable, where are these prefixes? If you were referring to the constant conversion functions (which have been moved to RenderTarget.cpp), should the anonymous namespace be put in the sf namespace?

2. We must have a fallback for systems without glBlendFuncSeparate.

Would it suffice if it were supported for the existing blend modes? Then we could adapt the SFML rendering such that if the GLEW extension is not supported, it will recognize those cases and use the old glBlendFunc().

But in general, it's not possible to map the new API with 6 parameters to the simplified one.

Is something more than this required for an adequate fallback?

By the way, are all the new constants really necessary? I didn't look deeply at them, so make sure they are all really relevant, and not just added "because now we can".

I'll investigate that. The question is whether you only want to provide the minimum number of enumerators that is necessary to implement the current blend modes, or at least a few more common ones? Where should we draw the border? It will be more or less arbitrary...

I can imagine a few scenarios where the reverse subtract could be useful, such as, for example, decreasing the amount of alpha in an render texture. If anything, min and max could be dropped as they serve little purpose from a graphical perspective and they also operate differently than the other equations (that is, they ignore the blending factors).

Maybe a

BlendMode(BlendFactor::Type source, BlendFactor::Type destination);

that could be extended by a BlendEquation::Type default parameter in the future?

Yep.

Shall I go ahead and implement this?

BlendMode(BlendFactor::Type source, BlendFactor::Type destination, BlendEquation::Type equation = BlendEquation::Add);

Finally, what is the preferred way of treating long lines in SFML? I didn't find any really long lines in other source files, so I just assumed a reasonable style with the long lines here, here, and here.

[Laurent]

I can imagine a few scenarios where the reverse subtract could be useful, such as, for example, decreasing the amount of alpha in an render texture. If anything, min and max could be dropped as they serve little purpose from a graphical perspective and they also operate differently than the other equations (that is, they ignore the blending factors).

Could we go even further and drop the equation completely? It can still be added later if needed, and this would lower the new complexity. If I remember correctly, most of the requests were about new factors.

One remark about naming: wouldn't BlendMode::Factor and BlendMode::Equation be better, rather than BlendFactor::Type and BlendEquation::Type? In other words, why are these enums declared ouside the BlendMode class?

[Nexus]

In other words, why are these enums declared ouside the BlendMode class?

I think the reason is expressivity when accessing the enumerators:

BlendFactor::SrcAlpha

or

BlendMode::SrcAlpha

(in the latter, factor and equation have the same scope)

I'm a bit in a hurry now, I'll respond to your post later, Thomas.

[Laurent]

This is not a problem in C++11 where you can write BlendMode::Factor::SrcAlpha if you want more expressivity.

[Nexus]

Sorry, about the history rewrite, but things will end up much cleaner this way.

Rebasing is no problem as long as it's not in SFML master

I think you could even make a further rebase and squash all the commits of the new branch to a single one (or do you want to preserve each refactoring iteration, Laurent?)

If still applicable, where are these prefixes?

Sorry, I thought they were inside sf namespace. In the anonymous namespace, it's fine like this. (Personally, I often put anonymous namespaces in the library namespace for this reason, but SFML doesn't do that).

Is something more than this required for an adequate fallback?

Actually that should solve it nicely, at least if the new arguments agree with the previous implementation. But I'm a bit worried when the user uses custom blend modes and one component is silently thrown away. Maybe there should be an error message in debug mode or an assert in this case?

Finally, what is the preferred way of treating long lines in SFML?

I don't know it either
Maybe just check that the line doesn't exceed the usual line length (e.g. of Doxygen comments) too much.

Could we go even further and drop the equation completely? It can still be added later if needed, and this would lower the new complexity. If I remember correctly, most of the requests were about new factors.

I think subtractive blend mode was also requested. But I agree that we should not add all 5 equations.

This is not a problem in C++11 where you can write BlendMode::Factor::SrcAlpha if you want more expressivity.

True. For me it's fine either way. I guess the reason to put them into BlendMode is that you want the things to be grouped rather than scattered across the sf namespace?

[Laurent]

or do you want to preserve each refactoring iteration, Laurent?

I don't want to preserve that, no

Maybe there should be an error message in debug mode or an assert in this case?

That sounds like a good idea, but SFML shouldn't spam the error output (such functions are often called every frame). Ideally there should be only one warning the first time the function is called.

I guess the reason to put them into BlendMode is that you want the things to be grouped rather than scattered across the sf namespace?

Yes.

[Nexus]

Ok. Then I suggest Thomas cleans up the commits into one and applies the last suggestions, then I can create the new branch in SFML. We can still change everything then, but I think it's good if we have something practical at hand, otherwise the discussion will be endless

A new branch will also help getting the attention of other users.

Reminder of the last changes:

• Move enums inside BlendMode class and rename them to Factor and Equation
• Leave only Add and Subtract equations

The error detection and other stuff can be implemented once the branch is up.