Detailed Description

This section contains documentation for the core nicegraf routines, structures and enumerations.

General Remarks

The library is currently not intended to be linked dynamically.
When nicegraf's C headers are included from C++, all global functions within them are automatically declared to have C linkage. Additionally, they are declared to be noexcept.

Objects

nicegraf objects, such as images, buffers, render targets, etc., are represented using opaque handles. The objects are constructed and destroyed explicitly by the application, and it is the responsibility of the application to ensure that the order of destruction is correct. For applications written in C++, a set of wrappers that automate object lifetime management is available. See C++ Wrappers for details.

Error Reporting

Most nicegraf routines report their completion status by returning an ngf_error, and write their results to out-parameters. The returned value is a generic error code. Detailed, human-readable information about errors may vary from platform to platform; nicegraf reports it by invoking a user-provided callback function (see ngf_diagnostic_info). The callback function must accept the diagnostic message type (see ngf_diagnostic_message_type), an arbitrary void pointer (the value of which the user may specify when providing the callback), a printf-style format string, and an arbitrary number of arguments specifying the data for the format-string.

Host Memory Management

By default, nicegraf uses the standard malloc/free to manage host memory for internal purposes. The client may override this behavior by supplying custom memory allocation callbacks (see ngf_allocation_callbacks).

GPU Memory Management

nicegraf internally manages GPU memory for all backends. It is currently not possible for clients to override this behavior and do their own GPU memory management.

Data Structures
struct	ngf_diagnostic_info

struct	ngf_allocation_callbacks

struct	ngf_irect2d

struct	ngf_extent3d

struct	ngf_offset3d

struct	ngf_shader_stage_info

struct	ngf_shader_stage

struct	ngf_rasterization_info

struct	ngf_stencil_info

struct	ngf_depth_stencil_info

struct	ngf_blend_info

struct	ngf_vertex_buf_binding_desc

struct	ngf_vertex_attrib_desc

struct	ngf_vertex_input_info

struct	ngf_multisample_info

struct	ngf_attachment_description

struct	ngf_attachment_descriptions

struct	ngf_constant_specialization

struct	ngf_specialization_info

struct	ngf_graphics_pipeline_info

struct	ngf_graphics_pipeline

struct	ngf_compute_pipeline_info

struct	ngf_compute_pipeline

struct	ngf_sampler_info

struct	ngf_sampler

struct	ngf_image_info

struct	ngf_image

struct	ngf_image_ref

struct	ngf_render_target_info

struct	ngf_render_target

struct	ngf_clear_info

struct	ngf_render_encoder

struct	ngf_xfer_encoder

struct	ngf_compute_encoder

struct	ngf_render_pass_info

struct	ngf_xfer_pass_info

struct	ngf_compute_pass_info

struct	ngf_buffer_info

struct	ngf_buffer

struct	ngf_buffer_slice

struct	ngf_texel_buffer_view

struct	ngf_buffer_bind_info

struct	ngf_image_sampler_bind_info

struct	ngf_resource_bind_op

struct	ngf_swapchain_info

struct	ngf_context

struct	ngf_context_info

struct	ngf_cmd_buffer_info

struct	ngf_cmd_buffer

struct	ngf_device_capabilities

struct	ngf_device

Macros
#define	NGF_DEVICE_NAME_MAX_LENGTH (256u)

Typedefs
typedef uint32_t	ngf_device_handle

typedef uintptr_t	ngf_frame_token

Enumerations
enum	ngf_diagnostic_log_verbosity { NGF_DIAGNOSTICS_VERBOSITY_DEFAULT , NGF_DIAGNOSTICS_VERBOSITY_DETAILED }

enum	ngf_diagnostic_message_type { NGF_DIAGNOSTIC_INFO , NGF_DIAGNOSTIC_WARNING , NGF_DIAGNOSTIC_ERROR }

enum	ngf_device_performance_tier { NGF_DEVICE_PERFORMANCE_TIER_HIGH = 0 , NGF_DEVICE_PERFORMANCE_TIER_LOW , NGF_DEVICE_PERFORMANCE_TIER_UNKNOWN , NGF_DEVICE_PERFORMANCE_TIER_COUNT }

enum	ngf_error { NGF_ERROR_OK = 0 , NGF_ERROR_OUT_OF_MEM , NGF_ERROR_OBJECT_CREATION_FAILED , NGF_ERROR_OUT_OF_BOUNDS , NGF_ERROR_INVALID_FORMAT , NGF_ERROR_INVALID_SIZE , NGF_ERROR_INVALID_ENUM , NGF_ERROR_INVALID_OPERATION }

enum	ngf_stage_type { NGF_STAGE_VERTEX = 0 , NGF_STAGE_FRAGMENT , NGF_STAGE_COMPUTE , NGF_STAGE_COUNT }

enum	ngf_polygon_mode { NGF_POLYGON_MODE_FILL = 0 , NGF_POLYGON_MODE_LINE , NGF_POLYGON_MODE_POINT , NGF_POLYGON_MODE_COUNT }

enum	ngf_cull_mode { NGF_CULL_MODE_BACK = 0 , NGF_CULL_MODE_FRONT , NGF_CULL_MODE_FRONT_AND_BACK , NGF_CULL_MODE_NONE , NGF_CULL_MODE_COUNT }

enum	ngf_front_face_mode { NGF_FRONT_FACE_COUNTER_CLOCKWISE = 0 , NGF_FRONT_FACE_CLOCKWISE , NGF_FRONT_FACE_COUNT }

enum	ngf_compare_op { NGF_COMPARE_OP_NEVER = 0 , NGF_COMPARE_OP_LESS , NGF_COMPARE_OP_LEQUAL , NGF_COMPARE_OP_EQUAL , NGF_COMPARE_OP_GEQUAL , NGF_COMPARE_OP_GREATER , NGF_COMPARE_OP_NEQUAL , NGF_COMPARE_OP_ALWAYS , NGF_COMPARE_OP_COUNT }

enum	ngf_stencil_op { NGF_STENCIL_OP_KEEP = 0 , NGF_STENCIL_OP_ZERO , NGF_STENCIL_OP_REPLACE , NGF_STENCIL_OP_INCR_CLAMP , NGF_STENCIL_OP_INCR_WRAP , NGF_STENCIL_OP_DECR_CLAMP , NGF_STENCIL_OP_DECR_WRAP , NGF_STENCIL_OP_INVERT , NGF_STENCIL_OP_COUNT }

enum	ngf_blend_factor { NGF_BLEND_FACTOR_ZERO = 0 , NGF_BLEND_FACTOR_ONE , NGF_BLEND_FACTOR_SRC_COLOR , NGF_BLEND_FACTOR_ONE_MINUS_SRC_COLOR , NGF_BLEND_FACTOR_DST_COLOR , NGF_BLEND_FACTOR_ONE_MINUS_DST_COLOR , NGF_BLEND_FACTOR_SRC_ALPHA , NGF_BLEND_FACTOR_ONE_MINUS_SRC_ALPHA , NGF_BLEND_FACTOR_DST_ALPHA , NGF_BLEND_FACTOR_ONE_MINUS_DST_ALPHA , NGF_BLEND_FACTOR_CONSTANT_COLOR , NGF_BLEND_FACTOR_ONE_MINUS_CONSTANT_COLOR , NGF_BLEND_FACTOR_CONSTANT_ALPHA , NGF_BLEND_FACTOR_ONE_MINUS_CONSTANT_ALPHA , NGF_BLEND_FACTOR_COUNT }

enum	ngf_blend_op { NGF_BLEND_OP_ADD , NGF_BLEND_OP_SUB , NGF_BLEND_OP_REV_SUB , NGF_BLEND_OP_MIN , NGF_BLEND_OP_MAX , NGF_BLEND_OP_COUNT }

enum	ngf_type { NGF_TYPE_INT8 = 0 , NGF_TYPE_UINT8 , NGF_TYPE_INT16 , NGF_TYPE_UINT16 , NGF_TYPE_INT32 , NGF_TYPE_UINT32 , NGF_TYPE_FLOAT , NGF_TYPE_HALF_FLOAT , NGF_TYPE_DOUBLE , NGF_TYPE_COUNT }

enum	ngf_sample_count { NGF_SAMPLE_COUNT_1 = 1 , NGF_SAMPLE_COUNT_2 = 2 , NGF_SAMPLE_COUNT_4 = 4 , NGF_SAMPLE_COUNT_8 = 8 , NGF_SAMPLE_COUNT_16 = 16 , NGF_SAMPLE_COUNT_32 = 32 , NGF_SAMPLE_COUNT_64 = 64 }

