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