7 ms·

Magnum: Lightweight, modular C++11 graphics middleware for games/visualization

87 points by 10000truths 5y ago

ncmncm 5y ago
This looks like good, modern code. +1, would use.
trinovantes 5y ago
I don't know why but I always find C/C++ libraries' documentation to be god awful to read compared to say Python or even JS libraries. An auto generated dump of javadoc comments is a terrible introduction. For example, if I want to open an image [1], it shows what I need to build the plugin but it doesn't have any code samples on how to use it. The constructor requires an manager -- what's that? After importing, how do I get the texture buffer? I'm sure all of this info is somewhere on the docs but I shouldn't have to search for something that should all be on the same page. [1] https://doc.magnum.graphics/magnum/classMagnum_1_1Trade_1_1AnyImageImporter.html https://doc.magnum.graphics/magnum/classMagnum_1_1Trade_1_1A...
- bogwog 5y ago
  I’ve had the complete opposite experience. I’ve yet to use a non-trivial Python library/framework where I didn’t end up having to dig through the source code to figure out how to do something. The dynamic nature of the language makes it hard to auto generate useful docs. With something like Doxygen you can easily know exactly what types a function expects, how to construct those types, etc. ...OTOH, digging through Python source code is more pleasant than C++. So it balances out I guess.
  - trinovantes 5y ago
    Which python libs do you find insufficiently documented? Admittedly I've only used Python for quick scripts or apps (bs4, fitz, flask) rather than my primary language so maybe my view is somewhat biased
  - mshockwave 5y ago
    same, C++ doc can be awful...if it's hand-written, but doxygen is quite good. On the other hand, docs for dynamic languages like javascript and python often hang me there with ambiguous descriptions like "string-like" or "buffer-like" -- yes, I know what those descriptions _mean_ but that doesn't really give me enough confidence to use those APIs.
  - mosra 5y ago
    While I'm here, a shameless self-promo -- Magnum uses a Python doc generator that includes type annotations by default, moving it closer to what you're used to from C++: https://blog.magnum.graphics/announcements/introducing-python-bindings/#everyone-just-uses-sphinx-you https://blog.magnum.graphics/announcements/introducing-pytho... (Sure, it still means the library has to make those annotations in the first place, and have them correct, but the newer and more complex libraries fortunately do, if even just to make IDE autocompletion work.)
- flohofwoe 5y ago
  Magnum's documentation is top tier IMHO. Just don't start with the API reference, but with this page: https://doc.magnum.graphics/magnum/pages.html https://doc.magnum.graphics/magnum/pages.html (which arguably should be the main page)
- mosra 5y ago
  Hah, good point, seems like this class suffers from documentation erosion. It got expanded and expanded and expanded and the essential piece of information got somehow lost down there in the gory details. The actual usage info and code snippet is in the base class documentation [1], it's just that it's no longer linked as prominently as it should be. I'll fix that. It's not this bad everywhere tho, docs of fresher APIs didn't have a chance to erode yet: https://doc.magnum.graphics/magnum/classMagnum_1_1Trade_1_1SceneData.html https://doc.magnum.graphics/magnum/classMagnum_1_1Trade_1_1S... [1] https://doc.magnum.graphics/magnum/classMagnum_1_1Trade_1_1AbstractImporter.html#Trade-AbstractImporter-usage https://doc.magnum.graphics/magnum/classMagnum_1_1Trade_1_1A...
tmaly 5y ago
Where did they come up with this name?
vasankar 5y ago
This is cool!
gary_0 5y ago
Some other interesting libraries I've seen along these lines: - Sokol (sokol_gfx in particular): https://github.com/floooh/sokol https://github.com/floooh/sokol - wgpu (see wgpu-native for the C API): https://github.com/gfx-rs/wgpu https://github.com/gfx-rs/wgpu It kind of seems like graphics abstractions for modern hardware are getting pretty "figured out". There are wrappers that work for most DirectX/Metal/OpenGL applications so they can run just about anywhere, and new 2D/3D applications have a lot of accessible/open-source options to build on top of. Projects like Mesa's Zink will centralize the burden of maintaining legacy APIs away from hardware manufacturers. Valve's Proton is making waves. WebGPU is on the way. The future looks bright.
- pjmlp 5y ago
  That isn't nothing new, 10 years ago, before free beer Unity and Unreal, one would be using something like Ogre 3D.
  - girvo 5y ago
    Or Irrlicht, if you were me as a younger lad and scared off by Ogre at the time. There's always been a vibrant landscape of these sorts of tools, so it's neat to see another one
