3DEE

[binary1248]

3DEE - 3D Extrapolated Extension for SFML

Yes... some people might have expected this from me, and this was in the planning for quite a while and since Tank preferred that I work on this rather than SFGUI how could I say no?

General Idea
I've been using SFML for quite a while now, and it sort of fulfilled my needs in the beginning. But as I wrote more and more things, I always had to resort to using raw OpenGL to get 3D rendering done because well... SFML doesn't support 3D rendering through its drawable API. It got quite annoying that all my applications had basically the same OpenGL boilerplate code that SFML happily takes care of... for 2D. I thought: there must be a common subset of functionality that all 3D applications rely on that everybody has to code, but nobody truly likes to code. That is basically what this extension is for. It takes all the concepts that make rapid prototyping and coding graphical applications with SFML so simple and fast, and applies them to the 3D domain as well. Moreover, it was designed to be as general as possible to fit as many use cases as possible while still adhering to the SFML architecture... somewhat.

As for the name... no I initially had no idea that it could be pronounced like that. I tend to name my projects after what they are since I am such a creative person. It is just a working title after all. I couldn't name it SFML, I already had a directory named SFML .

The idea is simple. Take all SFML classes that are bound to the 2D plane and extrapolate them into the next dimension (I know, it sounds awesome if you say it like that). 2D objects are furthermore still compatible with 3D rendering. They will simply have their z coordinate set to 0 appropriately.

Features
3D Primitives
Analog to RectangleShape and CircleShape, there are the 3D counterparts named Cuboid and SphericalPolyhedron respectively. They are based on Polyhedron which is the analog to Shape. For constructing one's own polyhedra, there is the ConvexPolyhedron class as an analog to ConvexShape (don't ask me why it is named ConvexPolyhedron, I don't understand either ).

