RenderTarget3D for DirectX

[tomspilman]

Added support for new class RenderTarget3D which works similar to its 2D and Cube counterparts. This feature does not exist in XNA, but actually fits in pretty elegantly into the API.

• Added RenderTarget3D class with DX implementation.
• Added GraphicsDevice.SetRenderTarget(RenderTarget3D, arraySlice).
• Made RenderTargetBinding a little more generic to handle both cube and 3D textures.
• Fixed bug were Texture3D.Format was not set.

This should be portable to OpenGL desktop systems, but i'm not sure of OpenGL ES platforms.

Also this currently only works by selecting the depth layer to render into on the CPU side via GraphicsDevice.SetRenderTarget. Eventually when we support geometry shaders in MGFX we can also do this on the GPU.

[mgbot]

Build results will soon be (or already are) available at: http://build.monogame.net/job/PullRequestTester/29/

[mgbot]

Build results will soon be (or already are) available at: http://build.monogame.net/job/PullRequestTester/30/

[CartBlanche]

Tom where can I read up on the uses of RenderTarget3D?
How hard easy will it be to implement in OpenGL?

[tomspilman]

Tom where can I read up on the uses of RenderTarget3D?

There isn't much to read... some high end algorithms require generation of a 3D texture. Often the best way to do that is to directly render into one instead of building one on the CPU. This PR allows you to do that where as MS XNA does not. The process is really not much different than RenderTargetCube... except this is a volume texture and not a cube texture.

How hard easy will it be to implement in OpenGL?

For OpenGL on the desktop it should be easy.

I do not think it is currently supported for GLES on iOS and Android, but it will be in GLES 3.0.

[tomspilman]

@slygamer @dellis1972 - You guys good with this? It is just adding overlooked functionality that should have been in XNA4.

[KonajuGames]

This PR will need an update since I merged another PR that modified GraphicsDevice.cs.

I'm happy with this one. We can add the OpenGL support later. It won't be supported under OpenGL ES 2.0. Once this PR is updated (should be a trivial update) I'm happy to merge it.

[tomspilman]

@mgbot test

[tomspilman]

Fixed

[mgbot]

Build results will soon be (or already are) available at: http://build.monogame.net/job/PullRequestTester/84/

[totallyeviljake]

While this is a great addition to MonoGame, this does break compatibility with XNA 4. Anyone who uses RenderTarget3D will not be able to port their game back to MSFT XNA.

[shmuelie]

Honestly how common is that? From what I can tell XNA -> MonoGame is much more common

[totallyeviljake]

A lot more common than you might think. Buy an xbox 360 and you can deploy your game there as an indie developer. If you use RenderTarget3D then you won't be able to do that.

There were other extensions to MonoGame that were denied, so what makes this change different?

[KonajuGames]

I would be willing to reconsider those other extensions. If I remember
rightly, they were simple extensions.

[totallyeviljake]

I just want to be fair to the contributors and make it well known that MonoGame is now taking a divergent path from XNA 4.

That said, there needs to be some guidelines about what will be accepted and what won't.

[shmuelie]

Could we make a MonoGame core that matches XNA and a MonoGame extended that adds features like this. If we make it clear the difference it could work

[tomspilman]

make it well known that MonoGame is now taking
a divergent path from XNA 4

The plan all along has been to start expanding MonoGame this year beyond XNA 4.0, but to do so in a smart way. We have always been vocal that post 3.0 we were going to start changing things, but still maintain 100% compatibility with XNA.

There were other extensions to MonoGame that were
denied, so what makes this change different?

So why RenderTarget3D and not something like the PR "Added Wrap methods to MathHelper"?

RenderTarget3D is wrapping GPU functionality that is different across platforms. It was also an obvious gap in functionality... RenderTarget2D and RenderTargetCube both exist in XNA 4, but RenderTarget3D did not... most likely because it was rarely used feature and simple to cut. The fact it fit so cleanly into the existing API is a testament for its inclusion.

The MathHelper.Wrap method code is 100% the same across all platforms. This code could just as easily live in another library that is compatible with XNA and MonoGame.

IMO MonoGame is not a bucket of utility methods... it is about hardware/platform abstractions.

[totallyeviljake]

Thanks @tomspilman that's a good start on the criteria for what is included in the extension and what is not. We're not looking for a upward capability that is broad, but rather a deeper capability that we can implement across all of the platforms.

That's fair, so long as we can stick to it. Graphics capability extensions are a good extension, no doubt, and then sound (3D) extensions. I nominate you to write that into the wiki. (haha)

[tomspilman]

I would say what we should consider are things that require abstraction across platforms. Even then anyone wanting to contribute something big should always reach out to us first.

[luiscubal]

I think MonoGame should be backwards compatible with XNA, but I see no problem if XNA is not forward compatible with MonoGame. Just make sure the added APIs are documented as such.

About guidelines, I propose the following:

1. The API itself is considered sufficiently high-quality. That is, it is well designed and it "fits" well with the rest of MonoGame.
2. It enables features that are either not possible or not feasible without it. In this case, RenderTarget3D could make some use-cases possible (that currently aren't) and other use-cases substantially faster than they would otherwise, right?
3. The API must come with high-quality documentation. The rationate for this requirement is that there isn't an excuse of "Check XNA's documentation instead" for monogame-exclusive features.
4. It is supported by more than one platform (e.g. it's not DirectX-exclusive). That said, this last requirement might not be a good idea. I've seen people requesting platform-specific features (e.g. access to device handles) in this bug tracker, and this would go against that.

I believe (I haven't checked 1 in detail) that RenderTarget3D correctly matches all the requirements except for 3. So I'd propose that this feature be merged in as soon as proper documentation is added.