- Animats 5y ago
  Oh, I wish. There are plenty of game engines and graphics libraries for C++. We have enough of those. This is not yet true for Rust. There seem to be, but if you start to push the performance limits, problems appear. I've been writing a client for Second Life, which, despite all the hype from NFT land, is still the best metaverse around. It's just sluggish, so I'm trying to fix that. The stack I'm using is Rust->Rend3->WGPU->Vulkan->NVidia. Rust is doing fine. No problems at the language level. For this, I need Rust's safe concurrency; there are a lot of threads manipulating shared data. 18 months on, I only needed a debugger once, and the problem wasn't in my code. Rend3/WGPU provides a cross platform layer. Put in meshes, materials, textures, and transforms, and have a loop endlessly calling the render function. Other threads change the scene in parallel with rendering. Rend3 handles memory allocation and scheduling. Vulkan gives you access to the GPU's memory. Managing it is someone else's problem. WGPU provides a common interface to Vulkan, DirectX, and Apple's Metal, which all do pretty much the same thing, but incompatibly. WGPU sits below most of the major game engines on Rust. It all works, but not fast enough. There are locking bottlenecks at the Rend3 and WGPU levels which cause the render thread to be stalled when another thread is loading content. The whole point of Vulkan is that you can do both at once, but the Rend3 and WGPU levels don't quite have that working yet. The right functionality is there, but not the optimization needed for serious work. Nobody seems to be building AAA titles in Rust. I'm pushing the scene complexity to AAA title levels[1], and I seem to be close to the first person to do that. Not where I wanted to be. If you want to work on the lower levels, the WGPU and Rend3 projects, which are open source, need more good people. [1] https://video.hardlimit.com/w/peBesyAgtzfRWS5FnDQQtn https://video.hardlimit.com/w/peBesyAgtzfRWS5FnDQQtn
rychco 5y ago
I’ll definitely give this a try, it arrived exactly when I was exploring other visualization middleware. Also it’s a small thing but it was refreshing to see, in the use-cases section, the developer refer to Godot as a better fit for someone who needs a WYSIWYG editor for games.
Jasper_ 5y ago
Yikes, a GL-inspired graphics library... let's see, how many sins do I count: * Still using global enable/disable flags for all the state bits (e.g. depth test, face culling) rather than packing them into a PSO struct. Why? * Uniforms are bound manually and kept statefully rather than being provided as a UBO interface. * No support for draw call buffering or sorting, and what appears like limited support for multiple framebuffers. * Ooh, "SceneGraph", is that where the pass manager is? Oh, no, it's an object layer that seems to resemble circa OGRE around 2011. Doesn't seem to do any transparency sorting or pass management either. I'd really recommend something like bgfx, sokol, or wgpu instead, which have reduced their dependence on global state, and provide a much better foundation for modern graphics.
- gameswithgabe 5y ago
  Are we looking at the same code? I'm not an OpenGL or Vulkan expert, but: > ...rather than packing them into a PSO struct. Why? * You can clearly read on the front page of the repository that this supports OpenGL 2 through 4.6. I think you're just not looking hard enough. He has Vulkan support in here with a clearly marked file named Pipeline.cpp. The guy knows what a pipeline is... > ...rather than being provided as a UBO interface. * Is this not a UBO interface? > layout(std140) uniform material { vec4 diffuse; vec4 specular; }; It's in his documentation for AbstractShaderProgram. He has explicit binding for stuff pre OpenGL 3.3 or whenever OpenGL added UBOs. > ...appears like limited support for multiple framebuffers. * I don't see why you think there's limited support for multiple framebuffers...? From his docs: > @section GL-Framebuffer-usage-multiple-outputs Multiple fragment shader outputs And then it goes on to explain how to use multiple framebuffer outputs for something like deferred rendering. Moreover, his docs have snippets like this: > @deprecated_gl Prefer to use @ref AbstractFramebuffer::clearDepth() @ref AbstractFramebuffer::clearDepthStencil() instead of @ref setClearDepth() and @ref AbstractFramebuffer::clear() as it leads to less state changes Which clearly shows this guy knows what global state is and why it's bad. I think you're making very broad assumptions based on a very cursory glance at this project. I've only looked at it for about 30 minutes and it looks like a well developed library by somebody who knows what they're doing. I'm sure I could find code that counters the rest of your argument, but I don't feel like looking anymore. None of your criticism seem well intentioned. It might behoove you to give people the benefit of the doubt and realize that you may be able to learn something from them, even if they're so clearly inferior to you. P.S. Don't start off a criticism by saying "how many sins do I count". I don't know your experience, but that's just such an incredibly pretentious statement that's begging to be countered by somebody way more knowledgeable than you about this stuff.

