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 "pipe/p_defines.h"
  50 #include "pipe/p_state.h"
  51
  52
  53 #ifdef __cplusplus
  54 extern "C" {
  55 #endif
  56
  57
  58 struct pb_vtbl;
  59 struct pb_validate;
  60
  61
  62 /**
  63  * Buffer description.
  64  *
  65  * Used when allocating the buffer.
  66  */
  67 struct pb_desc
  68 {
  69    unsigned alignment;
  70    unsigned usage;
  71 };
  72
  73
  74 /**
  75  * Size. Regular (32bit) unsigned for now.
  76  */
  77 typedef unsigned pb_size;
  78
  79
  80 /**
  81  * Base class for all pb_* buffers.
  82  */
  83 struct pb_buffer
  84 {
  85    struct pipe_buffer base;
  86
  87    /**
  88     * Pointer to the virtual function table.
  89     *
  90     * Avoid accessing this table directly. Use the inline functions below
  91     * instead to avoid mistakes.
  92     */
  93    const struct pb_vtbl *vtbl;
  94 };
  95
  96
  97 /**
  98  * Virtual function table for the buffer storage operations.
  99  *
 100  * Note that creation is not done through this table.
 101  */
 102 struct pb_vtbl
 103 {
 104    void (*destroy)( struct pb_buffer *buf );
 105
 106    /**
 107     * Map the entire data store of a buffer object into the client's address.
 108     * flags is bitmask of PIPE_BUFFER_FLAG_READ/WRITE.
 109     */
 110    void *(*map)( struct pb_buffer *buf,
 111                  unsigned flags );
 112
 113    void (*unmap)( struct pb_buffer *buf );
 114
 115    enum pipe_error (*validate)( struct pb_buffer *buf,
 116                                 struct pb_validate *vl,
 117                                 unsigned flags );
 118
 119    void (*fence)( struct pb_buffer *buf,
 120                   struct pipe_fence_handle *fence );
 121
 122    /**
 123     * Get the base buffer and the offset.
 124     *
 125     * A buffer can be subdivided in smaller buffers. This method should return
 126     * the underlaying buffer, and the relative offset.
 127     *
 128     * Buffers without an underlaying base buffer should return themselves, with
 129     * a zero offset.
 130     *
 131     * Note that this will increase the reference count of the base buffer.
 132     */
 133    void (*get_base_buffer)( struct pb_buffer *buf,
 134                             struct pb_buffer **base_buf,
 135                             pb_size *offset );
 136
 137 };
 138
 139
 140 static INLINE struct pipe_buffer *
 141 pb_pipe_buffer( struct pb_buffer *pbuf )
 142 {
 143    assert(pbuf);
 144    return &pbuf->base;
 145 }
 146
 147
 148 static INLINE struct pb_buffer *
 149 pb_buffer( struct pipe_buffer *buf )
 150 {
 151    assert(buf);
 152    /* Could add a magic cookie check on debug builds.
 153     */
 154    return (struct pb_buffer *)buf;
 155 }
 156
 157
 158 /* Accessor functions for pb->vtbl:
 159  */
 160 static INLINE void *
 161 pb_map(struct pb_buffer *buf,
 162        unsigned flags)
 163 {
 164    assert(buf);
 165    if(!buf)
 166       return NULL;
 167    assert(pipe_is_referenced(&buf->base.reference));
 168    return buf->vtbl->map(buf, flags);
 169 }
 170
 171
 172 static INLINE void
 173 pb_unmap(struct pb_buffer *buf)
 174 {
 175    assert(buf);
 176    if(!buf)
 177       return;
 178    assert(pipe_is_referenced(&buf->base.reference));
 179    buf->vtbl->unmap(buf);
 180 }
 181
 182
 183 static INLINE void
 184 pb_get_base_buffer( struct pb_buffer *buf,
 185                     struct pb_buffer **base_buf,
 186                     pb_size *offset )
 187 {
 188    assert(buf);
 189    if(!buf) {
 190       base_buf = NULL;
 191       offset = 0;
 192       return;
 193    }
 194    assert(pipe_is_referenced(&buf->base.reference));
 195    assert(buf->vtbl->get_base_buffer);
 196    buf->vtbl->get_base_buffer(buf, base_buf, offset);
 197    assert(*base_buf);
 198    assert(*offset < (*base_buf)->base.size);
 199 }
 200
 201
 202 static INLINE enum pipe_error
 203 pb_validate(struct pb_buffer *buf, struct pb_validate *vl, unsigned flags)
 204 {
 205    assert(buf);
 206    if(!buf)
 207       return PIPE_ERROR;
 208    assert(buf->vtbl->validate);
 209    return buf->vtbl->validate(buf, vl, flags);
 210 }
 211
 212
 213 static INLINE void
 214 pb_fence(struct pb_buffer *buf, struct pipe_fence_handle *fence)
 215 {
 216    assert(buf);
 217    if(!buf)
 218       return;
 219    assert(buf->vtbl->fence);
 220    buf->vtbl->fence(buf, fence);
 221 }
 222
 223
 224 static INLINE void
 225 pb_destroy(struct pb_buffer *buf)
 226 {
 227    assert(buf);
 228    if(!buf)
 229       return;
 230    assert(!pipe_is_referenced(&buf->base.reference));
 231    buf->vtbl->destroy(buf);
 232 }
 233
 234 static INLINE void
 235 pb_reference(struct pb_buffer **dst,
 236              struct pb_buffer *src)
 237 {
 238    struct pb_buffer *old = *dst;
 239
 240    if (pipe_reference(&(*dst)->base.reference, &src->base.reference))
 241       pb_destroy( old );
 242    *dst = src;
 243 }
 244
 245
 246 /**
 247  * Utility function to check whether the provided alignment is consistent with
 248  * the requested or not.
 249  */
 250 static INLINE boolean
 251 pb_check_alignment(pb_size requested, pb_size provided)
 252 {
 253    if(!requested)
 254       return TRUE;
 255    if(requested > provided)
 256       return FALSE;
 257    if(provided % requested != 0)
 258       return FALSE;
 259    return TRUE;
 260 }
 261
 262
 263 /**
 264  * Utility function to check whether the provided alignment is consistent with
 265  * the requested or not.
 266  */
 267 static INLINE boolean
 268 pb_check_usage(unsigned requested, unsigned provided)
 269 {
 270    return (requested & provided) == requested ? TRUE : FALSE;
 271 }
 272
 273
 274 /**
 275  * Malloc-based buffer to store data that can't be used by the graphics
 276  * hardware.
 277  */
 278 struct pb_buffer *
 279 pb_malloc_buffer_create(pb_size size,
 280                         const struct pb_desc *desc);
 281
 282
 283 #ifdef __cplusplus
 284 }
 285 #endif
 286
 287 #endif /*PB_BUFFER_H_*/