src/gallium/auxiliary/pipebuffer/pb_buffer.h

   1 /**************************************************************************
   2  *
   3  * Copyright 2007 VMware, Inc.
   4  * All Rights Reserved.
   5  *
   6  * Permission is hereby granted, free of charge, to any person obtaining a
   7  * copy of this software and associated documentation files (the
   8  * "Software"), to deal in the Software without restriction, including
   9  * without limitation the rights to use, copy, modify, merge, publish,
  10  * distribute, sub license, and/or sell copies of the Software, and to
  11  * permit persons to whom the Software is furnished to do so, subject to
  12  * the following conditions:
  13  *
  14  * The above copyright notice and this permission notice (including the
  15  * next paragraph) shall be included in all copies or substantial portions
  16  * of the Software.
  17  *
  18  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
  19  * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  20  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT.
  21  * IN NO EVENT SHALL VMWARE AND/OR ITS SUPPLIERS BE LIABLE FOR
  22  * ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
  23  * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
  24  * SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  25  *
  26  **************************************************************************/
  27
  28 /**
  29  * \file
  30  * Generic code for buffers.
  31  *
  32  * Behind a pipe buffle handle there can be DMA buffers, client (or user)
  33  * buffers, regular malloced buffers, etc. This file provides an abstract base
  34  * buffer handle that allows the driver to cope with all those kinds of buffers
  35  * in a more flexible way.
  36  *
  37  * There is no obligation of a winsys driver to use this library. And a pipe
  38  * driver should be completly agnostic about it.
  39  *
  40  * \author Jose Fonseca <jfonseca@vmware.com>
  41  */
  42
  43 #ifndef PB_BUFFER_H_
  44 #define PB_BUFFER_H_
  45
  46
  47 #include "pipe/p_compiler.h"
  48 #include "util/u_debug.h"
  49 #include "util/u_inlines.h"
  50 #include "pipe/p_defines.h"
  51
  52
  53 #ifdef __cplusplus
  54 extern "C" {
  55 #endif
  56
  57
  58 struct pb_vtbl;
  59 struct pb_validate;
  60 struct pipe_fence_handle;
  61
  62
  63 #define PB_USAGE_CPU_READ  (1 << 0)
  64 #define PB_USAGE_CPU_WRITE (1 << 1)
  65 #define PB_USAGE_GPU_READ  (1 << 2)
  66 #define PB_USAGE_GPU_WRITE (1 << 3)
  67 #define PB_USAGE_UNSYNCHRONIZED (1 << 10)
  68 #define PB_USAGE_DONTBLOCK (1 << 9)
  69
  70 #define PB_USAGE_CPU_READ_WRITE \
  71    ( PB_USAGE_CPU_READ | PB_USAGE_CPU_WRITE )
  72 #define PB_USAGE_GPU_READ_WRITE \
  73    ( PB_USAGE_GPU_READ | PB_USAGE_GPU_WRITE )
  74 #define PB_USAGE_WRITE \
  75    ( PB_USAGE_CPU_WRITE | PB_USAGE_GPU_WRITE )
  76
  77 /**
  78  * Buffer description.
  79  *
  80  * Used when allocating the buffer.
  81  */
  82 struct pb_desc
  83 {
  84    unsigned alignment;
  85    unsigned usage;
  86 };
  87
  88
  89 /**
  90  * 64-bit type for GPU buffer sizes and offsets.
  91  */
  92 typedef uint64_t pb_size;
  93
  94
  95 /**
  96  * Base class for all pb_* buffers.
  97  */
  98 struct pb_buffer
  99 {
 100    struct pipe_reference  reference;
 101    unsigned               alignment;
 102    pb_size                size;
 103    unsigned               usage;
 104
 105    /**
 106     * Pointer to the virtual function table.
 107     *
 108     * Avoid accessing this table directly. Use the inline functions below
 109     * instead to avoid mistakes.
 110     */
 111    const struct pb_vtbl *vtbl;
 112 };
 113
 114
 115 /**
 116  * Virtual function table for the buffer storage operations.
 117  *
 118  * Note that creation is not done through this table.
 119  */
 120 struct pb_vtbl
 121 {
 122    void (*destroy)( struct pb_buffer *buf );
 123
 124    /**
 125     * Map the entire data store of a buffer object into the client's address.
 126     * flags is bitmask of PB_USAGE_CPU_READ/WRITE.
 127     */
 128    void *(*map)( struct pb_buffer *buf,
 129                  unsigned flags, void *flush_ctx );
 130
 131    void (*unmap)( struct pb_buffer *buf );
 132
 133    enum pipe_error (*validate)( struct pb_buffer *buf,
 134                                 struct pb_validate *vl,
 135                                 unsigned flags );
 136
 137    void (*fence)( struct pb_buffer *buf,
 138                   struct pipe_fence_handle *fence );
 139
 140    /**
 141     * Get the base buffer and the offset.
 142     *
 143     * A buffer can be subdivided in smaller buffers. This method should return
 144     * the underlaying buffer, and the relative offset.
 145     *
 146     * Buffers without an underlaying base buffer should return themselves, with
 147     * a zero offset.
 148     *
 149     * Note that this will increase the reference count of the base buffer.
 150     */
 151    void (*get_base_buffer)( struct pb_buffer *buf,
 152                             struct pb_buffer **base_buf,
 153                             pb_size *offset );
 154
 155 };
 156
 157
 158
 159 /* Accessor functions for pb->vtbl:
 160  */
 161 static inline void *
 162 pb_map(struct pb_buffer *buf,
 163        unsigned flags, void *flush_ctx)
 164 {
 165    assert(buf);
 166    if (!buf)
 167       return NULL;
 168    assert(pipe_is_referenced(&buf->reference));
 169    return buf->vtbl->map(buf, flags, flush_ctx);
 170 }
 171
 172
 173 static inline void
 174 pb_unmap(struct pb_buffer *buf)
 175 {
 176    assert(buf);
 177    if (!buf)
 178       return;
 179    assert(pipe_is_referenced(&buf->reference));
 180    buf->vtbl->unmap(buf);
 181 }
 182
 183
 184 static inline void
 185 pb_get_base_buffer( struct pb_buffer *buf,
 186                     struct pb_buffer **base_buf,
 187                     pb_size *offset )
 188 {
 189    assert(buf);
 190    if (!buf) {
 191       base_buf = NULL;
 192       offset = 0;
 193       return;
 194    }
 195    assert(pipe_is_referenced(&buf->reference));
 196    assert(buf->vtbl->get_base_buffer);
 197    buf->vtbl->get_base_buffer(buf, base_buf, offset);
 198    assert(*base_buf);
 199    assert(*offset < (*base_buf)->size);
 200 }
 201
 202
 203 static inline enum pipe_error
 204 pb_validate(struct pb_buffer *buf, struct pb_validate *vl, unsigned flags)
 205 {
 206    assert(buf);
 207    if (!buf)
 208       return PIPE_ERROR;
 209    assert(buf->vtbl->validate);
 210    return buf->vtbl->validate(buf, vl, flags);
 211 }
 212
 213
 214 static inline void
 215 pb_fence(struct pb_buffer *buf, struct pipe_fence_handle *fence)
 216 {
 217    assert(buf);
 218    if (!buf)
 219       return;
 220    assert(buf->vtbl->fence);
 221    buf->vtbl->fence(buf, fence);
 222 }
 223
 224
 225 static inline void
 226 pb_destroy(struct pb_buffer *buf)
 227 {
 228    assert(buf);
 229    if (!buf)
 230       return;
 231    assert(!pipe_is_referenced(&buf->reference));
 232    buf->vtbl->destroy(buf);
 233 }
 234
 235 static inline void
 236 pb_reference(struct pb_buffer **dst,
 237              struct pb_buffer *src)
 238 {
 239    struct pb_buffer *old = *dst;
 240
 241    if (pipe_reference(&(*dst)->reference, &src->reference))
 242       pb_destroy( old );
 243    *dst = src;
 244 }
 245
 246
 247 /**
 248  * Utility function to check whether the provided alignment is consistent with
 249  * the requested or not.
 250  */
 251 static inline boolean
 252 pb_check_alignment(pb_size requested, pb_size provided)
 253 {
 254    if(!requested)
 255       return TRUE;
 256    if(requested > provided)
 257       return FALSE;
 258    if(provided % requested != 0)
 259       return FALSE;
 260    return TRUE;
 261 }
 262
 263
 264 /**
 265  * Utility function to check whether the provided alignment is consistent with
 266  * the requested or not.
 267  */
 268 static inline boolean
 269 pb_check_usage(unsigned requested, unsigned provided)
 270 {
 271    return (requested & provided) == requested ? TRUE : FALSE;
 272 }
 273
 274
 275 /**
 276  * Malloc-based buffer to store data that can't be used by the graphics
 277  * hardware.
 278  */
 279 struct pb_buffer *
 280 pb_malloc_buffer_create(pb_size size,
 281                         const struct pb_desc *desc);
 282
 283
 284 #ifdef __cplusplus
 285 }
 286 #endif
 287
 288 #endif /*PB_BUFFER_H_*/