A couple suggestions

[GraphicsWhale]

Naming them AudioStream and SampledAudio or something similar

I don't think "Sampled" means what you think it means. All digital audio is made up of samples. The point is that one is streamed, and one is buffered. Hence why I proposed the names BufferedAudio and UnbufferedAudio. Though, I suppose the names BufferedAudio and StreamedAudio sound better now that I think about it.

[shadowmouse]

I agree with the use of StreamedAudio and BufferedAudio. Just a thought but might they be included before SFML 3 with typedefs for Sound and Music so as not to break existing code and a note in the docs to say Sound and Music are depreciated?

[Nexus]

Is it really a concern? The differentiation between "sound effects" and "music" is not only fairly common, but corresponds exactly to the way the classes are used. I don't see a need to change anything here. Apart from the fact that "StreamedAudio/BufferedAudio" are quite clumsy for something so basic.

Anybody learning about sf::Sound and sf::Music must read the tutorial anyway, and their semantics are explained in a few sentences. After that, what they mean is clear for eternity, and people can use simple terms. You don't punish the thousands of people who are okay with "music" and "sound" by making their code less readable.

[shadowmouse]

Anybody learning about sf::Sound and sf::Music must read the tutorial anyway, and their semantics are explained in a few sentences. After that, what they mean is clear for eternity, and people can use simple terms. You don't punish the thousands of people who are okay with "music" and "sound" by making their code less readable.

That's a good point, which by the way is basically what I was thinking about the seperation of window and graphics, why punish the many when you already have sf::RenderTarget sf::RenderTexture which solve the problems of the few?

[GraphicsWhale]

I know the suggestion of replacing Sound/Music has already been.. "dissolved" (not sure what word to use) in this thread, but I still think it's a good idea.

Is it really a concern? The differentiation between "sound effects" and "music" is not only fairly common, but corresponds exactly to the way the classes are used.

Not all sounds may benefit from buffering and not all music will benefit from streaming. Most of the time they are, but most isn't always. It can be quite ugly when you need to use a Sound for something that's not a sound effect, or Music for something that isn't Music.

Effectively, the difference is rather "Should I cache this, or stream it?", not "Is this music, or a sound effect?", so I consider the names semi-misleading.

Is it really a concern? The differentiation between "sound effects" and "music" is not only fairly common, but corresponds exactly to the way the classes are used.

A large sound effect that is only played once benefits from being a Music, but it's not music. A short tune that is constantly re-used benefits from being an Sound, but it's not a sound-effect.

I don't see a need to change anything here. Apart from the fact that "StreamedAudio/BufferedAudio" are quite clumsy for something so basic.

What you see as "clumsy" I see as self-explanatory class names.

Anybody learning about sf::Sound and sf::Music must read the tutorial anyway, and their semantics are explained in 2 sentences.

What about the people who think they're too good for documentation? Even if they don't want to learn, it's not always a bad idea to give some sort of hint of the differences in the name.

After that, what they mean is clear for eternity, and people can use simple terms.

Why not simple and self-explanatory names?

You don't punish the thousands of people who are okay with "music" and "sound" by making their code less readable.

 

[GraphicsWhale]

Anybody learning about sf::Sound and sf::Music must read the tutorial anyway, and their semantics are explained in a few sentences. After that, what they mean is clear for eternity, and people can use simple terms. You don't punish the thousands of people who are okay with "music" and "sound" by making their code less readable.

That's a good point, which by the way is basically what I was thinking about the seperation of window and graphics, why punish the many when you already have sf::RenderTarget sf::RenderTexture which solve the problems of the few?

What's so "punishing" about decoupling a class that serves two purposes into two different classes?

[shadowmouse]

Because you're replacing a simple self explanatory window.draw() with the creation and use of a graphics constant, which is extra work for no gain for most people. Also, on the point about abstraction, as SFML abstracts the OS stuff and the OpenGL stuff, it doesn't matter whether SFML's internal call OS or OpenGL, but instead to focus on, is a window something that can be drawn to, or should it just contain something that can be drawn to?

[Nexus]

GraphicsWhale: you shouldn't underestimate how much simple terms can affect the efforts needed when writing, reading and maintaining code. Basic classes like sf::Sound and sf::Music are always looked up before usage, they don't behave like function names where the name already tells everything about the semantics. So, "self-explanatory" is not as much a gain as it seems to be.

A very good case to demonstrate what I mean is the Android API. They have some terms that are deliberately simple, yet not self-explanatory. "Intent" is such an example -- an intent is an operation, usually a message dispatched to activities. Nobody has an idea what "intent" means before reading the documentation. Yet, it is a well-chosen name, because it creates a concise domain-specific vocabulary. When people talk about intents, every Android developer knows what they mean, much more than "operation/message between activities".

Imagine they had called it "ActivityMessage". It would not only be more wordy to talk about, but it would make all the related features overly clumsy. "IntentFilter" would be "ActivityMessageFilter", already long methods like "startIntentSenderForResult" would become "startActivityMessageSenderForResult". Additionally, it's more difficult to differentiate it from the existing "Activity" and "Message" classes as well as all the methods containing either in their names. When reading code, you need considerably more time to parse and semantically interpret what's written, when terms are longer and more similar to each other.

[GraphicsWhale]

Because you're replacing a simple self explanatory window.draw() with the creation and use of a graphics constant, which is extra work for no gain for most people.

The suggestion was to implement something like this:

sf::Graphics& graphics = window.getGraphics();
graphics.draw(shape);
 

In opposed to just calling the window (which is just plain wrong). There are no constants.