87 points by 10000truths 5y ago

This looks like good, modern code. +1, would use.

I don't know why but I always find C/C++ libraries' documentation to be god awful to read compared to say Python or even JS libraries. An auto generated dump of javadoc comments is a terrible introduction. For example, if I want to open an image [1], it shows what I need to build the plugin but it doesn't have any code samples on how to use it. The constructor requires an manager -- what's that? After importing, how do I get the texture buffer? I'm sure all of this info is somewhere on the docs but I shouldn't have to search for something that should all be on the same page. [1] https://doc.magnum.graphics/magnum/classMagnum_1_1Trade_1_1AnyImageImporter.html https://doc.magnum.graphics/magnum/classMagnum_1_1Trade_1_1A...

bogwog 5y ago
I’ve had the complete opposite experience. I’ve yet to use a non-trivial Python library/framework where I didn’t end up having to dig through the source code to figure out how to do something. The dynamic nature of the language makes it hard to auto generate useful docs. With something like Doxygen you can easily know exactly what types a function expects, how to construct those types, etc. ...OTOH, digging through Python source code is more pleasant than C++. So it balances out I guess.
- trinovantes 5y ago
  Which python libs do you find insufficiently documented? Admittedly I've only used Python for quick scripts or apps (bs4, fitz, flask) rather than my primary language so maybe my view is somewhat biased
- mshockwave 5y ago
  same, C++ doc can be awful...if it's hand-written, but doxygen is quite good. On the other hand, docs for dynamic languages like javascript and python often hang me there with ambiguous descriptions like "string-like" or "buffer-like" -- yes, I know what those descriptions _mean_ but that doesn't really give me enough confidence to use those APIs.
- mosra 5y ago
  While I'm here, a shameless self-promo -- Magnum uses a Python doc generator that includes type annotations by default, moving it closer to what you're used to from C++: https://blog.magnum.graphics/announcements/introducing-python-bindings/#everyone-just-uses-sphinx-you https://blog.magnum.graphics/announcements/introducing-pytho... (Sure, it still means the library has to make those annotations in the first place, and have them correct, but the newer and more complex libraries fortunately do, if even just to make IDE autocompletion work.)
flohofwoe 5y ago
Magnum's documentation is top tier IMHO. Just don't start with the API reference, but with this page: https://doc.magnum.graphics/magnum/pages.html https://doc.magnum.graphics/magnum/pages.html (which arguably should be the main page)
mosra 5y ago
Hah, good point, seems like this class suffers from documentation erosion. It got expanded and expanded and expanded and the essential piece of information got somehow lost down there in the gory details. The actual usage info and code snippet is in the base class documentation [1], it's just that it's no longer linked as prominently as it should be. I'll fix that. It's not this bad everywhere tho, docs of fresher APIs didn't have a chance to erode yet: https://doc.magnum.graphics/magnum/classMagnum_1_1Trade_1_1SceneData.html https://doc.magnum.graphics/magnum/classMagnum_1_1Trade_1_1S... [1] https://doc.magnum.graphics/magnum/classMagnum_1_1Trade_1_1AbstractImporter.html#Trade-AbstractImporter-usage https://doc.magnum.graphics/magnum/classMagnum_1_1Trade_1_1A...

tmaly 5y ago

Where did they come up with this name?

vasankar 5y ago

This is cool!

gary_0 5y ago

Some other interesting libraries I've seen along these lines: - Sokol (sokol_gfx in particular): https://github.com/floooh/sokol https://github.com/floooh/sokol - wgpu (see wgpu-native for the C API): https://github.com/gfx-rs/wgpu https://github.com/gfx-rs/wgpu It kind of seems like graphics abstractions for modern hardware are getting pretty "figured out". There are wrappers that work for most DirectX/Metal/OpenGL applications so they can run just about anywhere, and new 2D/3D applications have a lot of accessible/open-source options to build on top of. Projects like Mesa's Zink will centralize the burden of maintaining legacy APIs away from hardware manufacturers. Valve's Proton is making waves. WebGPU is on the way. The future looks bright.

pjmlp 5y ago
That isn't nothing new, 10 years ago, before free beer Unity and Unreal, one would be using something like Ogre 3D.
- girvo 5y ago
  Or Irrlicht, if you were me as a younger lad and scared off by Ogre at the time. There's always been a vibrant landscape of these sorts of tools, so it's neat to see another one