enum	ngf_image_format { NGF_IMAGE_FORMAT_R8 = 0 , NGF_IMAGE_FORMAT_RG8 , NGF_IMAGE_FORMAT_RGB8 , NGF_IMAGE_FORMAT_RGBA8 , NGF_IMAGE_FORMAT_SRGB8 , NGF_IMAGE_FORMAT_SRGBA8 , NGF_IMAGE_FORMAT_BGR8 , NGF_IMAGE_FORMAT_BGRA8 , NGF_IMAGE_FORMAT_BGR8_SRGB , NGF_IMAGE_FORMAT_BGRA8_SRGB , NGF_IMAGE_FORMAT_RGB10A2 , NGF_IMAGE_FORMAT_R32F , NGF_IMAGE_FORMAT_RG32F , NGF_IMAGE_FORMAT_RGB32F , NGF_IMAGE_FORMAT_RGBA32F , NGF_IMAGE_FORMAT_R16F , NGF_IMAGE_FORMAT_RG16F , NGF_IMAGE_FORMAT_RGB16F , NGF_IMAGE_FORMAT_RGBA16F , NGF_IMAGE_FORMAT_RG11B10F , NGF_IMAGE_FORMAT_RGB9E5 , NGF_IMAGE_FORMAT_R16_UNORM , NGF_IMAGE_FORMAT_R16_SNORM , NGF_IMAGE_FORMAT_RG16_UNORM , NGF_IMAGE_FORMAT_RG16_SNORM , NGF_IMAGE_FORMAT_RGBA16_UNORM , NGF_IMAGE_FORMAT_RGBA16_SNORM , NGF_IMAGE_FORMAT_R8U , NGF_IMAGE_FORMAT_R8S , NGF_IMAGE_FORMAT_R16U , NGF_IMAGE_FORMAT_R16S , NGF_IMAGE_FORMAT_RG16U , NGF_IMAGE_FORMAT_RGB16U , NGF_IMAGE_FORMAT_RGBA16U , NGF_IMAGE_FORMAT_R32U , NGF_IMAGE_FORMAT_RG32U , NGF_IMAGE_FORMAT_RGB32U , NGF_IMAGE_FORMAT_RGBA32U , NGF_IMAGE_FORMAT_BC7 , NGF_IMAGE_FORMAT_BC7_SRGB , NGF_IMAGE_FORMAT_ASTC_4x4 , NGF_IMAGE_FORMAT_ASTC_4x4_SRGB , NGF_IMAGE_FORMAT_ASTC_5x4 , NGF_IMAGE_FORMAT_ASTC_5x4_SRGB , NGF_IMAGE_FORMAT_ASTC_5x5 , NGF_IMAGE_FORMAT_ASTC_5x5_SRGB , NGF_IMAGE_FORMAT_ASTC_6x5 , NGF_IMAGE_FORMAT_ASTC_6x5_SRGB , NGF_IMAGE_FORMAT_ASTC_6x6 , NGF_IMAGE_FORMAT_ASTC_6x6_SRGB , NGF_IMAGE_FORMAT_ASTC_8x5 , NGF_IMAGE_FORMAT_ASTC_8x5_SRGB , NGF_IMAGE_FORMAT_ASTC_8x6 , NGF_IMAGE_FORMAT_ASTC_8x6_SRGB , NGF_IMAGE_FORMAT_ASTC_8x8 , NGF_IMAGE_FORMAT_ASTC_8x8_SRGB , NGF_IMAGE_FORMAT_ASTC_10x5 , NGF_IMAGE_FORMAT_ASTC_10x5_SRGB , NGF_IMAGE_FORMAT_ASTC_10x6 , NGF_IMAGE_FORMAT_ASTC_10x6_SRGB , NGF_IMAGE_FORMAT_ASTC_10x8 , NGF_IMAGE_FORMAT_ASTC_10x8_SRGB , NGF_IMAGE_FORMAT_ASTC_10x10 , NGF_IMAGE_FORMAT_ASTC_10x10_SRGB , NGF_IMAGE_FORMAT_ASTC_12x10 , NGF_IMAGE_FORMAT_ASTC_12x10_SRGB , NGF_IMAGE_FORMAT_ASTC_12x12 , NGF_IMAGE_FORMAT_ASTC_12x12_SRGB , NGF_IMAGE_FORMAT_DEPTH32 , NGF_IMAGE_FORMAT_DEPTH16 , NGF_IMAGE_FORMAT_DEPTH24_STENCIL8 , NGF_IMAGE_FORMAT_UNDEFINED , NGF_IMAGE_FORMAT_COUNT }

enum	ngf_attachment_type { NGF_ATTACHMENT_COLOR = 0 , NGF_ATTACHMENT_DEPTH , NGF_ATTACHMENT_DEPTH_STENCIL }

enum	ngf_primitive_topology { NGF_PRIMITIVE_TOPOLOGY_TRIANGLE_LIST = 0 , NGF_PRIMITIVE_TOPOLOGY_TRIANGLE_STRIP , NGF_PRIMITIVE_TOPOLOGY_LINE_LIST , NGF_PRIMITIVE_TOPOLOGY_LINE_STRIP , NGF_PRIMITIVE_TOPOLOGY_COUNT }

enum	ngf_descriptor_type { NGF_DESCRIPTOR_UNIFORM_BUFFER = 0 , NGF_DESCRIPTOR_IMAGE , NGF_DESCRIPTOR_SAMPLER , NGF_DESCRIPTOR_IMAGE_AND_SAMPLER , NGF_DESCRIPTOR_TEXEL_BUFFER , NGF_DESCRIPTOR_STORAGE_BUFFER , NGF_DESCRIPTOR_STORAGE_IMAGE , NGF_DESCRIPTOR_TYPE_COUNT }

enum	ngf_sampler_filter { NGF_FILTER_NEAREST = 0 , NGF_FILTER_LINEAR , NGF_FILTER_COUNT }

enum	ngf_sampler_wrap_mode { NGF_WRAP_MODE_CLAMP_TO_EDGE = 0 , NGF_WRAP_MODE_REPEAT , NGF_WRAP_MODE_MIRRORED_REPEAT , NGF_WRAP_MODE_COUNT }

enum	ngf_image_usage { NGF_IMAGE_USAGE_SAMPLE_FROM = 0x01 , NGF_IMAGE_USAGE_ATTACHMENT = 0x02 , NGF_IMAGE_USAGE_XFER_DST = 0x04 , NGF_IMAGE_USAGE_MIPMAP_GENERATION = 0x08 , NGF_IMAGE_USAGE_STORAGE = 0x10 , NGF_IMAGE_USAGE_XFER_SRC = 0x20 }

enum	ngf_image_type { NGF_IMAGE_TYPE_IMAGE_2D = 0 , NGF_IMAGE_TYPE_IMAGE_3D , NGF_IMAGE_TYPE_CUBE , NGF_IMAGE_TYPE_COUNT }

enum	ngf_cubemap_face { NGF_CUBEMAP_FACE_POSITIVE_X , NGF_CUBEMAP_FACE_NEGATIVE_X , NGF_CUBEMAP_FACE_POSITIVE_Y , NGF_CUBEMAP_FACE_NEGATIVE_Y , NGF_CUBEMAP_FACE_POSITIVE_Z , NGF_CUBEMAP_FACE_NEGATIVE_Z , NGF_CUBEMAP_FACE_COUNT }

enum	ngf_attachment_load_op { NGF_LOAD_OP_DONTCARE = 0 , NGF_LOAD_OP_KEEP , NGF_LOAD_OP_CLEAR , NGF_LOAD_OP_COUNT }

enum	ngf_attachment_store_op { NGF_STORE_OP_DONTCARE = 0 , NGF_STORE_OP_STORE , NGF_STORE_OP_RESOLVE , NGF_STORE_OP_COUNT }

enum	ngf_buffer_storage_type { NGF_BUFFER_STORAGE_HOST_READABLE , NGF_BUFFER_STORAGE_HOST_WRITEABLE , NGF_BUFFER_STORAGE_HOST_READABLE_WRITEABLE , NGF_BUFFER_STORAGE_DEVICE_LOCAL , NGF_BUFFER_STORAGE_DEVICE_LOCAL_HOST_WRITEABLE , NGF_BUFFER_STORAGE_DEVICE_LOCAL_HOST_READABLE_WRITEABLE }

enum	ngf_buffer_usage { NGF_BUFFER_USAGE_XFER_SRC = 0x01 , NGF_BUFFER_USAGE_XFER_DST = 0x02 , NGF_BUFFER_USAGE_UNIFORM_BUFFER = 0x04 , NGF_BUFFER_USAGE_INDEX_BUFFER = 0x08 , NGF_BUFFER_USAGE_VERTEX_BUFFER = 0x10 , NGF_BUFFER_USAGE_TEXEL_BUFFER = 0x20 , NGF_BUFFER_USAGE_STORAGE_BUFFER = 0x40 }

enum	ngf_present_mode { NGF_PRESENTATION_MODE_FIFO , NGF_PRESENTATION_MODE_IMMEDIATE }

Functions
uintptr_t	ngf_get_mtl_image_handle (ngf_image image)

uintptr_t	ngf_get_mtl_buffer_handle (ngf_buffer buffer)

uintptr_t	ngf_get_mtl_sampler_handle (ngf_sampler sampler)

uintptr_t	ngf_get_mtl_cmd_buffer_handle (ngf_cmd_buffer cmd_buffer)

uintptr_t	ngf_get_mtl_render_encoder_handle (ngf_render_encoder render_encoder)

uintptr_t	ngf_get_mtl_xfer_encoder_handle (ngf_xfer_encoder xfer_encoder)

uintptr_t	ngf_get_mtl_compute_encoder_handle (ngf_compute_encoder compute_encoder)

uintptr_t	ngf_get_vk_image_handle (ngf_image image)

uintptr_t	ngf_get_vk_buffer_handle (ngf_buffer buffer)

uintptr_t	ngf_get_vk_cmd_buffer_handle (ngf_cmd_buffer cmd_buffer)

uintptr_t	ngf_get_vk_sampler_handle (ngf_sampler sampler)

ngf_error	ngf_get_device_list (const ngf_device *devices, uint32_t ndevices)

ngf_error	ngf_initialize (const ngf_init_info *init_info)

ngf_error	ngf_create_context (const ngf_context_info info, ngf_context result)

void	ngf_destroy_context (ngf_context ctx)

ngf_error	ngf_resize_context (ngf_context ctx, uint32_t new_width, uint32_t new_height)

ngf_error	ngf_set_context (ngf_context ctx)

ngf_context	ngf_get_context ()

ngf_error	ngf_begin_frame (ngf_frame_token *token)

ngf_error	ngf_end_frame (ngf_frame_token token)

const ngf_device_capabilities *	ngf_get_device_capabilities (void)

ngf_error	ngf_create_shader_stage (const ngf_shader_stage_info info, ngf_shader_stage result)

void	ngf_destroy_shader_stage (ngf_shader_stage stage)

