Buffer Modes

[RobertMtx]

Hey, I'm new here. Still getting started with the API. I'm converting my engine from D3D9 to Diligent, and its going very well so far. I just had a question about Buffer Modes (Diligent::BUFFER_MODE). Can anyone help me understand what situations these would be used in? And/or what the purpose of using them are? I have not gotten far enough to start uploading custom data to shaders, so this may be why I don't yet understand these.

I may somewhat understand BUFFER_MODE_STRUCTURED. Would this be used to transmit data to the shader that contains typename elements in it? Is there any particular reason to use it instead of BUFFER_MODE_UNDEFINED? Is that reason just to make sure the shader can sort the data out correctly?

As for BUFFER_MODE_FORMATTED, I'm somewhat lost, but suspect it may have something to do with linking shader-based values? Again, what is the purpose of using this in place of undefined?

Lastly, is there any API documentation that's up to date? I found http://diligentgraphics.com/doc/index.html , but it appears to contain types that don't exist, and seems to be missing types that do. Also, the main page is showing up blank, so I'm not sure what version it relates to.

Thanks for any info!

[TheMostDiligent]

For buffer modes, you need to specify one when you create a buffer view, e.g. you are going to access the buffer through a shader view
or unordered access view in the shader. Take a look at tutorial 14, it has examples of both types.

Structured buffers are buffers that consist of array of structures:

StructuredBuffer<ParticleAttribs> g_Particles;

...

ParticleAttribs Particle = g_Particles[iParticleIdx];

Formatted buffers are accessed somewhat like 1D-textures. They allow format conversion when you read data from them (e.g. UNORM->FLOAT).

As to the documentation, the most recent is in the header files. The one on the web site is quite out-dated.

[RobertMtx]

That helps, thanks! The header comments are very helpful. I have not needed to look elsewhere more than once so far.

BTW, the engine is pretty robust and impressively specific. You've hidden nearly every graphics API reference from the client. It must have taken quite some effort to put this together. It is very much appreciated!

[RobertMtx]

Sorry to resurrect this older thread, but while working through some buffer layouts, I noticed that none of the sample projects use BUFFER_MODE_FORMATTED except for a couple <int> buffers used for particle indices, in Tutorial 14. I'm wondering why the particle shader uses the formatted buffer for indices?

I also could not find any references to BUFFER_MODE_FORMATTED in the D3D12 buffer impl. Do formatted buffers have the same behavior as undefined (non-structured) buffers in D3D12?

I have two buffers that are packed with float4 and int4, and I'm trying to figure out which buffer mode would work best for those. Would I just use undefined for these, since they are already in the expected format? Or is it more preferable/common to use a formatted buffer because it is packed with a small basic type? I tried to search online for related information, but found nothing on D3D12 and formatted buffers.

[TheMostDiligent]

Formatted buffers work largely the same way as 1D textures. They allow format conversion on the fly. For instance, you can bind RGBA8_UNORM data buffer to a Buffer<float4> and it will convert UNORM->float conversion on the fly.

For float4 and int4 you can use either formatted or structured buffer. I honestly don't know which will work better. Probably, there will be no difference, so use whatever is more convenient.

[RobertMtx]

After getting things further along, I've run into another issue that has made me realize I apparently still don't understand the workflow to use dynamic buffers correctly in DX12 mode. I was under the impression that I could just map a dynamic buffer and leave it mapped indefinitely. But Diligent is throwing an error, reporting that the buffer contents have been discarded at the end of every frame. In..
BufferD3D12Impl::DvpVerifyDynamicAllocation(const DeviceContextD3D12Impl* pCtx) const
at line..
DEV_CHECK_ERR(m_DynamicData[ContextId].DvpCtxFrameNumber == CurrentFrame, "Dynamic allocation of dynamic buffer '", m_Desc.Name, "' in frame ", CurrentFrame, " is out-of-date. Note: contents of all dynamic resources is discarded at the end of every frame. A buffer must be mapped before its first use in any frame.");

What is the correct workflow for a dynamic buffer in DX12 for a buffer that is constantly re-used and rendered? Should I map it at the beginning of every frame, then unmap it before calling present? I think I read somewhere in the engine notes that it's better to not bother unmapping the buffer when working in newer APIs. Does this mean I call MapBuffer() every frame, but don't bother using UnmapBuffer()? Will this still throw the exception?