Animats 5y ago
Oh, I wish. There are plenty of game engines and graphics libraries for C++. We have enough of those. This is not yet true for Rust. There seem to be, but if you start to push the performance limits, problems appear. I've been writing a client for Second Life, which, despite all the hype from NFT land, is still the best metaverse around. It's just sluggish, so I'm trying to fix that. The stack I'm using is Rust->Rend3->WGPU->Vulkan->NVidia. Rust is doing fine. No problems at the language level. For this, I need Rust's safe concurrency; there are a lot of threads manipulating shared data. 18 months on, I only needed a debugger once, and the problem wasn't in my code. Rend3/WGPU provides a cross platform layer. Put in meshes, materials, textures, and transforms, and have a loop endlessly calling the render function. Other threads change the scene in parallel with rendering. Rend3 handles memory allocation and scheduling. Vulkan gives you access to the GPU's memory. Managing it is someone else's problem. WGPU provides a common interface to Vulkan, DirectX, and Apple's Metal, which all do pretty much the same thing, but incompatibly. WGPU sits below most of the major game engines on Rust. It all works, but not fast enough. There are locking bottlenecks at the Rend3 and WGPU levels which cause the render thread to be stalled when another thread is loading content. The whole point of Vulkan is that you can do both at once, but the Rend3 and WGPU levels don't quite have that working yet. The right functionality is there, but not the optimization needed for serious work. Nobody seems to be building AAA titles in Rust. I'm pushing the scene complexity to AAA title levels[1], and I seem to be close to the first person to do that. Not where I wanted to be. If you want to work on the lower levels, the WGPU and Rend3 projects, which are open source, need more good people. [1] https://video.hardlimit.com/w/peBesyAgtzfRWS5FnDQQtn https://video.hardlimit.com/w/peBesyAgtzfRWS5FnDQQtn

rychco 5y ago

I’ll definitely give this a try, it arrived exactly when I was exploring other visualization middleware. Also it’s a small thing but it was refreshing to see, in the use-cases section, the developer refer to Godot as a better fit for someone who needs a WYSIWYG editor for games.

Jasper_ 5y ago

Yikes, a GL-inspired graphics library... let's see, how many sins do I count: * Still using global enable/disable flags for all the state bits (e.g. depth test, face culling) rather than packing them into a PSO struct. Why? * Uniforms are bound manually and kept statefully rather than being provided as a UBO interface. * No support for draw call buffering or sorting, and what appears like limited support for multiple framebuffers. * Ooh, "SceneGraph", is that where the pass manager is? Oh, no, it's an object layer that seems to resemble circa OGRE around 2011. Doesn't seem to do any transparency sorting or pass management either. I'd really recommend something like bgfx, sokol, or wgpu instead, which have reduced their dependence on global state, and provide a much better foundation for modern graphics.

gameswithgabe 5y ago
Are we looking at the same code? I'm not an OpenGL or Vulkan expert, but: > ...rather than packing them into a PSO struct. Why? * You can clearly read on the front page of the repository that this supports OpenGL 2 through 4.6. I think you're just not looking hard enough. He has Vulkan support in here with a clearly marked file named Pipeline.cpp. The guy knows what a pipeline is... > ...rather than being provided as a UBO interface. * Is this not a UBO interface? > layout(std140) uniform material { vec4 diffuse; vec4 specular; }; It's in his documentation for AbstractShaderProgram. He has explicit binding for stuff pre OpenGL 3.3 or whenever OpenGL added UBOs. > ...appears like limited support for multiple framebuffers. * I don't see why you think there's limited support for multiple framebuffers...? From his docs: > @section GL-Framebuffer-usage-multiple-outputs Multiple fragment shader outputs And then it goes on to explain how to use multiple framebuffer outputs for something like deferred rendering. Moreover, his docs have snippets like this: > @deprecated_gl Prefer to use @ref AbstractFramebuffer::clearDepth() @ref AbstractFramebuffer::clearDepthStencil() instead of @ref setClearDepth() and @ref AbstractFramebuffer::clear() as it leads to less state changes Which clearly shows this guy knows what global state is and why it's bad. I think you're making very broad assumptions based on a very cursory glance at this project. I've only looked at it for about 30 minutes and it looks like a well developed library by somebody who knows what they're doing. I'm sure I could find code that counters the rest of your argument, but I don't feel like looking anymore. None of your criticism seem well intentioned. It might behoove you to give people the benefit of the doubt and realize that you may be able to learn something from them, even if they're so clearly inferior to you. P.S. Don't start off a criticism by saying "how many sins do I count". I don't know your experience, but that's just such an incredibly pretentious statement that's begging to be countered by somebody way more knowledgeable than you about this stuff.