pb_buffer.h revision 45bde75bd67e7e920f0113842d1fa58613ccc3ec 
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(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(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(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(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