Messy #include structure?

[mctb32]

I'm just trying out Diligent Graphics and I've run into a problem right on the start when trying to initialize the engine. The "API Basics" article says that I need to add the following folders to my include paths:

diligentcore\Graphics\GraphicsEngineD3D11\interface
diligentcore\Graphics\GraphicsEngineD3D12\interface
diligentcore\Graphics\GraphicsEngineOpenGL\interface

But it seems that many more paths are needed when compiling the top level graphics includes. For example, the file "EngineD3D11Attribs.h" includes the file "BasicTypes.h", which is in a totally different folder and can't be found with just the paths given above.

I looked at the samples, and I see that they include many more paths in their settings. 15 paths in case of the SampleBase project...

Correct me if I'm wrong, but this seems very messy, uncomforatble for the end user, and also error prone (if you end up with two files of the same name in different paths, which might be true for large projects).

Wouldn't it be better to use relative paths inside the includes, like this:
#include "....\diligentcore\primitives\interface\basictypes.h"
or like this:
#include <diligentcore\primitives\interface\basictypes.h>
?

The first option doesn't force the end user of the engine to add any paths whatsoever to their proejct, they just need a way to localize the include file they are using. The second way assumes that just one path needs to be defined, in this case this is the top-level engine folder. Most of the libraries I worked with, have a single "includes" folder that needs to be added and they use relative paths inside. I think this is the standard and proven way.

Can you consider fixing this? Or do you have a list of paths that actually need to be included to use different modules?

Anyway, thanks for sharing your code and writing all the awesome articles on Gamasutra :)

Thank you for looking into this and sorry it did not work for you right away.
Diligent Engine is broken up into multiple projects with some dependencies between them. When you use cmake, it configures all dependencies and other settings. It is totally possible to change paths to be relative (though it may make potential code refactoring little harder), but it will only solve part of the problem as link dependencies also need to be specified. On top of that, cmake also configures other required setting such as platform-specific compile flags, libraries, macros, custom build steps etc. So even if you resolve include directories, it will not be enough to build the engine. You will need to add dependency on the libraries in your cmake file, like so:

target_link_libraries(MyApp 
PRIVATE 
        GraphicsEngineD3D11-shared
        GraphicsEngineD3D12-shared 
        GraphicsEngineOpenGL-shared
)

I will update the readme to make this clear.

Did you use CMake to generate build files or are you using another build system?

[mctb32]

Thanks for a quick answer. We don't use Cmake in our games, just Visual Studio and XCode projects that are managed manually. I didn't have any problems generating projects for Diligent Graphics and it works great out of the box when compiling and running the samples. But when I added the generated module projects into our solution, I've run into the problem with not configured include paths. Link dependencies are not a problem, as Visual Studio has the option to automatically link dependent project outputs, which we are using.

In the future, we plan to implement some kind of automated build system like Cmake, but it's not very high on our priority list as our structure is fairly complicated. I understand it would be less painful if we were using Cmake, but again it would be great if you could make the engine a little more friendly to build systems other than cmake. Hence the suggestion about using relative paths, be it per file or per one master include path.

BTW, I'm considering porting the next version of our in-house game engine CUG Framework to Diligent Graphics. Currently we have custom DX9/Windows, DX11/Windows,Xbox One and OpenGL/MacOS+iOS backends that we are developing and upkeeping on our won, but the interfaces are starting to show their age, as they were architected with DX8 fixed pipeline in mind many years ago. Our engine deals mostly with 2D graphics, with most of the geometry being quads generated on the CPU each frame and very frequent state switching. Our typical usage is: draw a few quads, switch blending mode, draw a few quads, switch clipping mode, draw a few quads, switch textures, and so thousands times per frame. What I want to do in the first place is test how Diligent Graphics will perform in such a use case in comparison to our current solutions.

I see, that makes perfect sense. I fixed all interface header files so that configuring include directories is no longer required to make them compile. I also added another tutorial that has no dependencies on other projects.

As to your use case, this should work pretty well with D3D12 backend and also reasonably well with D3D11 backend. OpenGL will likely be slower as the engine is designed for the next-gene APIs (it is also not as well optimized as D3D12 and D3D11). If you can do any sort of batching, this should work very well on all backends.
On the other hand, I am planning to start work on Vulkan very soon. I will try to set up a simple quad rendering sample in few days.

Closing this issue (DiligentGraphics/DiligentCore@038fa79)

[mctb32]

Thanks for making the changes! A quad rendering sample would be very helpful.

There are very many ways you can implement quad rendering, some of them more efficient some of them - less. If you can tell me little more about you case, I may be able to offer a more efficient approach. Few questions:

