src/gallium/auxiliary/pipebuffer/pb_buffer.h

   1 /**************************************************************************
   2  *
   3  * Copyright 2007 Tungsten Graphics, Inc., Cedar Park, Texas.
   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 TUNGSTEN GRAPHICS 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 <jrfonseca@tungstengraphics.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 #include "pipe/p_state.h"
  52
  53
  54 #ifdef __cplusplus
  55 extern "C" {
  56 #endif
  57
  58
  59 struct pb_vtbl;
  60 struct pb_validate;
  61
  62
  63 /**
  64  * Buffer description.
  65  *
  66  * Used when allocating the buffer.
  67  */
  68 struct pb_desc
  69 {
  70    unsigned alignment;
  71    unsigned usage;
  72 };
  73
  74
  75 /**
  76  * Size. Regular (32bit) unsigned for now.
  77  */
  78 typedef unsigned pb_size;
  79
  80
  81 /**
  82  * Base class for all pb_* buffers.
  83  */
  84 struct pb_buffer
  85 {
  86    struct pipe_buffer base;
  87
  88    /**
  89     * Pointer to the virtual function table.
  90     *
  91     * Avoid accessing this table directly. Use the inline functions below
  92     * instead to avoid mistakes.
  93     */
  94    const struct pb_vtbl *vtbl;
  95 };
  96
  97
  98 /**
  99  * Virtual function table for the buffer storage operations.
 100  *
 101  * Note that creation is not done through this table.
 102  */
 103 struct pb_vtbl
 104 {
 105    void (*destroy)( struct pb_buffer *buf );
 106
 107    /**
 108     * Map the entire data store of a buffer object into the client's address.
 109     * flags is bitmask of PIPE_BUFFER_FLAG_READ/WRITE.
 110     */
 111    void *(*map)( struct pb_buffer *buf,
 112                  unsigned flags );
 113
 114    void (*unmap)( struct pb_buffer *buf );
 115
 116    enum pipe_error (*validate)( struct pb_buffer *buf,
 117                                 struct pb_validate *vl,
 118                                 unsigned flags );
 119
 120    void (*fence)( struct pb_buffer *buf,
 121                   struct pipe_fence_handle *fence );
 122
 123    /**
 124     * Get the base buffer and the offset.
 125     *
 126     * A buffer can be subdivided in smaller buffers. This method should return
 127     * the underlaying buffer, and the relative offset.
 128     *
 129     * Buffers without an underlaying base buffer should return themselves, with
 130     * a zero offset.
 131     *
 132     * Note that this will increase the reference count of the base buffer.
 133     */
 134    void (*get_base_buffer)( struct pb_buffer *buf,
 135                             struct pb_buffer **base_buf,
 136                             pb_size *offset );
 137
 138 };
 139
 140
 141 static INLINE struct pipe_buffer *
 142 pb_pipe_buffer( struct pb_buffer *pbuf )
 143 {
 144    assert(pbuf);
 145    return &pbuf->base;
 146 }
 147
 148
 149 static INLINE struct pb_buffer *
 150 pb_buffer( struct pipe_buffer *buf )
 151 {
 152    assert(buf);
 153    /* Could add a magic cookie check on debug builds.
 154     */
 155    return (struct pb_buffer *)buf;
 156 }
 157
 158
 159 /* Accessor functions for pb->vtbl:
 160  */
 161 static INLINE void *
 162 pb_map(struct pb_buffer *buf,
 163        unsigned flags)
 164 {
 165    assert(buf);
 166    if(!buf)
 167       return NULL;
 168    assert(pipe_is_referenced(&buf->base.reference));
 169    return buf->vtbl->map(buf, flags);
 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->base.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->base.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)->base.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->base.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)->base.reference, &src->base.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_*/