ngf_error	ngf_create_graphics_pipeline (const ngf_graphics_pipeline_info info, ngf_graphics_pipeline result)

void	ngf_destroy_graphics_pipeline (ngf_graphics_pipeline pipeline)

ngf_error	ngf_create_compute_pipeline (const ngf_compute_pipeline_info info, ngf_compute_pipeline result)

void	ngf_destroy_compute_pipeline (ngf_compute_pipeline pipeline)

ngf_error	ngf_create_image (const ngf_image_info info, ngf_image result)

void	ngf_destroy_image (ngf_image image)

ngf_error	ngf_create_sampler (const ngf_sampler_info info, ngf_sampler result)

void	ngf_destroy_sampler (ngf_sampler sampler)

ngf_error	ngf_create_render_target (const ngf_render_target_info info, ngf_render_target result)

void	ngf_destroy_render_target (ngf_render_target rendertarget)

ngf_render_target	ngf_default_render_target ()

const ngf_attachment_descriptions *	ngf_default_render_target_attachment_descs ()

ngf_error	ngf_create_buffer (const ngf_buffer_info info, ngf_buffer result)

void	ngf_destroy_buffer (ngf_buffer buffer)

void *	ngf_buffer_map_range (ngf_buffer buf, size_t offset, size_t size)

void	ngf_buffer_flush_range (ngf_buffer buf, size_t offset, size_t size)

void	ngf_buffer_unmap (ngf_buffer buf)

ngf_error	ngf_create_texel_buffer_view (const ngf_texel_buffer_view_info info, ngf_texel_buffer_view result)

void	ngf_destroy_texel_buffer_view (ngf_texel_buffer_view buf_view)

void	ngf_finish (void)

ngf_error	ngf_create_cmd_buffer (const ngf_cmd_buffer_info info, ngf_cmd_buffer result)

void	ngf_destroy_cmd_buffer (ngf_cmd_buffer buffer)

ngf_error	ngf_start_cmd_buffer (ngf_cmd_buffer buf, ngf_frame_token token)

ngf_error	ngf_submit_cmd_buffers (uint32_t nbuffers, ngf_cmd_buffer *bufs)

ngf_error	ngf_cmd_begin_render_pass (ngf_cmd_buffer buf, const ngf_render_pass_info pass_info, ngf_render_encoder enc)

ngf_error	ngf_cmd_begin_render_pass_simple (ngf_cmd_buffer buf, ngf_render_target rt, float clear_color_r, float clear_color_g, float clear_color_b, float clear_color_a, float clear_depth, uint32_t clear_stencil, ngf_render_encoder *enc)

ngf_error	ngf_cmd_end_render_pass (ngf_render_encoder enc)

ngf_error	ngf_cmd_begin_xfer_pass (ngf_cmd_buffer buf, const ngf_xfer_pass_info pass_info, ngf_xfer_encoder enc)

ngf_error	ngf_cmd_end_xfer_pass (ngf_xfer_encoder enc)

ngf_error	ngf_cmd_begin_compute_pass (ngf_cmd_buffer buf, const ngf_compute_pass_info pass_info, ngf_compute_encoder enc)

ngf_error	ngf_cmd_end_compute_pass (ngf_compute_encoder enc)

void	ngf_cmd_bind_gfx_pipeline (ngf_render_encoder buf, ngf_graphics_pipeline pipeline)

void	ngf_cmd_bind_compute_pipeline (ngf_compute_encoder buf, ngf_compute_pipeline pipeline)

void	ngf_cmd_viewport (ngf_render_encoder buf, const ngf_irect2d *r)

void	ngf_cmd_scissor (ngf_render_encoder enc, const ngf_irect2d *r)

void	ngf_cmd_stencil_reference (ngf_render_encoder enc, uint32_t front, uint32_t back)

void	ngf_cmd_stencil_compare_mask (ngf_render_encoder enc, uint32_t front, uint32_t back)

void	ngf_cmd_stencil_write_mask (ngf_render_encoder enc, uint32_t front, uint32_t back)

void	ngf_cmd_bind_resources (ngf_render_encoder enc, const ngf_resource_bind_op *bind_operations, uint32_t nbind_operations)

void	ngf_cmd_bind_compute_resources (ngf_compute_encoder enc, const ngf_resource_bind_op *bind_operations, uint32_t nbind_operations)

void	ngf_cmd_bind_attrib_buffer (ngf_render_encoder enc, ngf_buffer vbuf, uint32_t binding, size_t offset)

void	ngf_cmd_bind_index_buffer (ngf_render_encoder enc, ngf_buffer idxbuf, size_t offset, ngf_type index_type)

void	ngf_cmd_draw (ngf_render_encoder enc, bool indexed, uint32_t first_element, uint32_t nelements, uint32_t ninstances)

void	ngf_cmd_dispatch (ngf_compute_encoder enc, uint32_t x_threadgroups, uint32_t y_threadgroups, uint32_t z_threadgroups)

void	ngf_cmd_copy_buffer (ngf_xfer_encoder enc, ngf_buffer src, ngf_buffer dst, size_t size, size_t src_offset, size_t dst_offset)

void	ngf_cmd_write_image (ngf_xfer_encoder enc, ngf_buffer src, ngf_image dst, const ngf_image_write *writes, uint32_t nwrites)

void	ngf_cmd_copy_image_to_buffer (ngf_xfer_encoder enc, const ngf_image_ref src, ngf_offset3d src_offset, ngf_extent3d src_extent, uint32_t nlayers, ngf_buffer dst, size_t dst_offset)

ngf_error	ngf_cmd_generate_mipmaps (ngf_xfer_encoder xfenc, ngf_image img)

void	ngf_cmd_begin_debug_group (ngf_cmd_buffer cmd_buffer, const char *name)

void	ngf_cmd_end_current_debug_group (ngf_cmd_buffer cmd_buffer)

void	ngf_renderdoc_capture_next_frame ()

void	ngf_renderdoc_capture_begin ()

void	ngf_renderdoc_capture_end ()

Macro Definition Documentation

◆ NGF_DEVICE_NAME_MAX_LENGTH

#define NGF_DEVICE_NAME_MAX_LENGTH (256u)

Maximum length of a device's name.

Typedef Documentation

◆ ngf_device_handle

typedef uint32_t ngf_device_handle

A handle that uniquely identifies a rendering device.

Note that the value of the handle corresponding to the same exact physical device may be different across different instances of the same client. In other words, if the client application shuts down, then starts up again, it may get different values for device handles than it did before. Therefore, device handles should not be persisted.

◆ ngf_frame_token

typedef uintptr_t ngf_frame_token

A token identifying a frame of rendering. See ngf_begin_frame and ngf_end_frame for details.

Enumeration Type Documentation

◆ ngf_attachment_load_op

enum ngf_attachment_load_op

Enumerates actions that can be performed on attachment "load" (at the start of a render pass).

Enumerator
NGF_LOAD_OP_DONTCARE	Don't care what happens.
NGF_LOAD_OP_KEEP	Preserve the prior contents of the attachment.
NGF_LOAD_OP_CLEAR	Clear the attachment.

◆ ngf_attachment_store_op

enum ngf_attachment_store_op

Enumerates actions that can be performed on attachment "store" (at the end of a render pass).

Enumerator
NGF_STORE_OP_DONTCARE	Don't care what happens. Use this if you don't plan on reading back the contents of the attachment in any shaders, or presenting it to screen.
NGF_STORE_OP_STORE	Use this if you plan on reading the contents of the attachment in any shaders or presenting it to screen. The contents of the attachment shall be written out to system memory.
NGF_STORE_OP_RESOLVE	Use this to resolve a multisampled color attachment to a corresponding resolve attachment.

◆ ngf_attachment_type

enum ngf_attachment_type

Enumerates render target attachment types.

Enumerator
NGF_ATTACHMENT_COLOR	For attachments containing color data.
NGF_ATTACHMENT_DEPTH	For attachments containing depth data.
NGF_ATTACHMENT_DEPTH_STENCIL	For attachments containing combined depth and stencil data.

◆ ngf_blend_factor

enum ngf_blend_factor

Factors that can be used for source and destination values during the blend operation. The factor can be thought See ngf_blend_info for details.

