ngf_cmd_buffer Struct Reference

Detailed Description

Encodes a series of rendering commands.

Internally, a command buffer may be in any of the following five states:

• new;
• ready;
• recording;
• awaiting submission;
• submitted.

Every newly created command buffer is in the "new" state. It can be transitioned to the "ready" state by calling ngf_start_cmd_buffer on it.

When a command buffer is in the "ready" state, you may begin recording a new series of rendering commands into it.

Recording commands into a command buffer is performed using command encoders. There are a few different types of encoders, supporting different types of commands.

A new encoder may be created for a command buffer only if the command buffer is in either the "ready" or the "awaiting submission" state.

Creating a new encoder for a command buffer transitions that command buffer to the "recording" state.

Finishing and disposing of an active encoder transitions its corresponding command buffer into the "awaiting submission" state.

The three rules above mean that a command buffer may not have more than one encoder active at a given time.

Once all of the desired commands have been recorded, and the command buffer is in the "awaiting submission" state, the command buffer may be submitted for execution via a call to ngf_submit_cmd_buffers, which transitions it into the "submitted" state.

Submission may only be performed on command buffers that are in the "awaiting submission" state.

Once a command buffer is in the "submitted" state, it is impossible to append any new commands to it. It is, however, possible to begin recording a new, completely separate batch of commands by calling ngf_start_cmd_buffer which implicitly transitions the buffer to the "ready" state if it is already "submitted". This does not affect any previously submitted commands.

Calling a command buffer function on a buffer that is in a state not expected by that function will result in an error. For example, calling ngf_submit_cmd_buffers would produce an error on a buffer that is in the "ready" state, since, according to the rules outlined above, ngf_submit_cmd_buffers expects command buffers to be in the "awaiting submission" state.