• How often will you need to switch shaders and states (blend/rasterizer/depth stencil)?
• How many quads will you typically need to render using the same pipeline settings? Can you batch quads? How many total quads you typically render?
• How often do you need to switch textures? Do you use texture atlases or texture arrays? In D3D12/Vulkan, you can bind all your textures at once and index them from shaders thus avoiding the cost of texture binding completely (though it may be little less efficient from GPU point of view).
• Can you generate command lists in parallel?

[mctb32]

Thanks for offering your input. Our games are mostly 2D. The engine was used in many casual games in the past, now we are working on a 2D hack & slash game.

Our low level graphics system is a lightweight C style API that sits on top of whatever API we are using on the target platform. For Windows this is currently DX9, OpenGL/ES for MacOS/iOS, and DX11 for XboX One. The DX9 backend is the most optimized, the other ones are fairly new.

On the most basic level (this is a very big simplification), the graphics system has 2 drawing functions (DrawQuad, DrawQuads) and a lot of state changing functions (like SetBlendingMode, SetTexture, SetClipping, SetViewport, SetTransform, SetRenderTarget, SetBlurEffect, etc.). In the DX9 backend, the draw functions append the provided primitives into a dynamic vertex buffer and each state changing function flushes the buffer to the GFX card (via DrawIndexed) and switches the state. Some flushes go through the fixed pipeline, but some go through custom shaders if the client enables advanced effects, such as blurring, desaturation, etc. Of course, the graphics system ignores duplicate state changes, so there is almost no penalty for repeating a call to, let’s say, SetTexture with the same handle.

The actual draw call batching is the responsibility of higher level systems, but in many cases we can’t optimize a lot. We don’t use a zbuffer, all sprites a drawn back to front, as all of them have transparency (anti-aliasing baked into the sprites). The sprites are packed into big textures (most textures are > 2048) like gui.tex, effects.tex, dungeon.tex, monster1.tex, monster2.tex, fonts.tex, etc. We try to minimize texture switching, but there is not a lot we can do. We end up with constant switching between monsterX.tex and effects.tex for example. In some cases we duplicate sprites between textures, to minimize switching.

Anyway, the DX9 backend works fine and the games run fine even on very low hardware. We are happy with that, even though I’m sure there is a lot we could optimize. The reason I’m looking into Diligent Graphics is that the current architecture is difficult to upkeep and build upon. Each backend has to implement all of the effects supported in the engine, and support them in all of the combinations. This was fine when we worked solely with the fixed pipeline, but now we find ourselves adding more and more shared based effects, and even doing some basic 3D graphics. We also are looking into dropping the DX9 backend, as we dropped WindowsXP support last year.

Theoretically, employing Diligent Graphics as a layer between the 3DAPI and our 2D effects/states system would allow us to write the effects/states part once for all platforms and also it would give us a good base to build on when we decide to extend our 3D features.

What I want to do first is to test how it would compare to our existing, optimized DX9 backend on the most basic use case (drawing single quads often interrupted by Texture/Blendmode change). Unfortunately, I wasn’t able to link our engine with Diligent graphics yet. Everything compiles fine, after the header changes (thanks for that!) but I’m getting linker errors coming from the DX SDK. I think I tracked it down to a difference in the Target Platform. The Diligent engine projects generated by cmake target the Windows 10 platform, while we use the “8.1” SDK version, as we need to support Windows 7. We can’t drop Win7 as it is still more than 50% of gamers.

So the question is, is it possible to generate diligent projects targeting the 8.1 SDK or is Win7 not supported?

By the way, this is the game we’re now working on: http://store.steampowered.com/app/449960/. I can send you a key, if you’re interested :)

You can generate VS project files targeting 8.1 SDK using the following cmake command:

cmake -H. -B./cmk_build/Win64_8.1 -DCMAKE_SYSTEM_VERSION=8.1 -G "Visual Studio 15 2017 Win64"

However, d3d12 is only supported in Win10 SDK. I made few updates to build files to handle this, but D3D12 backend needs to be manually disabled for the moment:

In DiligentCore/CMakeLists.txt, ln 48:

set(D3D12_SUPPORTED FALSE CACHE INTERNAL "D3D12 supported on Win32 platform")

The change above should be made before running the cmake command.

In DiligentCore/Platforms/interface/PlatformDefinitions.h, ln 46:

#   define D3D12_SUPPORTED 0

In unityplugin/GhostCubeScene/PluginSource/src/PlatformBase.h, ln 43:

#define SUPPORT_D3D12 0

If you only want to build Core module, you only really need to do the first change.

What link errors are you getting, BTW?

Thanks for explaining the details, I now definitely have much better picture. I am taking the next week off, but I will make the quad rendering sample the first thing I am back.

Meanwhile, I would be happy to try out the game. Could you please send the key to info@diligentgraphics.com?

[mctb32]

I sent you an email. Thanks again for the help.