Enumerator
NGF_BLEND_FACTOR_ZERO	If used as a blend factor for color: sets each color component to 0; if used as a blend factor for alpha: sets alpha to 0.
NGF_BLEND_FACTOR_ONE	If used as a blend factor for color: leaves the color unchanged; if used as a blend factor for alpha: leaves the alpha value unchanged.
NGF_BLEND_FACTOR_SRC_COLOR	If used as a blend factor for color: multiplies each color component by the corresponding component of the "source" color value; if used as a blend factor for alpha: multiples the alpha value by the "source" alpha value.
NGF_BLEND_FACTOR_ONE_MINUS_SRC_COLOR	If used as a blend factor for color: multiplies each color component by one minus the corresponding component of the "source" color value; if used as a blend factor for alpha: multiples the alpha value by one minus the "source" alpha value.
NGF_BLEND_FACTOR_DST_COLOR	If used as a blend factor for color: multiplies each color component by the corresponding component of the "destination" color value; if used as a blend factor for alpha: multiples the alpha value by the "destination" alpha value.
NGF_BLEND_FACTOR_ONE_MINUS_DST_COLOR	If used as a blend factor for color: multiplies each color component by one minus the corresponding component of the "destination" color value; if used as a blend factor for alpha: multiples the alpha value by one minus the "destination" alpha value.
NGF_BLEND_FACTOR_SRC_ALPHA	If used as a blend factor for color: multiplies each color component by the "source" alpha value; if used as a blend factor for alpha: multiples the alpha value by the "source" alpha value.
NGF_BLEND_FACTOR_ONE_MINUS_SRC_ALPHA	If used as a blend factor for color: multiplies each color component by one minus the "source" alpha value; if used as a blend factor for alpha: multiples the alpha value by one minus the "source" alpha value.
NGF_BLEND_FACTOR_DST_ALPHA	If used as a blend factor for color: multiplies each color component by the "destination" alpha value; if used as a blend factor for alpha: multiples the alpha value by the "destination" alpha value.
NGF_BLEND_FACTOR_ONE_MINUS_DST_ALPHA	If used as a blend factor for color: multiplies each color component by one minus the "destination" alpha value; if used as a blend factor for alpha: multiples the alpha value by one minus the "destination" alpha value.
NGF_BLEND_FACTOR_CONSTANT_COLOR	If used as a blend factor for color: multiplies the red, green and blue components of the color by the 1st, 2nd and 3rd elements of ngf_graphics_pipeline_info::blend_consts respectively; if used as a blend factor for alpha: multiplies the alpha value by the 4th component of ngf_graphics_pipeline_info::blend_consts.
NGF_BLEND_FACTOR_ONE_MINUS_CONSTANT_COLOR	If used as a blend factor for color: multiplies the red, green and blue components of the color by one minus the 1st, 2nd and 3rd elements of ngf_graphics_pipeline_info::blend_consts respectively; if used as a blend factor for alpha: multiplies the alpha value by one minus the 4th component of ngf_graphics_pipeline_info::blend_consts.
NGF_BLEND_FACTOR_CONSTANT_ALPHA	If used as a blend factor for color: multiplies the components of the color by the 4th element of ngf_graphics_pipeline_info::blend_consts; if used as a blend factor for alpha: multiplies the alpha value by the 4th component of ngf_graphics_pipeline_info::blend_consts.
NGF_BLEND_FACTOR_ONE_MINUS_CONSTANT_ALPHA	If used as a blend factor for color: multiplies the components of the color by one minus the 4th element of ngf_graphics_pipeline_info::blend_consts; if used as a blend factor for alpha: multiplies the alpha value by one minus the 4th component of ngf_graphics_pipeline_info::blend_consts.

◆ ngf_blend_op

enum ngf_blend_op

Operations that can be performed to blend the values computed by the fragment stage (source values, denoted S in the member documentation) with values already present in the target color attachment of the framebuffer (destination values, denoted D in the member documentation).

The factors (ngf_blend_factor) for the source and destination values are denoted as Fs and Fd respectively in the member documentation below.

Enumerator
NGF_BLEND_OP_ADD	The result of the blend operation shall be `SFs + DFd`
NGF_BLEND_OP_SUB	The result of the blend operation shall be `SFs - DFd`
NGF_BLEND_OP_REV_SUB	The result of the blend operation shall be `DFd - SFs`
NGF_BLEND_OP_MIN	The result of the blend operation shall be `min(S, D)`
NGF_BLEND_OP_MAX	The result of the blend operation shall be `max(S, D)`

◆ ngf_buffer_storage_type

enum ngf_buffer_storage_type

Enumerates types of memory backing a buffer object.

Enumerator
NGF_BUFFER_STORAGE_HOST_READABLE	Memory that can be read by the host.
NGF_BUFFER_STORAGE_HOST_WRITEABLE	Memory that can be written to by the host.
NGF_BUFFER_STORAGE_HOST_READABLE_WRITEABLE	Memory that can be both read from and written to by the host.
NGF_BUFFER_STORAGE_DEVICE_LOCAL	Memory that is local to the device (GPU). Normally, this type of storage isn't accessible directly from the host and the contents of a buffer backed by this type of memory can only be modified by executing a ngf_cmd_copy_buffer.
NGF_BUFFER_STORAGE_DEVICE_LOCAL_HOST_WRITEABLE	Memory that is both local to the device (GPU) and mappable/writeable directly from host. This type of storage is available only when the capability ngf_device_capabilities::device_local_memory_is_host_visible is supported. Examples of systems that may support this type of storage are iGPUs or discrete GPUs with ReBAR enabled. Using this type of backing storage allows the host to write bytes directly into the mapped memory, obviating the need for staging buffers in some cases.
NGF_BUFFER_STORAGE_DEVICE_LOCAL_HOST_READABLE_WRITEABLE	Same as NGF_BUFFER_STORAGE_DEVICE_LOCAL_HOST_WRITEABALE, but additionally allows the host to read directly from mapped memory.

◆ ngf_buffer_usage

enum ngf_buffer_usage

Enumerates the buffer usage flags. A valid buffer usage mask may be formed by combining a subset of these values with a bitwise OR operator.

Enumerator
NGF_BUFFER_USAGE_XFER_SRC	The buffer may be used as a source for transfer operations.
NGF_BUFFER_USAGE_XFER_DST	The buffer may be used as a destination for transfer operations.
NGF_BUFFER_USAGE_UNIFORM_BUFFER	The buffer may be bound as a uniform buffer.
NGF_BUFFER_USAGE_INDEX_BUFFER	The buffer may be used as the source of index data for indexed draws.
NGF_BUFFER_USAGE_VERTEX_BUFFER	The buffer may be used as a source of vertex attribute data.
NGF_BUFFER_USAGE_TEXEL_BUFFER	The buffer may be bound as a uniform texel buffer.
NGF_BUFFER_USAGE_STORAGE_BUFFER	The buffer may be bound as a storage buffer.

◆ ngf_compare_op

enum ngf_compare_op

Compare operations used in depth and stencil tests.

Enumerator
NGF_COMPARE_OP_NEVER	Comparison test never succeeds.
NGF_COMPARE_OP_LESS	Comparison test succeeds if A < B.
NGF_COMPARE_OP_LEQUAL	Comparison test succeeds if A <= B.
NGF_COMPARE_OP_EQUAL	Comparison test succeeds if A == B.
NGF_COMPARE_OP_GEQUAL	Comparison test succeeds if A >= B.
NGF_COMPARE_OP_GREATER	Comparison test succeeds if A > B.
NGF_COMPARE_OP_NEQUAL	Comparison test succeeds if A != B.
NGF_COMPARE_OP_ALWAYS	Comparison test always succeeds.

◆ ngf_cubemap_face

enum ngf_cubemap_face

Members of this enumeration are used to refer to the different faces of a cubemap.

◆ ngf_cull_mode

enum ngf_cull_mode

Enumerates polygon culling strategies. See also ngf_rasterization_info.

Enumerator
NGF_CULL_MODE_BACK	Cull back-facing polygons.
NGF_CULL_MODE_FRONT	Cull front-facing polygons.
NGF_CULL_MODE_FRONT_AND_BACK	Cull all polygons.
NGF_CULL_MODE_NONE	Do not cull anything.

◆ ngf_descriptor_type

enum ngf_descriptor_type

Available descriptor types. Not that some back-ends may not support all of the listed descriptor types.

Enumerator
NGF_DESCRIPTOR_UNIFORM_BUFFER	A uniform buffer, also known as a constant buffer, can be used to pass a small to medium sized chunk of data to the shader in a structured way.
NGF_DESCRIPTOR_IMAGE	An ngf_image.
NGF_DESCRIPTOR_SAMPLER	An ngf_sampler.
NGF_DESCRIPTOR_IMAGE_AND_SAMPLER	A combination of an image and sampler in a single object.
NGF_DESCRIPTOR_TEXEL_BUFFER	A texel buffer can be used to pass a large amount of unstructured data (i.e. a big array of `float4`s) to the shader.
NGF_DESCRIPTOR_STORAGE_BUFFER	A storage buffer is a large buffer that can be both read and written in shaders.

◆ ngf_device_performance_tier

enum ngf_device_performance_tier

Enumerates different types of rendering devices.

Enumerator
NGF_DEVICE_PERFORMANCE_TIER_HIGH	For high-performance devices, such as discrete GPU.
NGF_DEVICE_PERFORMANCE_TIER_LOW	For low-power integrated GPUs, software rendering, etc.
NGF_DEVICE_PERFORMANCE_TIER_UNKNOWN	The specific performance profile is unknown.

◆ ngf_diagnostic_log_verbosity

enum ngf_diagnostic_log_verbosity

Verbosity levels for the diagnostic message log.

Enumerator
NGF_DIAGNOSTICS_VERBOSITY_DEFAULT	Normal level, reports only severe errors.
NGF_DIAGNOSTICS_VERBOSITY_DETAILED	Recommended for debug builds, may induce performance overhead.

◆ ngf_diagnostic_message_type

enum ngf_diagnostic_message_type

Type of a diagnostic log entry.

Enumerator
NGF_DIAGNOSTIC_INFO	Informational message, not actionable.
NGF_DIAGNOSTIC_WARNING	Message warns of a potential issue with an API call.
NGF_DIAGNOSTIC_ERROR	Message provides details of an API call failure or a severe performance issue.

◆ ngf_error

enum ngf_error

Enumerates the error codes that nicegraf routines may return. See also Error Reporting.

Enumerator
NGF_ERROR_OK	No error, operation finished successfully.
NGF_ERROR_OUT_OF_MEM	Host memory allocation failed.
NGF_ERROR_OBJECT_CREATION_FAILED	A call to the backend API that was supposed to create an object failed.
NGF_ERROR_OUT_OF_BOUNDS	The operation would have resulted in an out of bounds access.
NGF_ERROR_INVALID_FORMAT	A format enumerator provided as part of an argument to the call is not valid in that context.
NGF_ERROR_INVALID_SIZE	A size passed as part of an argument to the call is either too large or too small.
NGF_ERROR_INVALID_ENUM	An enumerator passed as part of an argument to the call is not valid in that context.
NGF_ERROR_INVALID_OPERATION	The routine did not complete successfully.

◆ ngf_front_face_mode

enum ngf_front_face_mode

Enumerates possible vertex winding orders, which are used to decide which polygons are front- or back-facing. See also ngf_rasterization_info.

