From d6e6fa01a51f3c9328c4cfdc1d7b3b448de11b84 Mon Sep 17 00:00:00 2001 From: Nicolai Hähnle Date: Thu, 2 Feb 2017 21:10:44 +0100 Subject: gallium: add sparse buffer interface and capability MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit v2: - explain the resource_commit interface in more detail Reviewed-by: Marek Olšák --- src/gallium/docs/source/context.rst | 25 +++++++++++++++++++++++++ src/gallium/docs/source/screen.rst | 3 +++ 2 files changed, 28 insertions(+) (limited to 'src/gallium/docs') diff --git a/src/gallium/docs/source/context.rst b/src/gallium/docs/source/context.rst index a053193722d..5949ff23c95 100644 --- a/src/gallium/docs/source/context.rst +++ b/src/gallium/docs/source/context.rst @@ -618,6 +618,31 @@ are set. +.. _resource_commit: + +resource_commit +%%%%%%%%%%%%%%% + +This function changes the commit state of a part of a sparse resource. Sparse +resources are created by setting the ``PIPE_RESOURCE_FLAG_SPARSE`` flag when +calling ``resource_create``. Initially, sparse resources only reserve a virtual +memory region that is not backed by memory (i.e., it is uncommitted). The +``resource_commit`` function can be called to commit or uncommit parts (or all) +of a resource. The driver manages the underlying backing memory. + +The contents of newly committed memory regions are undefined. Calling this +function to commit an already committed memory region is allowed and leaves its +content unchanged. Similarly, calling this function to uncommit an already +uncommitted memory region is allowed. + +For buffers, the given box must be aligned to multiples of +``PIPE_CAP_SPARSE_BUFFER_PAGE_SIZE``. As an exception to this rule, if the size +of the buffer is not a multiple of the page size, changing the commit state of +the last (partial) page requires a box that ends at the end of the buffer +(i.e., box->x + box->width == buffer->width0). + + + .. _pipe_transfer: PIPE_TRANSFER diff --git a/src/gallium/docs/source/screen.rst b/src/gallium/docs/source/screen.rst index 8685fb728ba..f1b91363d64 100644 --- a/src/gallium/docs/source/screen.rst +++ b/src/gallium/docs/source/screen.rst @@ -381,6 +381,9 @@ The integer capabilities: PIPE_POLYGON_MODE_FILL_RECTANGLE mode is supported for ``pipe_rasterizer_state::fill_front`` and ``pipe_rasterizer_state::fill_back``. +* ``PIPE_CAP_SPARSE_BUFFER_PAGE_SIZE``: The page size of sparse buffers in + bytes, or 0 if sparse buffers are not supported. The page size must be at + most 64KB. .. _pipe_capf: -- cgit v1.2.3