Sorry, for some reason, I can't seem to grasp the correct workflow/usage of dynamic buffers. Really appreciate any advice you can give me here.

[TheMostDiligent]

Should I map it at the beginning of every frame, then unmap it before calling present?

Yes

I think I read somewhere in the engine notes that it's better to not bother unmapping the buffer when working in newer APIs.

Within one frame.

Does this mean I call MapBuffer() every frame, but don't bother using UnmapBuffer()? Will this still throw the exception?

You should still call Unmap or validation will be unhappy.

[RobertMtx]

That clears things up. Thanks a lot! Finally got something on the screen, after exactly 2 months of replacing my graphics system with Diligent. That amount of time was while working around a full time job, though. Also, I didn't start small and build up while testing, like a smart person does. Instead, I jumped in head first, like a crazy person would, completely replacing the previous system before ever testing a single line of code. It's not a great way to do things, because so many things can go wrong at the same time.

[RobertMtx]

Mapping it at the beginning of each frame, then unmapping at the end seems to work pretty well, but I'm running into a situation where, if I run out of buffer memory and restart the buffer iterator, it seems to ignore some of the data.

I'm currently only writing onto 1/4th of the buffer at a time, rendering that, writing to the next 1/4th of it, rendering that, repeat, then loop back to zero when I reach the end, But as soon as my buffer write pointer loops back to zero, things start disappearing. I'm assuming this is because I shouldn't be looping back to memory that I've already submitted for rendering?

If that is the case, how would I avoid writing onto dynamic memory that the GPU is still using? If I run out of dynamic buffer space, should I unmap/remap the buffer when I start back at zero? Will that be enough to stay in sync with the GPU?

Edit: While doing some pure Dx12 reading, it looks like some developers do some type of double-buffering method for this situation. Basically they flip between 2 buffers, filling one while the GPU finishes with the other. They mention using fence/barriers to make sure the GPU finishes with the previous buffer before switching. I have to admit, resource states & fencing is not something I have a firm grasp on as of yet. I tried what I mentioned above, remapping the buffer when I run out of space, and it seems to work. But now I'm wondering why it works, unless its because Diligent is doing something in the background, such as waiting for the GPU to finish with the buffer?