Enumerator
NGF_FRONT_FACE_COUNTER_CLOCKWISE	Polygons with vertices in counter-clockwise order are considered front-facing.
NGF_FRONT_FACE_CLOCKWISE	Polygons with vertices in clockwise order are considered front-facing.

◆ ngf_image_format

enum ngf_image_format

Image formats.

Some backends may not support all of those. Using an sRGB format in a color attachment or swapchain image means that all color values output by the fragment stage are interpreted as being in linear color space, and an appropriate transfer function is applied to them to covert them to the sRGB colorspace before writing them to the target. Using an sRGB format in a sampled image means that all color values stored in the image are interpreted to be in the sRGB color space, and all read operations automatically apply a transfer function to convert the values from sRGB to linear color space.

◆ ngf_image_type

enum ngf_image_type

Enumerates the possible image types.

Enumerator
NGF_IMAGE_TYPE_IMAGE_2D	Two-dimensional image.
NGF_IMAGE_TYPE_IMAGE_3D	Three-dimensional image.
NGF_IMAGE_TYPE_CUBE	Cubemap.

◆ ngf_image_usage

enum ngf_image_usage

Image usage flags.

A valid image usage mask may be formed by combining one or more of these values with a bitwise OR operator.

Enumerator
NGF_IMAGE_USAGE_SAMPLE_FROM	The image may be read from in a shader.
NGF_IMAGE_USAGE_ATTACHMENT	The image may be used as an attachment for a render target.
NGF_IMAGE_USAGE_XFER_DST	The image may be used as a destination for a transfer operation.
NGF_IMAGE_USAGE_MIPMAP_GENERATION	Mipmaps may be generated for the image with ngf_cmd_generate_mipmaps.
NGF_IMAGE_USAGE_STORAGE	The image may be read or written to by a shader.
NGF_IMAGE_USAGE_XFER_SRC	The image may be used as a source for a transfer operation.

◆ ngf_polygon_mode

enum ngf_polygon_mode

Enumerates ways to draw polygons. See also ngf_rasterization_info.

Enumerator
NGF_POLYGON_MODE_FILL	Fill the entire polyoon.
NGF_POLYGON_MODE_LINE	Outline only.
NGF_POLYGON_MODE_POINT	Vertices only.

◆ ngf_present_mode

enum ngf_present_mode

Enumerates possible presentation modes. "Presentation mode" refers to the particular way the CPU, GPU and the presentation engine interact. Some of the listed presentation modes may not be supported on various backend, hardware or OS combinations. If an unsupported mode is requested, nicegraf silently falls back onto NGF_PRESENTATION_MODE_FIFO.

Enumerator
NGF_PRESENTATION_MODE_FIFO	This is the only presentation mode that is guaranteed to be supported. In this mode, the presentation requests are queued internally, and the presentation engine waits for the vertical blanking signal to present the image at the front of the queue. This mode guarantees no frame tearing.
NGF_PRESENTATION_MODE_IMMEDIATE	In this mode, the presentation engine does not wait for the vertical blanking signal, instead presenting an image immediately. This mode results in lower latency but may induce frame tearing. It is not recommended to use this mode on mobile targets.

◆ ngf_primitive_topology

enum ngf_primitive_topology

Enumerates the available primitive topologies (ways to group vertices into primitives).

Enumerator
NGF_PRIMITIVE_TOPOLOGY_TRIANGLE_LIST	A list of separate triangles - each three vertices define a separate triangle.
NGF_PRIMITIVE_TOPOLOGY_TRIANGLE_STRIP	A list of connected triangles, with consecutive triangles sharing an edge like so: o---------o-----------o \ / \ / \ / \ / ... o----------o
NGF_PRIMITIVE_TOPOLOGY_LINE_LIST	A list of separate lines. Each two vertices define a separate line.
NGF_PRIMITIVE_TOPOLOGY_LINE_STRIP	A list of connected lines. The end of a line is the beginning of the next line in the list.

◆ ngf_sample_count

enum ngf_sample_count

Specifies the number of MSAA samples.

◆ ngf_sampler_filter

enum ngf_sampler_filter

Enumerates filters for texture lookups.

Enumerator

NGF_FILTER_NEAREST

When used as the minification (ngf_sampler_info::min_filter) or magnification (ngf_sampler_info::mag_filter) filter, the result of the filtering operation shall be the value of the texel whose center is nearest to the sample.

When used as ngf_sampler_info::mip_filter, makes the selected mip level snap to the one that is closest to the requested mip level value.

NGF_FILTER_LINEAR

When used as the minification (ngf_sampler_info::min_filter) or magnification (ngf_sampler_info::mag_filter) filter, the result of the filtering operation shall be linearly interpolated from the values of 4 (in case of 2D images) or 8 (in case of 3D images) texels whose centers are nearest to the sample.

When used as ngf_sampler_info::mip_filter, linearly blends the values from two mip levels closest to the requested mip level value.

◆ ngf_sampler_wrap_mode

enum ngf_sampler_wrap_mode

Enumerates strategies for dealing with sampling an image out-of-bounds.

Enumerator
NGF_WRAP_MODE_CLAMP_TO_EDGE	Clamp the texel value to what's at the edge of the image.
NGF_WRAP_MODE_REPEAT	Repeat the image contents.
NGF_WRAP_MODE_MIRRORED_REPEAT	Repeat the image contents, mirrored.

◆ ngf_stage_type

enum ngf_stage_type

Shader stage types. Note that some back-ends might not support all of these.

Enumerator
NGF_STAGE_VERTEX	Indicates the vertex processing stage.
NGF_STAGE_FRAGMENT	Indicates the fragment processing stage.
NGF_STAGE_COMPUTE	Indicates the compute stage.

◆ ngf_stencil_op

enum ngf_stencil_op

Operations that can be performed on stencil buffer.

Enumerator
NGF_STENCIL_OP_KEEP	Don't touch.
NGF_STENCIL_OP_ZERO	Set to 0.
NGF_STENCIL_OP_REPLACE	Replace with reference value.
NGF_STENCIL_OP_INCR_CLAMP	Increment, clamping to max value.
NGF_STENCIL_OP_INCR_WRAP	Increment, wrapping to 0.
NGF_STENCIL_OP_DECR_CLAMP	Decrement, clamping to 0.
NGF_STENCIL_OP_DECR_WRAP	Decrement, wrapping to max value.
NGF_STENCIL_OP_INVERT	Bitwise invert.

◆ ngf_type

enum ngf_type

Enumerates the available vertex attribute component types.

Enumerator
NGF_TYPE_INT8	Signed 8-bit integer.
NGF_TYPE_UINT8	Unsigned 8-bit integer.
NGF_TYPE_INT16	Signed 16-bit integer.
NGF_TYPE_UINT16	Unsigned 16-bit integer.
NGF_TYPE_INT32	Signed 32-bit integer.
NGF_TYPE_UINT32	Unsigned 32-bit integer.
NGF_TYPE_FLOAT	32-bit floating point number.
NGF_TYPE_HALF_FLOAT	16-bit floating point number.
NGF_TYPE_DOUBLE	Double-precision floating point number.

Function Documentation

◆ ngf_begin_frame()

ngf_error ngf_begin_frame ( ngf_frame_token * token )

Begin a frame of rendering.

This function starts a frame of rendering in the calling thread's current context. It generates a special token associated with the frame, which is required for recording command buffers (see ngf_start_cmd_buffer).

Parameters

token A pointer to a ngf_frame_token. The generated frame token shall be returned here.

◆ ngf_buffer_flush_range()

void ngf_buffer_flush_range	(	ngf_buffer	buf,
		size_t	offset,
		size_t	size )

Ensures that any writes performed by the CPU into the mapped range are be visible to subsequently submitted rendering commands executed by the rendering device.

Parameters

ptr	The handle to the buffer that needs to be flushed.
offset	The offset, relative to the start of the mapped range, at which the flushed region starts, in bytes.
size	The size of the flushed region, in bytes.

◆ ngf_buffer_map_range()

void * ngf_buffer_map_range	(	ngf_buffer	buf,
		size_t	offset,
		size_t	size )

Maps a region of a given buffer to host memory.

It is an error to bind a buffer that is currently mapped using any command. If a buffer that needs to be bound is mapped, first call ngf_buffer_flush_range to ensure any new data in the mapped range becomes visible to the subsequent commands, then call ngf_buffer_unmap. Writing into any region that could be in use by previously submitted commands results in undefined behavior.

Parameters

buf	The handle to the buffer to be mapped.
offset	The offset at which the mapped region starts, in bytes. It must satisfy platform-specific alignment requirements. See, for example, ngf_device_capabilities::uniform_buffer_offset_alignment and ngf_device_capabilities::texel_buffer_offet_alignment.
size	The size of the mapped region, in bytes.
flags	A combination of flags from ngf_buffer_map_flags.

Returns: A pointer to the mapped memory, or NULL if the buffer could not be mapped.

◆ ngf_buffer_unmap()

void ngf_buffer_unmap ( ngf_buffer buf )

Unmaps a previously mapped buffer.

If multiple regions were mapped, all of them are unmapped. Any pointers returned by prior calls to ngf_buffer_map_range are invalidated.

Parameters

buf	The buffer that needs to be unmapped.

◆ ngf_cmd_begin_compute_pass()

ngf_error ngf_cmd_begin_compute_pass	(	ngf_cmd_buffer	buf,
		const ngf_compute_pass_info *	pass_info,
		ngf_compute_encoder *	enc )

Begins a compute pass.

Parameters

buf	The handle of the command buffer to operate on. Must be in the "ready" state, will be transitioned to the "recording" state.
pass_info	A pointer to ngf_compute_pass_info specifying details about this compute pass.
enc	Pointer to memory where a handle to a transfer encoder shall be returned. All commands associated with the transfer pass must be recorded using that encoder.

