gallium: support for array textures and related changes

resources have a array_size parameter now.
get_tex_surface and tex_surface_destroy have been renamed to create_surface
and surface_destroy and moved to context, similar to sampler views (and
create_surface now uses a template just like create_sampler_view). Surfaces
now really should only be used for rendering. In particular they shouldn't be
used as some kind of 2d abstraction for sharing a texture. offset/layout fields
don't make sense any longer and have been removed, width/height should go too.
surfaces and sampler views now specify a layer range (for texture resources),
layer is either array slice, depth slice or cube face.
pipe_subresource is gone array slices (or cube faces) are now treated the same
as depth slices in transfers etc. (that is, they use the z coord of the
respective functions).

Squashed commit of the following:

commit a45bd509014743d21a532194d7b658a1aeb00cb7
Merge: 1aeca28 32e1e59
Author: Roland Scheidegger <sroland@vmware.com>
Date:   Thu Dec 2 04:32:06 2010 +0100

    Merge remote branch 'origin/master' into gallium-array-textures

    Conflicts:
    	src/gallium/drivers/i915/i915_resource_texture.c
    	src/gallium/drivers/i915/i915_state_emit.c
    	src/gallium/drivers/i915/i915_surface.c

commit 1aeca287a827f29206078fa1204715a477072c08
Merge: 912f042 6f7c8c3
Author: Roland Scheidegger <sroland@vmware.com>
Date:   Thu Dec 2 00:37:11 2010 +0100

    Merge remote branch 'origin/master' into gallium-array-textures

    Conflicts:
    	src/gallium/state_trackers/vega/api_filters.c
    	src/gallium/state_trackers/vega/api_images.c
    	src/gallium/state_trackers/vega/mask.c
    	src/gallium/state_trackers/vega/paint.c
    	src/gallium/state_trackers/vega/renderer.c
    	src/gallium/state_trackers/vega/st_inlines.h
    	src/gallium/state_trackers/vega/vg_context.c
    	src/gallium/state_trackers/vega/vg_manager.c

commit 912f042e1d439de17b36be9a740358c876fcd144
Author: Roland Scheidegger <sroland@vmware.com>
Date:   Wed Dec 1 03:01:55 2010 +0100

    gallium: even more compile fixes after merge

commit 6fc95a58866d2a291def333608ba9c10c3f07e82
Author: Roland Scheidegger <sroland@vmware.com>
Date:   Wed Dec 1 00:22:26 2010 +0100

    gallium: some fixes after merge

commit a8d5ffaeb5397ffaa12fb422e4e7efdf0494c3e2
Merge: f7a202f 2da02e7
Author: Roland Scheidegger <sroland@vmware.com>
Date:   Tue Nov 30 23:41:26 2010 +0100

    Merge remote branch 'origin/master' into gallium-array-textures

    Conflicts:
    	src/gallium/drivers/i915/i915_state_emit.c
    	src/gallium/state_trackers/vega/api_images.c
    	src/gallium/state_trackers/vega/vg_context.c

commit f7a202fde2aea2ec78ef58830f945a5e214e56ab
Author: Roland Scheidegger <sroland@vmware.com>
Date:   Wed Nov 24 19:19:32 2010 +0100

    gallium: even more fixes/cleanups after merge

commit 6895a7f969ed7f9fa8ceb788810df8dbcf04c4c9
Author: Roland Scheidegger <sroland@vmware.com>
Date:   Wed Nov 24 03:07:36 2010 +0100

    gallium: more compile fixes after merge

commit af0501a5103b9756bc4d79167bd81051ad6e8670
Author: Roland Scheidegger <sroland@vmware.com>
Date:   Tue Nov 23 19:24:45 2010 +0100

    gallium: lots of compile fixes after merge