Edit 2: I just re-read the notes about tutorial 10, and it seems to answer most of my questions. From what I gather, remapping a dynamic buffer with MAP_FLAG_DISCARD (which I've always done), seems to request a new block of memory to work with. So I'm guessing that's probably the way to go.

[TheMostDiligent]

I'm assuming this is because I shouldn't be looping back to memory that I've already submitted for rendering?

Yes.

If I run out of dynamic buffer space, should I unmap/remap the buffer when I start back at zero?

Yes.

Will that be enough to stay in sync with the GPU?

Yes. Take a look at Tutorial 10.

But now I'm wondering why it works

When you map the buffer and issue draw command, nothing happens on the GPU yet, only the command buffer is recorded. If you use the same pointer, you simply overwrite memory that is already referenced by another draw call. Mapping/Unmapping gives you new memory. Commands are executed on the GPU when the command buffer is submitted at the end of the frame.

[RobertMtx]

That makes a lot of sense, thanks. Would there be any reason to do some type of double buffering, as others have mentioned? Would there be an advantage to doing that vs just remapping the same buffer?

I guess I'm just a little unsure of what happens when the buffer is unmapped. Does Diligent Engine find me a new chunk of free memory, or is that something that the DX12/GPU handles?

[TheMostDiligent]

Would there be any reason to do some type of double buffering, as others have mentioned? Would there be an advantage to doing that vs just remapping the same buffer?

In the majority of scenarios no. Diligent handles this for you.

Does Diligent Engine find me a new chunk of free memory

Yes

[RobertMtx]

Thanks for the advice. Sorry to ask so many questions, but do you know if there is any way to query the maximum size of a dynamic buffer? I looked through the members of GraphicsAdapterInfo, but couldn't find anything related.

I was hoping that requesting a buffer that is too large would simply fail to create the buffer, so that I could detect that and reduce it. But DX12 seems to just entirely shut down the graphics device, making it pretty much impossible to recover from the situation. Through trial and error, it looks like 64MB might be the limit in my specific case, but I'm not sure if that is due to my card's specs, Diligent's inner workings, DX12, etc.

[TheMostDiligent]

Do you know if there is any way to query the maximum size of a dynamic buffer?
Through trial and error, it looks like 64MB might be the limit in my specific case

There is currently no way to get this, but 64 MB is a good approximation. Do you need to upload more than that?

[RobertMtx]

No, I currently have it set to 1MB, and not even using half of it. But I haven't been pushing to any limits yet. And I still need to change my particle system and others to use the same buffer, but I doubt it will need to be much larger than 1MB to render most of the dynamic elements in a single frame without remapping the buffer.

I added this specific buffer's size to my engine's ini-like file as a low-level engine setting, since it such a major part of engine functionality, and remapping the buffer several times per frame may not be ideal. Anyway, I figured I should handle the situation where it is being set too high. But for now, I'll just cap it off at 64MB.

[RobertMtx]

I know I've dragged this buffer conversion out far longer than it should be, but I have yet another question if you get a moment.

I'm wondering what happens in the following scenario, with a structured buffer that contains arbitrary (non-vertex) data that is accessed by the vertex/pixel shaders (a shader resource buffer):

1. Fill the dynamic buffer up entirely until it runs out of space
2. Send draw commands that make use of the buffer contents - draw everything that will use the buffer's current contents
3. Remap the buffer and fill it again, in the same frame
4. Send more draw commands that make use of the buffer's second-iteration-contents

I'm a little unsure of weather this will work as expected, since you mentioned that all draw commands wait until the end of a frame to execute. Does this mean that half of the draw commands will be using one section of memory, while the other half will use another, even though they both expect to be using the same shader resource buffer? Or will this strategy fail to work, overwriting the shader's view of the buffer location when it is remapped, resulting in all draw commands using the contents of the second iteration and ignoring the first?

[TheMostDiligent]

Dynamic buffers need to be mapped every frame. After Present is called, their content is undefined. Also, you can only use the pointer between Map and Unmap calls.

[RobertMtx]

Okay, this took forever to track down, but the reason for the exception was because of unused (never touched) dynamic buffers being defined in the PipelineResourceDesc array before the used ones. So for example, if I have something like..
PipelineResourceDesc vars[] = { A,B,C }; and link that to my pipeline resource signature, but then never make use of buffer B, then trying to access buffer C in the shader will throw the exception, but using buffer A will be totally fine. If I simply make sure I call Context.MapBuffer(B) and Context.UnmapBuffer(B), then no exceptions when trying to use buffer C.

I could understand this type of exception being thrown when attempting to write or read a buffer that was never mapped, or was left mapped at the end of the frame. But in this case, the buffer defined before the others was never touched at all. It isn't mapped, read to, written to, or accessed in the shader. Just its presence in the resource variables list throws the exception when trying to read anything defined below it. (Edit: Looks like you also need to link the unused buffer to the shader resource binding for the exception to happen: SRB->GetVariableByName( ..., "Name")->Set( UnusedBuffer->GetDefaultView(BUFFER_VIEW_SHADER_RESOURCE) ); If this is not called, it won't cause exceptions for the buffers below it.)

Any idea why this would be happening? If you think I may be doing something wrong somewhere else that is leaking chaos into other areas, let me know, and I'll try to modify one of the Diligent samples to see if I can get the problem to happen there. Should be able to just add a new buffer at the top of the PipelineResourceDesc list and just never touch it.

Edit: Just to add more details, I wanted to note that all of the buffers don't need to be mapped every frame. They just need to be mapped at least once before the first present() is called, as far as I can tell.

[TheMostDiligent]

I honestly don't know. Maybe Direct3D12 runtime does something strange.
If you can provide a simple reproducer based on one of Diligent samples, this will be very helpful.

[RobertMtx]

I looked into it after posting that, but unfortunately, the only sample code that creates a shared pipeline resource (with CreatePipelineResourceSignature()) is tutorial 22. But oddly, it does not want to run on my system, reporting that my GPU doesn't support ray tracing. Its surprising, because my video card is a decent card (NVidia GeForce GTX 1080) that supports shader model 6.5, but maybe ray tracing is still too young for it.

Unfortunately, I wouldn't have any way to to test modifications to that sample. Let me know if there is some other code I can test that scenario with.

[TheMostDiligent]

GTX 1080 does not support ray tracing. Ray tracing requires 20XX series or later.
I can suggest modifying one of the tutorials to use signatures.