◆ ngf_cmd_begin_debug_group()

void ngf_cmd_begin_debug_group	(	ngf_cmd_buffer	cmd_buffer,
		const char *	name )

Records the beginning of a "debug group" into the given command buffer.

Debug groups are a way to group together related commands for easier vieweing in graphics debugging tools such as RenderDoc. They do not have any other functional impact. Debug groups have to be enabled during initialization. See ngf_diagnostic_info.

This command records a marker into the given command buffer indicating that the subsequent commands recorded into the buffer pertain to a certain debug group.

Parameters

cmd_buffer	the command buffer to record the debug group start marker into.
name	The name of the debug group that will appear in debugging tools.

◆ ngf_cmd_begin_render_pass()

ngf_error ngf_cmd_begin_render_pass	(	ngf_cmd_buffer	buf,
		const ngf_render_pass_info *	pass_info,
		ngf_render_encoder *	enc )

Begins a new render pass.

A render pass can be thought of as a sequence of rendering commands associated with a particular render target. At the start of the pass, an "load operation" is performed for each attachment. The application code may specify exactly what load operations to perform for each individual attachment. After that, all the rendering commands are executed. Finally, at the end of the pass, a "store operation" is performed for each attachment. Again, the application code may specify exactly which store operations to perform for each individual attachment.

Parameters

buf	The command buffer to operate on. Must be in the "ready" state, shall be transitioned to the "recording" state.
pass_info	Specifies the renderpass parameters, such as load and store operations.
enc	Pointer to memory into which a handle to a render encoder will be returned. All the commands associated with the renderpass must be recorder using that encoder.

◆ ngf_cmd_begin_render_pass_simple()

ngf_error ngf_cmd_begin_render_pass_simple	(	ngf_cmd_buffer	buf,
		ngf_render_target	rt,
		float	clear_color_r,
		float	clear_color_g,
		float	clear_color_b,
		float	clear_color_a,
		float	clear_depth,
		uint32_t	clear_stencil,
		ngf_render_encoder *	enc )

Similar to ngf_cmd_begin_render_pass, but with some choices pre-made:

All color attachments of the render target are cleared to the specified color.
Depth and stencil attachments are cleared to the specified respective values (if they are present).
The store action for any attachment that is not marked as "sampled from" (see ngf_attachment_description::is_sampled), is set to NGF_STORE_OP_DONTCARE.

The store action for attachments marked as "sampled from", is set to NGF_STORE_OP_STORE.

Parameters

buf	The command buffer to operate on.
rt	The handle to the render target to use for the pass.
clear_color_r	The red component of the clear color to be used on color attachments. Ignored for attachments that don't have that channel.
clear_color_g	The red component of the clear color to be used on color attachments. Ignored for attachments that don't have that channel.
clear_color_b	The red component of the clear color to be used on color attachments. Ignored for attachments that don't have that channel.
clear_color_a	The red component of the clear color to be used on color attachments. Ignored for attachments that don't have that channel.
clear_depth	The value to clear the depth attachment to (if it is present).
clear_stencil	The value to clear the stencil attachment to (if it is present).

◆ ngf_cmd_begin_xfer_pass()

ngf_error ngf_cmd_begin_xfer_pass	(	ngf_cmd_buffer	buf,
		const ngf_xfer_pass_info *	pass_info,
		ngf_xfer_encoder *	enc )

Begins a transfer pass.

A transfer pass is a sequence of commands that copy data.

Parameters

buf	The handle to the command buffer to operate on. Must be in the "ready" state, will be transitioned to the "recording" state.
pass_info	Pointer to ngf_xfer_pass_info specifying details about this transfer pass.
enc	Pointer to memory where a handle to a transfer encoder shall be returned. All commands associated with the transfer pass must be recorded using that encoder.

◆ ngf_cmd_bind_attrib_buffer()

void ngf_cmd_bind_attrib_buffer	(	ngf_render_encoder	enc,
		ngf_buffer	vbuf,
		uint32_t	binding,
		size_t	offset )

Binds a vertex attribute buffer to be used in the next draw.

Parameters

enc	The handle to the render encoder.
vbuf	The handle to the vertex buffer to bind.
binding	The vertex buffer binding ID to bind the buffer to.
offset	The offset (in bytes) to bind at.

◆ ngf_cmd_bind_compute_pipeline()

void ngf_cmd_bind_compute_pipeline	(	ngf_compute_encoder	buf,
		ngf_compute_pipeline	pipeline )

Binds a compute pipeline.

◆ ngf_cmd_bind_compute_resources()

void ngf_cmd_bind_compute_resources	(	ngf_compute_encoder	enc,
		const ngf_resource_bind_op *	bind_operations,
		uint32_t	nbind_operations )

Bind resources for shaders to access. See ngf_resource_bind_op for more information.

Parameters

enc	The handle to the render encoder object to record the command into.
bind_operations	A pointer to a contiguous array of ngf_resource_bind_op objects.
nbinds	The number of elements in the array pointed to by bind_operations.

◆ ngf_cmd_bind_gfx_pipeline()

void ngf_cmd_bind_gfx_pipeline	(	ngf_render_encoder	buf,
		ngf_graphics_pipeline	pipeline )

Binds a graphics pipeline.

◆ ngf_cmd_bind_index_buffer()

void ngf_cmd_bind_index_buffer	(	ngf_render_encoder	enc,
		ngf_buffer	idxbuf,
		size_t	offset,
		ngf_type	index_type )

Binds an index buffer to be used in the next draw.

Parameters

enc	The handle to the render encoder.
idxbuf	The handle to the index buffer to bind.
offset	The offset at which to bind the buffer (in bytes).
index_type	The type of values that are stored in the index buffer. Can be either NGF_TYPE_UINT32 or NGF_TYPE_UINT16.

◆ ngf_cmd_bind_resources()

void ngf_cmd_bind_resources	(	ngf_render_encoder	enc,
		const ngf_resource_bind_op *	bind_operations,
		uint32_t	nbind_operations )

Bind resources for shaders to access. See ngf_resource_bind_op for more information.

Parameters

enc	The handle to the render encoder object to record the command into.
bind_operations	A pointer to a contiguous array of ngf_resource_bind_op objects.
nbinds	The number of elements in the array pointed to by bind_operations.

◆ ngf_cmd_copy_buffer()

void ngf_cmd_copy_buffer	(	ngf_xfer_encoder	enc,
		ngf_buffer	src,
		ngf_buffer	dst,
		size_t	size,
		size_t	src_offset,
		size_t	dst_offset )

Copies data between buffers.

Parameters

enc	The handle to the transfer encoder object to record the command into.
src	The handle to the buffer object to be copied from.
dst	The handle to the buffer object to be copied into.
size	The size of the copied region, in bytes.
src_offset	The offset in the source buffer to copy from.
dst_offset	The offset in the destination buffer to copy into.

◆ ngf_cmd_copy_image_to_buffer()

void ngf_cmd_copy_image_to_buffer	(	ngf_xfer_encoder	enc,
		const ngf_image_ref	src,
		ngf_offset3d	src_offset,
		ngf_extent3d	src_extent,
		uint32_t	nlayers,
		ngf_buffer	dst,
		size_t	dst_offset )

Copies data from an image to a buffer.

Parameters

enc	The handle to the transfer encoder object to record the command into.
src	Reference to the image region that shall be copied from.
src_offset	The offset in the source image from which to start copying.
extent	The size of the region in the source mip level being copied.
nlayers	The number of layers to be copied.
dst	Reference to the image region that shall be written to.
dst_offset	Offset within the target mip level to write to (in texels).

◆ ngf_cmd_dispatch()

void ngf_cmd_dispatch	(	ngf_compute_encoder	enc,
		uint32_t	x_threadgroups,
		uint32_t	y_threadgroups,
		uint32_t	z_threadgroups )

Encodes a compute shader dispatch. This command is not supported by draw-type buffers.

Parameters

enc	The encoder to record the command into.
x_threadgroups	Number of threadgroups along the X dimension of the grid.
y_threadgroups	Number of threadgroups along the Y dimension of the grid.
z_threadgroups	Number of threadgroups along the Z dimension of the grid.

◆ ngf_cmd_draw()

void ngf_cmd_draw	(	ngf_render_encoder	enc,
		bool	indexed,
		uint32_t	first_element,
		uint32_t	nelements,
		uint32_t	ninstances )

Executes a draw. This command is not supported by compute-type command buffers.

Parameters

enc	The render encoder to record the command into.
indexed	Indicates whether the draw uses an index buffer or not.
first_element	Offset of the first vertex.
nelements	Number of vertices to process.
ninstance	Number of instances (use `1` for regular non-instanced draws).

◆ ngf_cmd_end_compute_pass()

ngf_error ngf_cmd_end_compute_pass ( ngf_compute_encoder enc )

Ends a compute pass.

Disposes of the given compute cmd encoder, transitioning its corresponding command buffer to the "ready" state.

◆ ngf_cmd_end_current_debug_group()

void ngf_cmd_end_current_debug_group ( ngf_cmd_buffer cmd_buffer )

Records the end of a "debug group" into the given command buffer.

This command records a marker into the given command buffer that terminates the current debug group if there is one. Subsequent commands recorded into the buffer shall not pertain to any debug group until a new one is started.

Parameters

cmd_buffer The command buffer to record the debug group end marker into.

◆ ngf_cmd_end_render_pass()

ngf_error ngf_cmd_end_render_pass ( ngf_render_encoder enc )

Ends a render pass.

Disposes of the given render command encoder, transitioning its corresponding command buffer to the "ready" state.

◆ ngf_cmd_end_xfer_pass()

ngf_error ngf_cmd_end_xfer_pass ( ngf_xfer_encoder enc )

Ends a transfer pass.

