From 4cf6acc3d0023d93e15531bbcdeffd15ba3e9924 Mon Sep 17 00:00:00 2001 From: =?utf8?q?Marek=20Ol=C5=A1=C3=A1k?= Date: Sun, 28 Oct 2012 21:31:12 +0100 Subject: [PATCH] gallium/u_vbuf: document how it works --- src/gallium/auxiliary/util/u_vbuf.c | 60 +++++++++++++++++++++++++++++ src/gallium/auxiliary/util/u_vbuf.h | 6 +-- 2 files changed, 63 insertions(+), 3 deletions(-) diff --git a/src/gallium/auxiliary/util/u_vbuf.c b/src/gallium/auxiliary/util/u_vbuf.c index 5bd60dc95f0..b712b52de06 100644 --- a/src/gallium/auxiliary/util/u_vbuf.c +++ b/src/gallium/auxiliary/util/u_vbuf.c @@ -25,6 +25,66 @@ * **************************************************************************/ +/** + * This module uploads user buffers and translates the vertex buffers which + * contain incompatible vertices (i.e. not supported by the driver/hardware) + * into compatible ones, based on the Gallium CAPs. + * + * It does not upload index buffers. + * + * The module heavily uses bitmasks to represent per-buffer and + * per-vertex-element flags to avoid looping over the list of buffers just + * to see if there's a non-zero stride, or user buffer, or unsupported format, + * etc. + * + * There are 3 categories of vertex elements, which are processed separately: + * - per-vertex attribs (stride != 0, instance_divisor == 0) + * - instanced attribs (stride != 0, instance_divisor > 0) + * - constant attribs (stride == 0) + * + * All needed uploads and translations are performed every draw command, but + * only the subset of vertices needed for that draw command is uploaded or + * translated. (the module never translates whole buffers) + * + * + * The module consists of two main parts: + * + * + * 1) Translate (u_vbuf_translate_begin/end) + * + * This is pretty much a vertex fetch fallback. It translates vertices from + * one vertex buffer to another in an unused vertex buffer slot. It does + * whatever is needed to make the vertices readable by the hardware (changes + * vertex formats and aligns offsets and strides). The translate module is + * used here. + * + * Each of the 3 categories is translated to a separate buffer. + * Only the [min_index, max_index] range is translated. For instanced attribs, + * the range is [start_instance, start_instance+instance_count]. For constant + * attribs, the range is [0, 1]. + * + * + * 2) User buffer uploading (u_vbuf_upload_buffers) + * + * Only the [min_index, max_index] range is uploaded (just like Translate) + * with a single memcpy. + * + * This method works best for non-indexed draw operations or indexed draw + * operations where the [min_index, max_index] range is not being way bigger + * than the vertex count. + * + * If the range is too big (e.g. one triangle with indices {0, 1, 10000}), + * the per-vertex attribs are uploaded via the translate module, all packed + * into one vertex buffer, and the indexed draw call is turned into + * a non-indexed one in the process. This adds additional complexity + * to the translate part, but it prevents bad apps from bringing your frame + * rate down. + * + * + * If there is nothing to do, it forwards every command to the driver. + * The module also has its own CSO cache of vertex element states. + */ + #include "util/u_vbuf.h" #include "util/u_dump.h" diff --git a/src/gallium/auxiliary/util/u_vbuf.h b/src/gallium/auxiliary/util/u_vbuf.h index 0f82271649d..a608184e596 100644 --- a/src/gallium/auxiliary/util/u_vbuf.h +++ b/src/gallium/auxiliary/util/u_vbuf.h @@ -28,9 +28,9 @@ #ifndef U_VBUF_H #define U_VBUF_H -/* This module builds upon u_upload_mgr and translate_cache and takes care of - * user buffer uploads and vertex format fallbacks. It's designed - * for the drivers which don't always use the Draw module. (e.g. for HWTCL) +/* This module takes care of user buffer uploads and vertex format fallbacks. + * It's designed for the drivers which don't want to use the Draw module. + * There is a more detailed description at the beginning of the .c file. */ #include "pipe/p_context.h" -- 2.30.2