3D Models
You might be asking: OK great, we have primitives, but what about models? After all they represent the bulk of geometry in a typical 3D application. That is true, and that is why there is a very light interface class called Model which provides a few methods that might be helpful when building your own application specific 3D model classes. Since model loading, storage and representation is a science in itself, one isn't limited to using Model at all costs. Even a simple VertexArray can be used to represent model data if you want more control. Model was one of the classes for which I genuinely had no idea how to design. The requirements differ so much per application so instead of trying to implement a solution for every possible scenario, I figured just make it as light as possible and purely optional to use. I didn't implement model data loading because that would have introduced another dependency (which I don't like), and it ends up in a lot of code that the application would not make use of in the end. Model loading is done by the application specific class. Feedback would be appreciated on what other useful features could be added to Model.

Billboards
Although so simple, billboards are so common in 3D applications, as a replacement for complex geometry at lower levels of detail, as the representation of particles and many other things. Billboards are implemented as Sprites which are automatically rotated to always face the camera they were set to track. Nothing more, nothing less.

Cameras
What 3D application would be complete without Cameras? They are indeed the analog to a View and derive from View just to keep things simple (I could have derived the other way around or made a common parent interface but I wanted to minimize the needed changes). They can be used anywhere a normal View would be able to be used. As inspiration for its API I took the newly added/changed Listener API with its position and directions so combining a Listener and Camera becomes quite trivial and the only natural thing to do .

Lights
This is the first controversial feature. There is a Light class, and it bases its functionality on the fixed-function lighting of OpenGL with all its limitations. This could also be done using shaders, which I also recommend doing if you can afford it. However, sticking with SFML philosophy I felt that I had to provide an alternative for those unlucky people without programmable graphics hardware. Light can also be used for rapid prototyping and replaced later on with something more... flexible, but short of copying and pasting shader code along with its handling code, this is the fastest you will get lighting up and running which is absolutely necessary in many 3D applications.

Shadows
This is the second controversial (non-)feature. Yes... it is a non-feature because I didn't implement shadowing. There simply isn't any fixed-function support for shadows and writing a custom shadow implementation

• Is guaranteed to have worse performance than the equivalent shader/modern variant
• Is not guaranteed to be optimal given the scene for which it is to be used, meaning that I would have to write multiple implementations for each scenario which would all be inferior to writing an application specific implementation
• Is still a science in itself. There is no consensus on "how to do it right", just general techniques that still need to be adapted to each application

For those reasons I thought it be better to let the application developer implement their own shadows which suits their needs the best.

Minor Features
4x4 Transforms
This was a given, considering we are working in 3D now. This could be considered a major feature, however I don't directly use Transforms all that much and I don't think many others do as well .

Stencil attachment for RenderTextures
I figured when rendering in 3D, it is going to be necessary to have an optional stencil attachment for RenderTextures, after all, many advanced techniques rely on use of stencil data (this includes shadowing techniques). This also sparks the question of whether the format of RenderTextures should be even more flexible to e.g. prevent the creation of a color buffer in cases where one isn't required.

2D Drawable Winding
I altered all 2D drawable classes to specify vertex data with counter-clockwise winding. This was a requirement because I enabled backface culling in RenderTarget by default, get used to it .

OK, enough with the features, where's the...
Yes... the repository can be found at GitHub: https://github.com/binary1248/SFML

The branch consists of additions/changes to the SFML master branch in order to make integration as seamless as possible. Because I consider this to be a strict superset of SFML's features, this extension should be able to be dropped in place of the standard SFML implementation and it should work out of the box. If it doesn't, either it is a bug (not unlikely at all ) or have something to do with the caveats that I am going to list.

The change set should stay more or less compatible with future changes to mainline SFML if not too much is changed. As such it should be easily rebased to the current SFML master when anything happens there.

Caveats
Winding
If you make use of your own geometry specification using VertexArray or a custom ConvexShape/Shape, make sure the face winding matches with what is expected (counter-clockwise). Culling is enabled by default in this implementation and any clockwise faces will not be rendered. Make it into a good habit and one day you will thank me because of the performance boost you might observe .

Vertex Normals
By default, vertex normals should be set correctly for all 2D drawables, facing in the positive z direction. When specifying your own vertex data, do not forget to specify them if the default doesn't cut it and you want to light your geometry.

View Matrix
Contrary to popular belief, you in fact don't move the view around by manipulating the projection matrix. The projection matrix is there for one purpose, and as its name implies that is the projection from eye/view space coordinates into normalized device coordinates. The reason why the architects of OpenGL chose the term modelview matrix is because the modelview matrix combines the Model and the View matrix into a single matrix. With the help of pushing and popping the stack it isn't hard to understand the theoretical concept. This is how a vertex is transformed:

vertex_out = projection * view * model * vertex_in

The model matrix transforms the vertex into world space, the view matrix into eye space and the projection matrix into normalized device space which is fed into the rasterizer. The reason why combining the view matrix into the projection matrix is possible is simple to understand from the equation. However, this brings problems with it, especially when lighting and normals come into play. Vertex normals are transformed just like normal vertex data, however they are not multiplied with the projection matrix. This means if you have your view matrix combined with the projection matrix as opposed to the modelview matrix the normals will not be transformed properly, and lighting will produce unexpected results.

The proper way to move the view around is to instead "move the world around the view". This is done using the inverse of what would normally be considered the rotation and translation of the camera.

This is less of a problem when rendering in 2D without lighting because... well... there are no normals to worry about. There are other strange side-effects that are the result of this mistake. For more information refer to this. If you have some obscure code that relies on the vanilla "non-standard" matrix implementation then maybe it's time to consider fixing it up.

Frequently Asked Questions
Q: Where are the pre-compiled libraries for XYZ compiler?
A: You know me... No pre-compiled libraries here.

Q: I can't see anything I draw!
A: Read documentation? Read caveats? Did everything right? Report bug.

Q: Why are there no copyright notices in the newly added files?
A: I can't just copy them from the standard SFML files can I? Until I figure out what best to do, the source is available under the same license as SFML, zlib.

Q: Do you plan on ....
A: Yes I have plans for a lot of things, and they will be implemented when I have a general idea of how to implement them. Don't be afraid of asking for features, if they are simple enough and are general enough to be useful to people besides you as well, I might implement them. However I will not take the route of implementing every possible variation of a certain feature to cater to every possible use case like certain individuals try and fail to do.

Q: I know this isn't a question but I found a bug and I am sure it isn't intended behaviour described in a footnote of the documentation, and it wasn't in your caveat list.
A: Ask here or GitHub tracker.

Q: Where is the documentation?
A: doxygen inside the doc directory, or just generate the doc target in CMake. Same as SFML.

Q: What? No screenshots? What kind of presentation is this?!
A: The only thing to see would be the example I added, and that is not the focus as it is there purely for code demonstration purposes. And besides... building the example and running it yourself isn't really hard is it?

Q: This is too complicated for me. Is there a simpler way?
A: What? This is supposed to make your life simpler, and your development... faster. If you prefer writing 500 lines of OpenGL code to get a rotating lit cube up and running, be my guest.

Q: I don't understand OpenGL! That's the reason I use SFML. Why does this look a lot like OpenGL?
A: Like everything in the universe, there is a reason why OpenGL looks like what it is. Indeed you will find that many 3D APIs that don't get too high level have similar interfaces. Nothing else makes much sense. This is no exception. It helps to understand OpenGL concepts but most of the time it should not be needed when using this (my opinion, very subjective). In the case where a bit more knowledge is required, I have tried to write documentation explaining everything that is required.

Q: ... this engine ...
A: This is not an engine. SFML is not an engine. If you want an engine, you will have to look elsewhere.

Q: I want XYZ to look like ABC and when I click UVW it should become IJK. Please help.
A: Look for code slaves elsewhere.

Q: Will parts of this become part of SFML?
A: That is not for me to decide. If Laurent wants to grab bits and pieces, he is very welcome to. I am fine if all of this gets merged and I end up relinquishing my rights to the code. Anything that increases the number of 3D projects in this subforum... I'm getting quite bored... Teapot Defence anyone?

Q: Man that interface is completely moronic. How did you even come up with such a monstrosity?!
A: Constructive criticism welcome. I know this is a sensitive (and quite complicated) topic. And I guess nobody (not even Laurent) tried anything like this before from what I can tell. One learns from their mistakes, and mistakes have to be made to learn.

Q: Are those the only questions in the FAQ?
A: Nope, more will be added if needed.

Q: Why does this thread look like the SFNUL one?
A: Because I am a truly creative individual.

[ChronicRat]

Cool, i'll take a look when my current game will be done.

[therocode]

Oh, wow, this sounds quite awesome! Good job.

I have always found the lack of 3D and the complications that arise when using SFML with own rendering code what makes SFML to many a "kindergarten" library where it is awesome to learn and get familiar with things, but is left behind for alternatives that are easier to integrate and gets less in your way when you want to make more advanced things. Perhaps this extension could hold people a bit longer.

Would definitely try it out, but right now I have no fitting project. Will keep it in mind for future reference.

[eXpl0it3r]

Oh look it's finally here!

I like it, can we merge it into SFML, Laurent?

[Nexus]

Really nice! There are meanwhile quite a few 3D extensions, but a lot of them are either "engines" with rather specific use cases, abandoned or a huge mess (from "certain individuals" ). It looks like yours is the first serious attempt to stay with the SFML philosophy and extend it with as few changes as possible. Especially the "drop-in" semantics sound very promising, you should definitely keep that.

By the way, the project description is quite funny to read

[lolz123]

Looks really nice! A clean interface, as always 

That said, I do see a few problems with this. I am a "Use OpenGL directly" type of guy, mostly because I try to stay on top of the latest and greatest OpenGL features, so it is quite possible that these criticisms do not apply since it is not what the library is trying to achieve. So, please take this with a grain of salt.

The idea of providing an interface as opposed to an engine is cool, but it is really hard to do for something with a scope like OpenGL has. OpenGL's API is probably as simple as it can get FOR C (DirectX has objects, making it a much nicer to use library  )

I do not see how one can maintain the design philosophy of SFML for 3D. SFML's graphics API is great for 2D, but the same design doesn't really translate into 3D IMO. Its going to be really hard to do something like deferred shading in your current setup, since it modifies the entire pipeline to be "Not SFML-style". In deferred shading, all rendered things must have a uniform interface for materials, for instance. Also, you cannot simply add features to a deferred shading pipeline without changing the entire pipleline.

Also, I am sure you are aware of this, but pretty much everything you wrote in OpenGL is highly deprecated.

These criticisms may be wrong, they may be stupid, I need more coffee 

[binary1248]

I am also more of an OpenGL guy, and I know how deferred shading basically requires you to take control of the whole pipeline yourself. But if you consider that rewriting any of the SFML examples in modern OpenGL would require writing the same functionality directly in OpenGL code, then there really is no point in trying to abstract further. With every layer of abstraction, you lose expressiveness, unless it is a super-thin layer which would be nothing but redundant.

The idea is to provide simple access to the most used functionality hidden behind abstraction, until the developer decides that they need more control. SFML does this, and without 3DEE, the realm of 3D rendering was also "beyond" SFML and something you had to do by hand. 3DEE just pushes this barrier a bit further, but for the purposes of complex things like deferred shading the barrier would have to be pushed so far, that it wouldn't make much sense to abstract any more. As such, you are probably right. You are unfortunately not (yet?) the target audience of 3DEE .

Bear in mind that I had to stick to deprecated features to "fit into SFML" better. If SFML had used modern OpenGL I would have too, I didn't want to change the requirements or even add new dependencies. I was merely exposing more of the lower level features using the same resources. I could have rewritten SFML to make more use of modern OpenGL but I figured that shouldn't be undertaken at the same time as this, as it is a completely separate concern. After all I am not really the one maintaining mainline SFML .

I do not see how one can maintain the design philosophy of SFML for 3D. SFML's graphics API is great for 2D, but the same design doesn't really translate into 3D IMO.

The reason I see for this, is that OpenGL was designed with 3D rendering in mind from the start, and as such 2D rendering was "squeezed into" the 3D rendering API. What this meant is that things that should be conceptually simple are artificially bloated due to the generalization. SFML is hiding the unneeded parts of this generalization again and maps directly from 2D concepts to the subset of OpenGL that is concerned with 2D rendering.

Its going to be really hard to do something like deferred shading in your current setup, since it modifies the entire pipeline to be "Not SFML-style". In deferred shading, all rendered things must have a uniform interface for materials, for instance. Also, you cannot simply add features to a deferred shading pipeline without changing the entire pipleline.

I can already picture how the pipeline itself would be abstracted in order to provide an easier to use interface. What OpenGL still does not do well, if you ask me, is provide a uniform intuitive API to its pipeline. I think every OpenGL programmer knows what I am talking about when I say that knowledge of the OpenGL programming API alone is not enough to get things done. You actually have to understand how the pipeline works "behind the scenes" in order to make use of it in a meaningful way. And that leads to having to understand the fundamentals of 3D computer graphics itself which is where most people stop and start running away . Maybe it was for this reason that Laurent didn't want to enter the realm of this "black magic"?

Maybe one day, SFML will support 2D and 3D rendering without use of any deprecated features and easy access to a modular pipeline API. I still have no idea what that will look like, but one can keep hoping .

[The Terminator]

I've been waiting for something like this for a long time. Definitely will be using this in my later games, it looks amazing!

[Lolilolight]

This is exacly what I'm trying to do for my next games.

[binary1248]

Update
VertexBuffer and VertexContainer
I figured this was a good time to implement an abstraction of an OpenGL VBO that could be used as a drop-in replacement for a VertexArray. All it does is delay data upload until the buffer is bound and the data has changed because more often than not, when you bind a buffer you want to do something with the data on the GPU. This has the nice side effect that for geometry that hardly changes, there is no cheaper way to draw. I can already imagine how much performance improvement people using huge VertexArrays will benefit from when using a VertexBuffer instead (this is one of those few times when my work actually benefits the tilemap community ) if they are truly bottlenecked by bus transfers.

For the really special use cases, one can even access the memory block directly and use a VertexBuffer to transfer arbitrary (non-Vertex) data to GPU memory. Buffer objects are probably the most common way of transferring any kind of data between host and GPU memory.

In the case where you want compatibility with older (ancient) hardware, you can use VertexContainer as a drop-in replacement instead. It will automatically select the optimal storage implementation based on the system it is running on. I also went ahead and replaced all instances of VertexArray or normal Vertex arrays in the drawable classes with VertexContainer, so they will hopefully profit from the reduced data transfers as well.

I would be interested to hear about any performance improvements (or possibly even declines) when dropping in 3DEE in place of vanilla SFML. My aim is to make something that everybody can benefit from.

1DEE and 3DEE Textures (I couldn't resist )
Maybe not many beginners might know, but counter to intuition, OpenGL supports 1D and 3D textures in addition to 2D textures which SFML already exposes through its API. They won't be too useful when sticking to fixed-function 2D rendering, however they might be useful to those that make heavy use of raw OpenGL and shaders.

To demonstrate how a 1D texture might be used (this is still a very synthetic example), I altered the Storm + Blink Effect in the Shader example a bit to add a bit more... "chaotic energy" to it .

Shader Language Version Query
It is important to know what is supported when writing your own shaders, and until now, the user would have to manually query OpenGL themselves to find out what is supported. I added a small method to the Shader class that returns that information in a simple string that can be processed to find out what is supported. Getting the information should be a one-liner in the future.


The changes have all been pushed to GitHub.

These are a few of the features on the roadmap to de-deprecation of the SFML drawable implementation I had in mind. In the future I hope to see SFML run using modern OpenGL behind the scenes on hardware that supports it. It should still be completely hidden from beginners though, they have enough to worry about . OpenGL users (like myself) should also benefit from having less to worry about because the really low-level details and C API restrictions would be sufficiently hidden behind higher level C++ constructs.

[BaneTrapper]

Hello, it seams quite a good addition to sfml this would bring so i want to check it out:

I got few issues,
I cannot build the documentation with cmake. Id like to see documentation.

I Downloaded from provided link

OK, enough with the features, where's the...
Yes... the repository can be found at GitHub: https://github.com/binary1248/SFML

I see there is a documentation

Q: Where is the documentation?
A: doxygen inside the doc directory, or just generate the doc target in CMake. Same as SFML.

But when i build it with cmake i get following error

Code: [Select]

The C compiler identification is MSVC 17.0.50727.1
The CXX compiler identification is MSVC 17.0.50727.1
Check for working C compiler using: Visual Studio 11
Check for working C compiler using: Visual Studio 11 -- works
Detecting C compiler ABI info
Detecting C compiler ABI info - done
Check for working CXX compiler using: Visual Studio 11
Check for working CXX compiler using: Visual Studio 11 -- works
Detecting CXX compiler ABI info
Detecting CXX compiler ABI info - done
CMake Error at C:/Program Files/CMake 2.8/share/cmake-2.8/Modules/FindPackageHandleStandardArgs.cmake:108 (message):
  Could NOT find Doxygen (missing: DOXYGEN_EXECUTABLE)
Call Stack (most recent call first):
  C:/Program Files/CMake 2.8/share/cmake-2.8/Modules/FindPackageHandleStandardArgs.cmake:315 (_FPHSA_FAILURE_MESSAGE)
  C:/Program Files/CMake 2.8/share/cmake-2.8/Modules/FindDoxygen.cmake:85 (FIND_PACKAGE_HANDLE_STANDARD_ARGS)
  CMakeLists.txt:16 (find_package)


CMake Warning (dev) in CMakeLists.txt:
  No cmake_minimum_required command is present.  A line of code such as

    cmake_minimum_required(VERSION 2.8)

  should be added at the top of the file.  The version specified may be lower
  if you wish to support older CMake versions for this project.  For more
  information run "cmake --help-policy CMP0000".
This warning is for project developers.  Use -Wno-dev to suppress it.

Configuring incomplete, errors occurred!

EDIT:: I fixed the unresolved link compiler error.
Downloaded fresh copy repeated process to build, no compiler error now.

[Laurent]

Could NOT find Doxygen

I think it's clear: you have to install doxygen to build the documentation.

[BaneTrapper]

Could NOT find Doxygen

I think it's clear: you have to install doxygen to build the documentation.

Ooh i had no idea what it is, thank you.

[Laurent]

Yeah, since he says "same as SFML", I guess he means "read the SFML tutorial for more detailed information"

SFML_BUILD_DOC

This boolean option controls whether you generate the SFML documentation or not. Note that the doxygen tool must be installed and accessible, otherwise enabling this option will produce an error.

[BaneTrapper]

Yeah, since he says "same as SFML", I guess he means "read the SFML tutorial for more detailed information"

SFML_BUILD_DOC

This boolean option controls whether you generate the SFML documentation or not. Note that the doxygen tool must be installed and accessible, otherwise enabling this option will produce an error.

It was a lot to take in at moment read, thank you on help!