Disposes of the given transfer cmd encoder, transitioning its corresponding command buffer to the "ready" state.

◆ ngf_cmd_generate_mipmaps()

ngf_error ngf_cmd_generate_mipmaps	(	ngf_xfer_encoder	xfenc,
		ngf_image	img )

Generates mipmaps automatically.

Mipmaps are generated for all layers of the given image, from level 1 to the the maximum level specified when creating the image, using the data from the preceding level as the source. Level 0 of each layer is expected to be populated by the application code prior to calling this function.

Parameters

xfenc	A transfer command encoder.
img	The handle to the image to operate on.

◆ ngf_cmd_scissor()

void ngf_cmd_scissor	(	ngf_render_encoder	enc,
		const ngf_irect2d *	r )

Sets the scissor region to be used in the subsequent rendering commands. The scissor defines a region of the framebuffer that can be affected by the rendering commands. Any pixels outside of that region are not written to.

◆ ngf_cmd_stencil_compare_mask()

void ngf_cmd_stencil_compare_mask	(	ngf_render_encoder	enc,
		uint32_t	front,
		uint32_t	back )

Set the compare mask to be used in stencil tests.

◆ ngf_cmd_stencil_reference()

void ngf_cmd_stencil_reference	(	ngf_render_encoder	enc,
		uint32_t	front,
		uint32_t	back )

Sets the reference value to be used in stencil tests.

◆ ngf_cmd_stencil_write_mask()

void ngf_cmd_stencil_write_mask	(	ngf_render_encoder	enc,
		uint32_t	front,
		uint32_t	back )

Sets the stencil write mask.

◆ ngf_cmd_viewport()

void ngf_cmd_viewport	(	ngf_render_encoder	buf,
		const ngf_irect2d *	r )

Sets the viewport to be used in subsequent rendering commands. The viewport defines a region of the destination framebuffer that the resulting rendering is scaled to fit into.

◆ ngf_cmd_write_image()

void ngf_cmd_write_image	(	ngf_xfer_encoder	enc,
		ngf_buffer	src,
		ngf_image	dst,
		const ngf_image_write *	writes,
		uint32_t	nwrites )

Copies data from a buffer into an image.

For non-compressed formats, the source data is assumed to be arranged in a simple linear layout. Cubemap faces and layers are assumed to be stored successively in the source buffer, from first to last. For each layer, the first texel corresponds to the lower left corner of the image, and the subsequent texels progress from left to right, through the remainder of the bottom row, and from then on, through higher rows.

Parameters

enc	The handle to the transfer encoder object to record the command into.
src	The handle to the buffer object to be copied from.
dst	The image that the data from the buffer shall be written into.
writes	A pointer to an array of ngf_image_write objects, each describing a write to a mip level of the image to be written.
nwrites	Number of objects in the `writes` array.

◆ ngf_create_buffer()

ngf_error ngf_create_buffer	(	const ngf_buffer_info *	info,
		ngf_buffer *	result )

Creates a new buffer object.

Parameters

info	Information required to construct the buffer object.
result	Pointer to where the handle to the newly created object will be written to.

◆ ngf_create_cmd_buffer()

ngf_error ngf_create_cmd_buffer	(	const ngf_cmd_buffer_info *	info,
		ngf_cmd_buffer *	result )

Creates a new command buffer.

Parameters

info	The information required to create the new command buffer.
result	Pointer to where the handle to the newly created command buffer will be returned.

◆ ngf_create_compute_pipeline()

ngf_error ngf_create_compute_pipeline	(	const ngf_compute_pipeline_info *	info,
		ngf_compute_pipeline *	result )

Creates a new compute pipeline object.

Parameters

info	Information required to construct the compute pipeline object.
result	Pointer to where the handle to the newly created object will be returned.

◆ ngf_create_context()

ngf_error ngf_create_context	(	const ngf_context_info *	info,
		ngf_context *	result )

Creates a new ngf_context.

Parameters

info	The context configuration.

◆ ngf_create_graphics_pipeline()

ngf_error ngf_create_graphics_pipeline	(	const ngf_graphics_pipeline_info *	info,
		ngf_graphics_pipeline *	result )

Creates a new graphics pipeline object.

Parameters

info	Information required to construct the graphics pipeline object.
result	Pointer to where the handle to the newly created object will be returned.

◆ ngf_create_image()

ngf_error ngf_create_image	(	const ngf_image_info *	info,
		ngf_image *	result )

Creates a new image object.

Parameters

info	Information required to construct the image object.
result	Pointer to where the handle to the newly created object will be returned.

◆ ngf_create_render_target()

ngf_error ngf_create_render_target	(	const ngf_render_target_info *	info,
		ngf_render_target *	result )

Create a new rendertarget object.

Parameters

info	Information required to construct the rendertarget object.
result	Pointer to where the handle to the newly created object will be returned.

◆ ngf_create_sampler()

ngf_error ngf_create_sampler	(	const ngf_sampler_info *	info,
		ngf_sampler *	result )

Creates a new sampler object.

Parameters

info	Information required to construct the sampler object.
result	Pointer to where the handle to the newly created object will be returned.

◆ ngf_create_shader_stage()

ngf_error ngf_create_shader_stage	(	const ngf_shader_stage_info *	info,
		ngf_shader_stage *	result )

Creates a new shader stage object.

Parameters

stages	Information required to construct the shader stage object.
result	Pointer to where the handle to the newly created object will be returned.

◆ ngf_create_texel_buffer_view()

ngf_error ngf_create_texel_buffer_view	(	const ngf_texel_buffer_view_info *	info,
		ngf_texel_buffer_view *	result )

Creates a new texel buffer view object.

Parameters

info	Information required to construct the texel buffer view object.
result	Pointer to where the handle to the newly created object will be written to.

◆ ngf_default_render_target()

ngf_render_target ngf_default_render_target ( )

Returns the handle to the ngf_render_target associated with the the current context's swapchain (aka the default render target). If the current context does not have a swapchain, the result shall be null. Otherwise, it shall be a render target that has a color attachment associated with the context's swapchain. If the swapchain was created with an accompanying depth buffer, the render target shall have an attachment for that as well.

The caller should not attempt to destroy the returned render target. It shall be destroyed automatically, together with the parent context.

◆ ngf_default_render_target_attachment_descs()

const ngf_attachment_descriptions * ngf_default_render_target_attachment_descs ( )

Returns the attachment descriptions for the default render target. The caller should not attempt to free the returned pointer or modify the contents of the memory it points to.

◆ ngf_destroy_buffer()

void ngf_destroy_buffer ( ngf_buffer buffer )

Destroys the given buffer object.

Parameters

buffer The handle to the buffer object to be destroyed.

◆ ngf_destroy_cmd_buffer()

void ngf_destroy_cmd_buffer ( ngf_cmd_buffer buffer )

Destroys the given command buffer.

If there is any work submitted via the given command buffer still pending on the rendering device, it shall be executed asynchronously. Therefore, application code doesn't need to wait for the commands associated with the command buffer to finish before it can safely dispose of the command buffer.

Parameters

buffer The handle to the command buffer object to be destroyed.

◆ ngf_destroy_compute_pipeline()

void ngf_destroy_compute_pipeline ( ngf_compute_pipeline pipeline )

Destroys the given compute pipeline object.

Parameters

pipeline The handle to the pipeline object to be destroyed.

◆ ngf_destroy_context()

void ngf_destroy_context ( ngf_context ctx )

Destroys the given ngf_context.

Parameters

ctx	The context to destroy.

◆ ngf_destroy_graphics_pipeline()

void ngf_destroy_graphics_pipeline ( ngf_graphics_pipeline pipeline )

Destroys the given graphics pipeline object.

Parameters

pipeline The handle to the pipeline object to be destroyed.

◆ ngf_destroy_image()

void ngf_destroy_image ( ngf_image image )

Destroys the given image object.

Parameters

image The handle to the image object to be destroyed.

◆ ngf_destroy_render_target()

void ngf_destroy_render_target ( ngf_render_target rendertarget )

Destroys the given render target.

Parameters

rendertarget The handle to the rendertarget object to be destroyed.

◆ ngf_destroy_sampler()

void ngf_destroy_sampler ( ngf_sampler sampler )

Destroys the given sampler object.

Parameters

ssampler The handle to the sampler object to be destroyed.

◆ ngf_destroy_shader_stage()

void ngf_destroy_shader_stage ( ngf_shader_stage stage )

Destroys the given shader stage.

Parameters

stage The handle to the shader stage object to be destroyed.

◆ ngf_destroy_texel_buffer_view()

void ngf_destroy_texel_buffer_view ( ngf_texel_buffer_view buf_view )

Destroys the given texel buffer view object.

Parameters

buffer The handle to the texel buffer view object to be destroyed.

◆ ngf_end_frame()

ngf_error ngf_end_frame ( ngf_frame_token token )

End the current frame of rendering on the calling thread's context.

Parameters

token The frame token generated by the corresponding preceding call to ngf_begin_frame.

◆ ngf_finish()

void ngf_finish ( void )

Waits for all pending rendering commands to complete.

Do not use this function lightly. It is expensive because it introduces a sync point between the CPU and the rendering device.

◆ ngf_get_context()

ngf_context ngf_get_context ( )

Get the active nicegraf context associated with the calling thread.

Returns NULL if no context associated with the calling thread exists.

◆ ngf_get_device_capabilities()

const ngf_device_capabilities * ngf_get_device_capabilities ( void )

Returns: A pointer to an ngf_device_capabilities instance, or NULL, if no context is present on the calling thread.

◆ ngf_get_device_list()

ngf_error ngf_get_device_list	(	const ngf_device **	devices,
		uint32_t *	ndevices )

Obtains a list of rendering devices available to nicegraf.

This function is not thread-safe. The devices are not returned in any particular order, and the order is not guaranteed to be the same every time the function is called.

