src/gallium/docs/source/screen.rst

   1 Screen
   2 ======
   3
   4 A screen is an object representing the context-independent part of a device.
   5
   6 Useful Flags
   7 ------------
   8
   9 .. _pipe_buffer_usage:
  10
  11 PIPE_BUFFER_USAGE
  12 ^^^^^^^^^^^^^^^^^
  13
  14 These flags control buffer creation. Buffers may only have one role, so
  15 care should be taken to not allocate a buffer with the wrong usage.
  16
  17 * ``PIXEL``: This is the flag to use for all textures.
  18 * ``VERTEX``: A vertex buffer.
  19 * ``INDEX``: An element buffer.
  20 * ``CONSTANT``: A buffer of shader constants.
  21
  22 Buffers are inevitably abstracting the pipe's underlying memory management,
  23 so many of their usage flags can be used to direct the way the buffer is
  24 handled.
  25
  26 * ``CPU_READ``, ``CPU_WRITE``: Whether the user will map and, in the case of
  27   the latter, write to, the buffer. The convenience flag ``CPU_READ_WRITE`` is
  28   available to signify a read/write buffer.
  29 * ``GPU_READ``, ``GPU_WRITE``: Whether the driver will internally need to
  30   read from or write to the buffer. The latter will only happen if the buffer
  31   is made into a render target.
  32 * ``DISCARD``: When set on a map, the contents of the map will be discarded
  33   beforehand. Cannot be used with ``CPU_READ``.
  34 * ``DONTBLOCK``: When set on a map, the map will fail if the buffer cannot be
  35   mapped immediately.
  36 * ``UNSYNCHRONIZED``: When set on a map, any outstanding operations on the
  37   buffer will be ignored. The interaction of any writes to the map and any
  38   operations pending with the buffer are undefined. Cannot be used with
  39   ``CPU_READ``.
  40 * ``FLUSH_EXPLICIT``: When set on a map, written ranges of the map require
  41   explicit flushes using :ref:`buffer_flush_mapped_range`. Requires
  42   ``CPU_WRITE``.
  43
  44 .. _pipe_texture_usage:
  45
  46 PIPE_TEXTURE_USAGE
  47 ^^^^^^^^^^^^^^^^^^
  48
  49 These flags determine the possible roles a texture may be used for during its
  50 lifetime. Texture usage flags are cumulative and may be combined to create a
  51 texture that can be used as multiple things.
  52
  53 * ``RENDER_TARGET``: A colorbuffer or pixelbuffer.
  54 * ``DISPLAY_TARGET``: A sharable buffer that can be given to another process.
  55 * ``PRIMARY``: A frontbuffer or scanout buffer.
  56 * ``DEPTH_STENCIL``: A depthbuffer, stencilbuffer, or Z buffer. Gallium does
  57   not explicitly provide for stencil-only buffers, so any stencilbuffer
  58   validated here is implicitly also a depthbuffer.
  59 * ``SAMPLER``: A texture that may be sampled from in a fragment or vertex
  60   shader.
  61 * ``DYNAMIC``: A texture that will be mapped frequently.
  62
  63 Methods
  64 -------
  65
  66 XXX moar; got bored
  67
  68 get_name
  69 ^^^^^^^^
  70
  71 Returns an identifying name for the screen.
  72
  73 get_vendor
  74 ^^^^^^^^^^
  75
  76 Returns the screen vendor.
  77
  78 get_param
  79 ^^^^^^^^^
  80
  81 Get an integer/boolean screen parameter.
  82
  83 get_paramf
  84 ^^^^^^^^^^
  85
  86 Get a floating-point screen parameter.
  87
  88 is_format_supported
  89 ^^^^^^^^^^^^^^^^^^^
  90
  91 See if a format can be used in a specific manner.
  92
  93 **usage** is a bitmask of :ref:`PIPE_TEXTURE_USAGE` flags.
  94
  95 Returns TRUE if all usages can be satisfied.
  96
  97 .. note::
  98
  99    ``PIPE_TEXTURE_USAGE_DYNAMIC`` is not a valid usage.
 100
 101 .. _texture_create:
 102
 103 texture_create
 104 ^^^^^^^^^^^^^^
 105
 106 Given a template of texture setup, create a buffer and texture.
 107
 108 texture_blanket
 109 ^^^^^^^^^^^^^^^
 110
 111 Like :ref:`texture_create`, but use a supplied buffer instead of creating a
 112 new one.
 113
 114 texture_destroy
 115 ^^^^^^^^^^^^^^^
 116
 117 Destroy a texture. The buffer backing the texture is destroyed if it has no
 118 more references.