commit 0332003c2feb60f2a20e9a40368180c4ecd33e6b
Merge: 26c6346 b6b91fa
Author: Roland Scheidegger <sroland@vmware.com>
Date:   Tue Nov 23 17:02:26 2010 +0100

    Merge remote branch 'origin/master' into gallium-array-textures

    Conflicts:
    	src/gallium/auxiliary/gallivm/lp_bld_sample.c
    	src/gallium/auxiliary/util/u_blit.c
    	src/gallium/auxiliary/util/u_blitter.c
    	src/gallium/auxiliary/util/u_inlines.h
    	src/gallium/auxiliary/util/u_surface.c
    	src/gallium/auxiliary/util/u_surfaces.c
    	src/gallium/docs/source/context.rst
    	src/gallium/drivers/llvmpipe/lp_rast.c
    	src/gallium/drivers/nv50/nv50_state_validate.c
    	src/gallium/drivers/nvfx/nv04_surface_2d.c
    	src/gallium/drivers/nvfx/nv04_surface_2d.h
    	src/gallium/drivers/nvfx/nvfx_buffer.c
    	src/gallium/drivers/nvfx/nvfx_miptree.c
    	src/gallium/drivers/nvfx/nvfx_resource.c
    	src/gallium/drivers/nvfx/nvfx_resource.h
    	src/gallium/drivers/nvfx/nvfx_state_fb.c
    	src/gallium/drivers/nvfx/nvfx_surface.c
    	src/gallium/drivers/nvfx/nvfx_transfer.c
    	src/gallium/drivers/r300/r300_state_derived.c
    	src/gallium/drivers/r300/r300_texture.c
    	src/gallium/drivers/r600/r600_blit.c
    	src/gallium/drivers/r600/r600_buffer.c
    	src/gallium/drivers/r600/r600_context.h
    	src/gallium/drivers/r600/r600_screen.c
    	src/gallium/drivers/r600/r600_screen.h
    	src/gallium/drivers/r600/r600_state.c
    	src/gallium/drivers/r600/r600_texture.c
    	src/gallium/include/pipe/p_defines.h
    	src/gallium/state_trackers/egl/common/egl_g3d_api.c
    	src/gallium/state_trackers/glx/xlib/xm_st.c
    	src/gallium/targets/libgl-gdi/gdi_softpipe_winsys.c
    	src/gallium/targets/libgl-gdi/libgl_gdi.c
    	src/gallium/tests/graw/tri.c
    	src/mesa/state_tracker/st_cb_blit.c
    	src/mesa/state_tracker/st_cb_readpixels.c

commit 26c6346b385929fba94775f33838d0cceaaf1127
Author: Roland Scheidegger <sroland@vmware.com>
Date:   Mon Aug 2 19:37:21 2010 +0200

    fix more merge breakage

commit b30d87c6025eefe7f6979ffa8e369bbe755d5c1d
Merge: 9461bf3 1f1928d
Author: Roland Scheidegger <sroland@vmware.com>
Date:   Mon Aug 2 19:15:38 2010 +0200

    Merge remote branch 'origin/master' into gallium-array-textures

    Conflicts:
    	src/gallium/drivers/llvmpipe/lp_rast.c
    	src/gallium/drivers/llvmpipe/lp_rast_priv.h
    	src/gallium/drivers/r300/r300_blit.c
    	src/gallium/drivers/r300/r300_screen_buffer.c
    	src/gallium/drivers/r300/r300_state_derived.c
    	src/gallium/drivers/r300/r300_texture.c
    	src/gallium/drivers/r300/r300_texture.h
    	src/gallium/drivers/r300/r300_transfer.c
    	src/gallium/drivers/r600/r600_screen.c
    	src/gallium/drivers/r600/r600_state.c
    	src/gallium/drivers/r600/r600_texture.c
    	src/gallium/drivers/r600/r600_texture.h
    	src/gallium/state_trackers/dri/common/dri1_helper.c
    	src/gallium/state_trackers/dri/sw/drisw.c
    	src/gallium/state_trackers/xorg/xorg_exa.c

commit 9461bf3cfb647d2301364ae29fc3084fff52862a
Merge: 17492d7 0eaccb3
Author: Roland Scheidegger <sroland@vmware.com>
Date:   Thu Jul 15 20:13:45 2010 +0200

    Merge commit 'origin/master' into gallium-array-textures

    Conflicts:
    	src/gallium/auxiliary/util/u_blitter.c
    	src/gallium/drivers/llvmpipe/lp_rast.c
    	src/gallium/drivers/llvmpipe/lp_surface.c
    	src/gallium/drivers/r300/r300_render.c
    	src/gallium/drivers/r300/r300_state.c
    	src/gallium/drivers/r300/r300_texture.c
    	src/gallium/drivers/r300/r300_transfer.c
    	src/gallium/tests/trivial/quad-tex.c