Parameters

devices	pointer to a pointer to `const` ngf_device. If not `NULL`, this will be populated with a pointer to an array of ngf_device instances, each containing data about a rendering device available to the system. Callers should not attempt to free the returned pointer.
ndevices	pointer to a `uint32_t`. If not NULL, the number of available rendering devices shall be written to the memory pointed to by this parameter.

◆ ngf_get_mtl_buffer_handle()

uintptr_t ngf_get_mtl_buffer_handle ( ngf_buffer buffer )

Returns a uintptr_t to the underlying MTLBuffer. The caller is responsible for casting the return value to a MTLBuffer.

Parameters

buffer A handle to a nicegraf buffer.

◆ ngf_get_mtl_cmd_buffer_handle()

uintptr_t ngf_get_mtl_cmd_buffer_handle ( ngf_cmd_buffer cmd_buffer )

Returns a uintptr_t to the underlying MTLCommandBuffer. The caller is responsible for casting the return value to a MTLCommandBuffer.

Parameters

cmd_buffer A handle to a nicegraf command buffer.

◆ ngf_get_mtl_compute_encoder_handle()

uintptr_t ngf_get_mtl_compute_encoder_handle ( ngf_compute_encoder compute_encoder )

Returns a uintptr_t to the underlying MTLComputeCommandEncoder. The caller is responsible for casting the return value to a MTLComputeCommandEncoder.

Parameters

cmd_buffer A handle to a nicegraf command buffer.

◆ ngf_get_mtl_image_handle()

uintptr_t ngf_get_mtl_image_handle ( ngf_image image )

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Returns a uintptr_t to the underlying MTLTexture. The caller is responsible for casting the return value to a MTLTexture.

Parameters

image A handle to a nicegraf image.

◆ ngf_get_mtl_render_encoder_handle()

uintptr_t ngf_get_mtl_render_encoder_handle ( ngf_render_encoder render_encoder )

Returns a uintptr_t to the underlying MTLRenderCommandEncoder. The caller is responsible for casting the return value to a MTLRenderCommandEncoder.

Parameters

cmd_buffer A handle to a nicegraf command buffer.

◆ ngf_get_mtl_sampler_handle()

uintptr_t ngf_get_mtl_sampler_handle ( ngf_sampler sampler )

Returns a uintptr_t to the underlying MTLSamplerState. The caller is responsible for casting the return value to a MTLSamplerState.

Parameters

sampler A handle to a nicegraf sampler.

◆ ngf_get_mtl_xfer_encoder_handle()

uintptr_t ngf_get_mtl_xfer_encoder_handle ( ngf_xfer_encoder xfer_encoder )

Returns a uintptr_t to the underlying MTLBlitCommandEncoder. The caller is responsible for casting the return value to a MTLBlitCommandEncoder.

Parameters

cmd_buffer A handle to a nicegraf command buffer.

◆ ngf_get_vk_buffer_handle()

uintptr_t ngf_get_vk_buffer_handle ( ngf_buffer buffer )

Returns a uintptr_t to the underlying VkBuffer. The caller is responsible for casting the return value to a VkBuffer.

Parameters

buffer A handle to a nicegraf buffer.

◆ ngf_get_vk_cmd_buffer_handle()

uintptr_t ngf_get_vk_cmd_buffer_handle ( ngf_cmd_buffer cmd_buffer )

Returns a uintptr_t to the underlying VkCommandBuffer. The caller is responsible for casting the return value to a VkCommandBuffer.

Parameters

cmd_buffer A handle to a nicegraf command buffer.

◆ ngf_get_vk_image_handle()

uintptr_t ngf_get_vk_image_handle ( ngf_image image )

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Returns a uintptr_t to the underlying VkImage. The caller is responsible for casting the return value to a VkImage.

Parameters

image A handle to a nicegraf image.

◆ ngf_get_vk_sampler_handle()

uintptr_t ngf_get_vk_sampler_handle ( ngf_sampler sampler )

Returns a uintptr_t to the underlying VkSampler. The caller is responsible for casting the return value to a VkSampler.

Parameters

sampler A handle to a nicegraf sampler.

◆ ngf_initialize()

ngf_error ngf_initialize ( const ngf_init_info * init_info )

Initializes nicegraf.

The client should call this function only once during the entire lifetime of the application. This function is not thread safe.

Parameters

init_info Initialization parameters.

◆ ngf_renderdoc_capture_begin()

void ngf_renderdoc_capture_begin ( )

Begins RenderDoc Capture.

Begins frame capture for the active window in the current context. Ended by ngf_renderdoc_capture_end.

◆ ngf_renderdoc_capture_end()

void ngf_renderdoc_capture_end ( )

Triggers RenderDoc Capture.

Ends frame capture for the active window in the current context.

◆ ngf_renderdoc_capture_next_frame()

void ngf_renderdoc_capture_next_frame ( )

Triggers RenderDoc Capture.

Captures the next frame from the active window in the current context. If called, subsequent calls to ngf_renderdoc_capture_begin and ngf_renderdoc_capture_end will do nothing until after the next frame that ngf_renderdoc_capture_next_frame was called (i.e. you cannot do nested captures).

◆ ngf_resize_context()

ngf_error ngf_resize_context	(	ngf_context	ctx,
		uint32_t	new_width,
		uint32_t	new_height )

Adjust the images associated with the given context's swapchain.

This function must be called every time that the window the context's presenting to is resized. It is up to the client application to detect the resize events and call this function. Not calling this function on resize results in undefined behavior.

Parameters

ctx	The context to operate on
new_width	New window client area width in pixels
new_height	New window client area height in pixels

◆ ngf_set_context()

ngf_error ngf_set_context ( ngf_context ctx )

Set the given nicegraf context as current for the calling thread.

All subsequent rendering operations invoked from the calling thread shall affect the given context.

Once a context has been set as current on a thread, it cannot be migrated to another thread.

Parameters

ctx	The context to set as current.

◆ ngf_start_cmd_buffer()

ngf_error ngf_start_cmd_buffer	(	ngf_cmd_buffer	buf,
		ngf_frame_token	token )

Resets the command buffer.

Erases all the commands previously recorded into the given command buffer, and prepares it for recording commands to be submitted within the frame identified by the specified token.

The command buffer is required to be in the "ready" state.

Parameters

buf	The handle to the command buffer to operate on
token	The token for the frame within which the recorded commands are going to be submitted.

◆ ngf_submit_cmd_buffers()

ngf_error ngf_submit_cmd_buffers	(	uint32_t	nbuffers,
		ngf_cmd_buffer *	bufs )

Submits the commands recorded in the given command buffers for execution. All command buffers must be in the "awaiting submission" state, and shall be transitioned to the "submitted" state.

Parameters

nbuffers	The number of command buffers being submitted for execution.
bufs	A pointer to a contiguous array of nbuffers handles to command buffer objects to be submitted for execution.

Detailed Description

General Remarks

Objects

Error Reporting

Host Memory Management

GPU Memory Management

Data Structures

Macros

Typedefs

Enumerations

Functions

Macro Definition Documentation

◆ NGF_DEVICE_NAME_MAX_LENGTH

Typedef Documentation

◆ ngf_device_handle

◆ ngf_frame_token

Enumeration Type Documentation

◆ ngf_attachment_load_op

◆ ngf_attachment_store_op

◆ ngf_attachment_type

◆ ngf_blend_factor

◆ ngf_blend_op

◆ ngf_buffer_storage_type

◆ ngf_buffer_usage

◆ ngf_compare_op

◆ ngf_cubemap_face

◆ ngf_cull_mode

◆ ngf_descriptor_type

◆ ngf_device_performance_tier

◆ ngf_diagnostic_log_verbosity

◆ ngf_diagnostic_message_type

◆ ngf_error

◆ ngf_front_face_mode

◆ ngf_image_format

◆ ngf_image_type

◆ ngf_image_usage

◆ ngf_polygon_mode

◆ ngf_present_mode

◆ ngf_primitive_topology

◆ ngf_sample_count

◆ ngf_sampler_filter

◆ ngf_sampler_wrap_mode

◆ ngf_stage_type

◆ ngf_stencil_op

◆ ngf_type

Function Documentation

◆ ngf_begin_frame()

◆ ngf_buffer_flush_range()

◆ ngf_buffer_map_range()

◆ ngf_buffer_unmap()

◆ ngf_cmd_begin_compute_pass()

◆ ngf_cmd_begin_debug_group()

◆ ngf_cmd_begin_render_pass()

◆ ngf_cmd_begin_render_pass_simple()

◆ ngf_cmd_begin_xfer_pass()

◆ ngf_cmd_bind_attrib_buffer()

◆ ngf_cmd_bind_compute_pipeline()

◆ ngf_cmd_bind_compute_resources()

◆ ngf_cmd_bind_gfx_pipeline()

◆ ngf_cmd_bind_index_buffer()

◆ ngf_cmd_bind_resources()

◆ ngf_cmd_copy_buffer()

◆ ngf_cmd_copy_image_to_buffer()

◆ ngf_cmd_dispatch()

◆ ngf_cmd_draw()

◆ ngf_cmd_end_compute_pass()

◆ ngf_cmd_end_current_debug_group()

◆ ngf_cmd_end_render_pass()

◆ ngf_cmd_end_xfer_pass()

◆ ngf_cmd_generate_mipmaps()

◆ ngf_cmd_scissor()

◆ ngf_cmd_stencil_compare_mask()

◆ ngf_cmd_stencil_reference()

◆ ngf_cmd_stencil_write_mask()

◆ ngf_cmd_viewport()

◆ ngf_cmd_write_image()

◆ ngf_create_buffer()

◆ ngf_create_cmd_buffer()

◆ ngf_create_compute_pipeline()

◆ ngf_create_context()