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