commit 17492d705e7b7f607b71db045c3bf344cb6842b3
Author: Roland Scheidegger <sroland@vmware.com>
Date:   Fri Jun 18 10:58:08 2010 +0100

    gallium: rename element_offset/width fields in views to first/last_element

    This is much more consistent with the other fields used there
    (first/last level, first/last layer).
    Actually thinking about removing the ugly union/structs again and
    rename first/last_layer to something even more generic which could also
    be used for buffers (like first/last_member) without inducing headaches.

commit 1b717a289299f942de834dcccafbab91361e20ab
Author: Roland Scheidegger <sroland@vmware.com>
Date:   Thu Jun 17 14:46:09 2010 +0100

    gallium: remove PIPE_SURFACE_LAYOUT_LINEAR definition

    This was only used by the layout field of pipe_surface, but this
    driver internal stuff is gone so there's no need for this driver independent
    layout definition neither.

commit 10cb644b31b3ef47e6c7b55e514ad24bb891fac4
Merge: 5691db9 c85971d
Author: Roland Scheidegger <sroland@vmware.com>
Date:   Thu Jun 17 12:20:41 2010 +0100

    Merge commit 'origin/master' into gallium-array-textures

    Conflicts:
    	src/gallium/docs/source/glossary.rst
    	src/gallium/tests/graw/fs-test.c
    	src/gallium/tests/graw/gs-test.c

commit 5691db960ca3d525ce7d6c32d9c7a28f5e907f3b
Author: Roland Scheidegger <sroland@vmware.com>
Date:   Thu Jun 17 11:29:03 2010 +0100

    st/wgl: fix interface changes bugs

commit 2303ec32143d363b46e59e4b7c91b0ebd34a16b2
Author: Roland Scheidegger <sroland@vmware.com>
Date:   Wed Jun 16 19:42:32 2010 +0100

    gallium: adapt code to interface changes...

commit dcae4f586f0d0885b72674a355e5d56d47afe77d
Author: Roland Scheidegger <sroland@vmware.com>
Date:   Wed Jun 16 19:42:05 2010 +0100

    gallium: separate depth0 and array_size in the resource itself.

    These fields are still mutually exclusive (since no 3d array textures exist)
    but it ultimately seemed to error-prone to adapt all code accept the new
    meaning of depth0 (drivers stick that into hardware regs, calculate mipmap
    sizes etc.). And it isn't really cleaner anyway.
    So, array textures will have depth0 of 1, but instead use array_size,
    3D textures will continue to use depth0 (and have array_size of 1). Cube
    maps also will use array_size to indicate their 6 faces, but since all drivers
    should just be fine by inferring this themselves from the fact it's a cube map
    as they always used to nothing should break.

commit 621737a638d187d208712250fc19a91978fdea6b
Author: Roland Scheidegger <sroland@vmware.com>
Date:   Wed Jun 16 17:47:38 2010 +0100

    gallium: adapt code to interface changes

    There are still usages of pipe_surface where pipe_resource should be used,
    which should eventually be fixed.

commit 2d17f5efe166b2c3d51957c76294165ab30b8ae2
Author: Roland Scheidegger <sroland@vmware.com>
Date:   Wed Jun 16 17:46:14 2010 +0100

    gallium: more interface changes

    In particular to enable usage of buffers in views, and ability to use a
    different pipe_format in pipe_surface.
    Get rid of layout and offset parameter in pipe_surface - the former was
    not used in any (public) code anyway, and the latter should either be computed
    on-demand or driver can use subclass of pipe_surface.
    Also make create_surface() use a template to be more consistent with
    other functions.

commit 71f885ee16aa5cf2742c44bfaf0dc5b8734b9901
Merge: 3232d11 8ad410d
Author: Roland Scheidegger <sroland@vmware.com>
Date:   Mon Jun 14 14:19:51 2010 +0100

    Merge commit 'origin/master' into gallium-array-textures

    Conflicts:
    	src/gallium/auxiliary/util/u_box.h
    	src/gallium/drivers/nv50/nv50_surface.c
    	src/gallium/drivers/nvfx/nvfx_surface.c
    	src/gallium/drivers/r300/r300_blit.c
    	src/gallium/drivers/r300/r300_texture.c
    	src/gallium/drivers/r300/r300_transfer.c
    	src/gallium/drivers/r600/r600_blit.c
    	src/gallium/drivers/r600/r600_screen.h
    	src/gallium/include/pipe/p_state.h