Also, on the point about abstraction, as SFML abstracts the OS stuff and the OpenGL stuff, it doesn't matter whether SFML's internal call OS or OpenGL stuff

You don't need to decouple everything down when it can work without it, but it creates a simpler, more modular design. Especially when you're mixing a class from one module (Window) with a class from another module (RenderTarget) through inheritance to create some mutant multi-purpose object, that is, RenderWindow.

it doesn't matter whether SFML's internal call OS or OpenGL, but instead to focus on, is a window something that can be drawn to, or should it just contain something that can be drawn to?

But why draw to an object that's suppose to be managing the window, in oppose to a class that's managing the graphics? I mean, technically RenderWindow is both a window and a graphics class, but that's not necessarily a good thing.

[shadowmouse]

But why draw to an object that's suppose to be managing the window, in oppose to a class that's managing the graphics? I mean, technically RenderWindow is both a window and a graphics class, but that's not necessarily a good thing.

I can't really explain what I'm saying any more other than just saying, because the window is where the things you draw are shown, therefore, you are drawing to the window/

[GraphicsWhale]

you shouldn't underestimate how much simple terms can affect the efforts needed when writing, reading and maintaining code.

Not all code is going to have the best names. Lack of punctuation, spaces (there's underscores, but nobody uses those for class names), only being able to fit into so many characters, and each name has to be unique.

But it's also important to not make assumptions about the class's usage, only what the class is, and it has to be minimalistic and clear. There are scenarios where it isn't possible, but it has to be really justified to not use a proper name. Using "File" to represent a file in the filesystem is ok, but using "SaveGame" to represent the same thing just because you believe that's what people will use it for is not ok.

Maybe you have a different way of thinking, but I don't agree with it.

Basic classes like sf::Sound and sf::Music are always looked up before usage, they don't behave like function names where the name already tells everything about the semantics.

You are assuming the programmer is going to immediately jump to the documentation when they see the two classes. Likely, they'll just pick one class, figure out how to use it, then stick with it. They both appear to do the same thing, so why would they care otherwise? The classes give so little detail in their names about the difference that even a seasoned programmer might just stick with, say, Sound, because they might be led to believe that this mystical "Music" doesn't actually have to do with playing audio.

So, "self-explanatory" is not as much a gain as it seems to be.

Theses, .. "inconveniences"(?) you speak of in my suggested naming scheme are likely more negligible than the benefits of changing it. This is especially true if in the future, if a large overhaul were to occur anyways.

A very good case to demonstrate what I mean is the Android API. They have some terms that are deliberately simple, yet not self-explanatory. "Intent" is such an example -- an intent is an operation, usually a message dispatched to activities. Nobody has an idea what "intent" means before reading the documentation. Yet, it is a well-chosen name, because it creates a concise domain-specific vocabulary. When people talk about intents, every Android developer knows what they mean, much more than "operation/message between activities".

Imagine they had called it "ActivityMessage". It would not only be more wordy to talk about, but it would make all the related features overly clumsy. "IntentFilter" would be "ActivityMessageFilter", already long methods like "startIntentSenderForResult" would become "startActivityMessageSenderForResult". Additionally, it's more difficult to differentiate it from the existing "Activity" and "Message" classes as well as all the methods containing either in their names. When reading code, you need considerably more time to parse and semantically interpret what's written, when terms are longer and more similar to each other.

And that's why I don't complain that sf::Event isn't named sf::WindowEvent. There is such a thing as a too detailed name, to the point where it become inconvenient. Especially if it's used often. I don't blame whoever wrote that API. But I find it hard to believe that the audio classes have to be named so often that adding a few additional characters would hurt anything.

[Laurent]

I can't really explain what I'm saying any more other than just saying, because the window is where the things you draw are shown, therefore, you are drawing to the window/

Let's explain it differently.

Instead of:

sf::Window
sf::RenderTarget
sf::RenderWindow
sf::Texture
sf::RenderTexture

There would be:

sf::Window
sf::Texture
sf::Graphics

Doesn't it look cleaner, more modular and easier to maintain this way?

[GraphicsWhale]

But why draw to an object that's suppose to be managing the window, in oppose to a class that's managing the graphics? I mean, technically RenderWindow is both a window and a graphics class, but that's not necessarily a good thing.

I can't really explain what I'm saying any more other than just saying, because the window is where the things you draw are shown, therefore, you are drawing to the window/

and I suppose because we're simply, interacting with the user, that we should just throw everything into one class, graphics, input, audio, window management, because that'd make more sense, right?

The window is a wrapper for the native window API. The graphics is a wrapper for the hardware-accelerated graphics API. It should be kept separate. And if anything, decoupling is a good thing because it's simply good OOP practice to do. It's makes code easier to understand and more maintainable.

[shadowmouse]

Doesn't it look cleaner, more modular and easier to maintain this way?

I suppose it does, I'm just not sure if it would make things easier for the user. I was thinking about things where you have to know about the window in order to do the graphics, such as snapping things to one side of the window, where if you only have access to an sf::Graphics, and the Window has been resized, would sf::Graphics know that the Window had been resized, or would the user have to do it themselves? What about if the window loses focus and you want to draw to it when this happens, if something either only has access to the Window, or only has access to the Graphics, you can't do this. I guess I'm just resistant to change unless I'm absolutely sure there won't be any negative effects, but unless I come up with a concrete thing that definitely will causes a problem, I'll leave it.

[Hapax]

It can be quite ugly when you need to use a Sound for something that's not a sound effect

A short tune that is constantly re-used benefits from being an Sound, but it's not a sound-effect.

But it's still sound, right?