commit 3232d11fe3ebf7686286013c357b404714853984
Author: Roland Scheidegger <sroland@vmware.com>
Date:   Mon Jun 14 11:40:04 2010 +0100

    mesa/st: adapt to interface changes

    still need to fix pipe_surface sharing
    (as that is now per-context).
    Also broken is depth0 handling - half the code assumes
    this is also used for array textures (and hence by extension
    of that cube maps would have depth 6), half the code does not...

commit f433b7f7f552720e5eade0b4078db94590ee85e1
Author: Roland Scheidegger <sroland@vmware.com>
Date:   Mon Jun 14 11:35:52 2010 +0100

    gallium: fix a couple of bugs in interface chnage fixes

commit 818366b28ea18f514dc791646248ce6f08d9bbcf
Author: Roland Scheidegger <sroland@vmware.com>
Date:   Sat Jun 12 02:42:11 2010 +0200

    targets: adapt to interface changes

    Yes even that needs adjustments...

commit 66c511ab1682c9918e0200902039247793acb41e
Author: Roland Scheidegger <sroland@vmware.com>
Date:   Sat Jun 12 02:41:13 2010 +0200

    tests: adapt to interface changes

    Everything needs to be fixed :-(.

commit 6b494635d9dbdaa7605bc87b1ebf682b138c5808
Author: Roland Scheidegger <sroland@vmware.com>
Date:   Sat Jun 12 02:39:50 2010 +0200

    st: adapt non-rendering state trackers to interface changes

    might not be quite right in all places, but they really don't want
    to use pipe_surface.

commit 00c4289a35d86e4fe85919ec32aa9f5ffe69d16d
Author: Roland Scheidegger <sroland@vmware.com>
Date:   Sat Jun 12 02:38:48 2010 +0200

    winsys: adapt to interface changes

commit 39d858554dc9ed5dbc795626fec3ef9deae552a0
Author: Roland Scheidegger <sroland@vmware.com>
Date:   Sat Jun 12 02:26:54 2010 +0200

    st/python: adapt to interface changes

    don't think that will work, sorry.

commit 6e9336bc49b32139cec4e683857d0958000e15e3
Author: Roland Scheidegger <sroland@vmware.com>
Date:   Sat Jun 12 02:26:07 2010 +0200

    st/vega: adapt to interface changes

commit e07f2ae9aaf8842757d5d50865f76f8276245e11
Author: Roland Scheidegger <sroland@vmware.com>
Date:   Sat Jun 12 02:25:56 2010 +0200

    st/xorg: adapt to interface changes

commit 05531c10a74a4358103e30d3b38a5eceb25c947f
Author: Roland Scheidegger <sroland@vmware.com>
Date:   Sat Jun 12 02:24:53 2010 +0200

    nv50: adapt to interface changes

commit 97704f388d7042121c6d496ba8c003afa3ea2bf3
Author: Roland Scheidegger <sroland@vmware.com>
Date:   Sat Jun 12 02:24:45 2010 +0200

    nvfx: adapt to interface changes

commit a8a9c93d703af6e8f5c12e1cea9ec665add1abe0
Author: Roland Scheidegger <sroland@vmware.com>
Date:   Sat Jun 12 02:24:01 2010 +0200

    i965g: adapt to interface changes

commit 0dde209589872d20cc34ed0b237e3ed7ae0e2de3
Author: Roland Scheidegger <sroland@vmware.com>
Date:   Sat Jun 12 02:22:38 2010 +0200

    i915g: adapt to interface changes

commit 5cac9beede69d12f5807ee1a247a4c864652799e
Author: Roland Scheidegger <sroland@vmware.com>
Date:   Sat Jun 12 02:20:58 2010 +0200

    svga: adapt to interface changes

    resource_copy_region still looking fishy.
    Was not very suited to unified zslice/face approach...

commit 08b5a6af4b963a3e4c75fc336bf6c0772dce5150
Author: Roland Scheidegger <sroland@vmware.com>
Date:   Sat Jun 12 02:20:01 2010 +0200

    rbug: adapt to interface changes

    Not sure if that won't need changes elsewhere?

commit c9fd24b1f586bcef2e0a6e76b68e40fca3408964
Author: Roland Scheidegger <sroland@vmware.com>
Date:   Sat Jun 12 02:19:31 2010 +0200

    trace: adapt to interface changes

commit ed84e010afc5635a1a47390b32247a266f65b8d1
Author: Roland Scheidegger <sroland@vmware.com>
Date:   Sat Jun 12 02:19:21 2010 +0200

    failover: adapt to interface changes

commit a1d4b4a293da933276908e3393435ec4b43cf201
Author: Roland Scheidegger <sroland@vmware.com>
Date:   Sat Jun 12 02:19:12 2010 +0200

    identity: adapt to interface changes

commit a8dd73e2c56c7d95ffcf174408f38f4f35fd2f4c
Author: Roland Scheidegger <sroland@vmware.com>
Date:   Sat Jun 12 02:18:55 2010 +0200

    softpipe: adapt to interface changes

commit a886085893e461e8473978e8206ec2312b7077ff
Author: Roland Scheidegger <sroland@vmware.com>
Date:   Sat Jun 12 02:18:44 2010 +0200

    llvmpipe: adapt to interface changes

commit 70523f6d567d8b7cfda682157556370fd3c43460
Author: Roland Scheidegger <sroland@vmware.com>
Date:   Sat Jun 12 02:18:14 2010 +0200

    r600g: adapt to interface changes

commit 3f4bc72bd80994865eb9f6b8dfd11e2b97060d19
Author: Roland Scheidegger <sroland@vmware.com>
Date:   Sat Jun 12 02:18:05 2010 +0200

    r300g: adapt to interface changes

commit 5d353b55ee14db0ac0515b5a3cf9389430832c19
Author: Roland Scheidegger <sroland@vmware.com>
Date:   Sat Jun 12 02:17:37 2010 +0200

    cell: adapt to interface changes

    not even compile tested

commit cf5d03601322c2dcb12d7a9c2f1745e2b2a35eb4
Author: Roland Scheidegger <sroland@vmware.com>
Date:   Sat Jun 12 02:14:59 2010 +0200

    util: adapt to interface changes

    amazing how much code changes just due to some subtle interface changes?

commit dc98d713c6937c0e177fc2caf23020402cc7ea7b
Author: Roland Scheidegger <sroland@vmware.com>
Date:   Sat Jun 12 02:12:40 2010 +0200

    gallium: more interface fail, docs

    this also changes flush_frontbuffer to use a pipe_resource instead of
    a pipe_surface - pipe_surface is not meant to be (or at least no longer)
    an abstraction for standalone 2d images which get passed around.
    (This has also implications for the non-rendering state-trackers.)

commit 08436d27ddd59857c22827c609b692aa0c407b7b
Author: Roland Scheidegger <sroland@vmware.com>
Date:   Thu Jun 10 17:42:52 2010 +0200

    gallium: fix array texture interface changes bugs, docs

commit 4a4d927609b62b4d7fb9dffa35158afe282f277b
Author: Roland Scheidegger <sroland@vmware.com>
Date:   Thu Jun 3 22:02:44 2010 +0200

    gallium: interface changes for array textures and related cleanups

    This patch introduces array textures to gallium (note they are not immediately
    usable without the associated changes to the shader side).
    Also, this abandons pipe_subresource in favor of using level and layer
    parameters since the distinction between several faces (which was part of
    pipe_subresource for cube textures) and several z slices (which were not part
    of pipe_subresource but instead part of pipe_box where appropriate for 3d
    textures) is gone at the resource level.
    Textures, be it array, cube, or 3d, now use a "unified" set of parameters,
    there is no distinction between array members, cube faces, or 3d zslices.
    This is unlike d3d10, whose subresource index includes layer information for
    array textures, but which considers all z slices of a 3d texture to be part
    of the same subresource.
    In contrast to d3d10, OpenGL though reuses old 2d and 3d function entry points
    for 1d and 2d array textures, respectively, which also implies that for instance
    it is possible to specify all layers of a 2d array texture at once (note that
    this is not possible for cube maps, which use the 2d entry points, although
    it is possible for cube map arrays, which aren't supported yet in gallium).
    This should possibly make drivers a bit simpler, and also get rid of mutually
    exclusive parameters in some functions (as z and face were exclusive), one
    potential downside would be that 3d array textures could not easily be supported
    without reverting this, but those are nowhere to be seen.

    Also along with adjusting to new parameters, rename get_tex_surface /
    tex_surface_destroy to create_surface / surface_destroy and move them from
    screen to context, which reflects much better what those do (they are analogous
    to create_sampler_view / sampler_view_destroy).

    PIPE_CAP_ARRAY_TEXTURES is used to indicate if a driver supports all of this
    functionality (that is, both sampling from array texture as well as use a range
    of layers as a render target, with selecting the layer from the geometry shader).

4 files changed, 59 insertions, 22 deletions

diff --git a/src/gallium/docs/d3d11ddi.txt b/src/gallium/docs/d3d11ddi.txt
index f8155c828b..11e7719089 100644
--- a/src/gallium/docs/d3d11ddi.txt
+++ b/src/gallium/docs/d3d11ddi.txt
@@ -162,8 +162,8 @@ CreateDepthStencilState -> create_depth_stencil_alpha_state
 	+ Gallium has per-face writemask/valuemasks, D3D11 uses the same value for back and front
 	+ Gallium supports the alpha test, which D3D11 lacks
 
-CreateDepthStencilView -> get_tex_surface
-CreateRenderTargetView -> get_tex_surface
+CreateDepthStencilView -> create_surface
+CreateRenderTargetView -> create_surface
 	! Gallium merges depthstencil and rendertarget views into pipe_surface, which also doubles as a 2D surface abstraction
 	- lack of texture array support
 	- lack of render-to-buffer support
@@ -221,7 +221,6 @@ CreateResource -> texture_create or buffer_create
 	! D3D11 specifies mapping flags (i.e. read/write/discard);:it's unclear what they are used for here
 	- D3D11 supports odd things in the D3D10_DDI_RESOURCE_MISC_FLAG enum (D3D10_DDI_RESOURCE_MISC_DISCARD_ON_PRESENT, D3D11_DDI_RESOURCE_MISC_BUFFER_ALLOW_RAW_VIEWS, D3D11_DDI_RESOURCE_MISC_BUFFER_STRUCTURED)
 	- Gallium does not support indirect draw call parameter buffers
-	- Gallium lacks array textures
 	! D3D11 supports specifying hardware modes and other stuff here for scanout resources
 	+ Gallium allows specifying minimum buffer alignment
 	! D3D11 implements cube maps as 2D array textures
diff --git a/src/gallium/docs/source/context.rst b/src/gallium/docs/source/context.rst
index e09a1304c4..c33cf7c573 100644
--- a/src/gallium/docs/source/context.rst
+++ b/src/gallium/docs/source/context.rst
@@ -84,7 +84,14 @@ in the result register. For example, ``swizzle_r`` specifies what is going to be
 placed in first component of result register.
 
 The ``first_level`` and ``last_level`` fields of sampler view template specify
-the LOD range the texture is going to be constrained to.
+the LOD range the texture is going to be constrained to. Note that these
+values are in addition to the respective min_lod, max_lod values in the
+pipe_sampler_state (that is if min_lod is 2.0, and first_level 3, the first mip
+level used for sampling from the resource is effectively the fifth).
+
+The ``first_layer`` and ``last_layer`` fields specify the layer range the
+texture is going to be constrained to. Similar to the LOD range, this is added
+to the array index which is used for sampling.
 
 * ``set_fragment_sampler_views`` binds an array of sampler views to
   fragment shader stage. Every binding point acquires a reference
@@ -103,6 +110,22 @@ the LOD range the texture is going to be constrained to.
 * ``sampler_view_destroy`` destroys a sampler view and releases its reference
   to associated texture.
 
+Surfaces
+^^^^^^^^
+
+These are the means to use resources as color render targets or depthstencil
+attachments. To create one, specify the mip level, the range of layers, and
+the bind flags (either PIPE_BIND_DEPTH_STENCIL or PIPE_BIND_RENDER_TARGET).
+Note that layer values are in addition to what is indicated by the geometry
+shader output variable XXX_FIXME (that is if first_layer is 3 and geometry
+shader indicates index 2, the 5th layer of the resource will be used). These
+first_layer and last_layer parameters will only be used for 1d array, 2d array,
+cube, and 3d textures otherwise they are 0.
+
+* ``create_surface`` creates a new surface.
+
+* ``surface_destroy`` destroys a surface and releases its reference to the
+  associated resource.
 
 Clearing
 ^^^^^^^^
@@ -118,8 +141,7 @@ used by GL), and always clears the whole surfaces (no scissoring as used by
 GL clear or explicit rectangles like d3d9 uses). It can, however, also clear
 only depth or stencil in a combined depth/stencil surface, if the driver
 supports PIPE_CAP_DEPTHSTENCIL_CLEAR_SEPARATE.
-If a surface includes several layers/slices (XXX: not yet...) then all layers
-will be cleared.
+If a surface includes several layers then all layers will be cleared.
 
 ``clear_render_target`` clears a single color rendertarget with the specified
 color value. While it is only possible to clear one surface at a time (which can
@@ -271,12 +293,12 @@ These methods operate directly on ``pipe_resource`` objects, and stand
 apart from any 3D state in the context.  Blitting functionality may be
 moved to a separate abstraction at some point in the future.
 
-``resource_copy_region`` blits a region of a subresource of a resource to a
-region of another subresource of a resource, provided that both resources have
-the same format, or compatible formats, i.e., formats for which copying the
-bytes from the source resource unmodified to the destination resource will
-achieve the same effect of a textured quad blitter. The source and destination
-may be the same resource, but overlapping blits are not permitted.
+``resource_copy_region`` blits a region of a resource to a region of another
+resource, provided that both resources have the same format, or compatible
+formats, i.e., formats for which copying the bytes from the source resource
+unmodified to the destination resource will achieve the same effect of a
+textured quad blitter.. The source and destination may be the same resource,
+but overlapping blits are not permitted.
 
 ``resource_resolve`` resolves a multisampled resource into a non-multisampled
 one. Formats and dimensions must match. This function must be present if a driver
diff --git a/src/gallium/docs/source/glossary.rst b/src/gallium/docs/source/glossary.rst
index acde56eafc..c749d0c955 100644
--- a/src/gallium/docs/source/glossary.rst
+++ b/src/gallium/docs/source/glossary.rst
@@ -22,6 +22,14 @@ Glossary
       Level of Detail. Also spelled "LoD." The value that determines when the
       switches between mipmaps occur during texture sampling.
 
+   layer
+      This term is used as the name of the "3rd coordinate" of a resource.
+      3D textures have zslices, cube maps have faces, 1D and 2D array textures
+      have array members (other resources do not have multiple layers).
+      Since the functions only take one parameter no matter what type of
+      resource is used, use the term "layer" instead of a resource type
+      specific one.
+
    GLSL
       GL Shading Language. The official, common high-level shader language used
       in GL 2.0 and above.
diff --git a/src/gallium/docs/source/screen.rst b/src/gallium/docs/source/screen.rst
index e3ef49c862..09edbaa673 100644
--- a/src/gallium/docs/source/screen.rst
+++ b/src/gallium/docs/source/screen.rst
@@ -258,25 +258,33 @@ resource_create
 Create a new resource from a template.
 The following fields of the pipe_resource must be specified in the template:
 
-target
+**target** one of the pipe_texture_target enums.
+Note that PIPE_BUFFER and PIPE_TEXTURE_X are not really fundamentally different.
+Modern APIs allow using buffers as shader resources.
 
-format
+**format** one of the pipe_format enums.
 
-width0
+**width0** the width of the base mip level of the texture or size of the buffer.
 
-height0
+**height0** the height of the base mip level of the texture
+(1 for 1D or 1D array textures).
 
-depth0
+**depth0** the depth of the base mip level of the texture
+(1 for everything else).
 
-last_level
+**array_size the array size for 1D and 2D array textures.
+For cube maps this must be 6, for other textures 1.
 
-nr_samples
+**last_level** the last mip map level present.
 
-usage
+**nr_samples** the nr of msaa samples. 0 (or 1) specifies a resource
+which isn't multisampled.
 
-bind
+**usage** one of the PIPE_USAGE flags.
 
-flags
+**bind** bitmask of the PIPE_BIND flags.
+
+**flags** bitmask of PIPE_RESOURCE_FLAG flags.