p_screen.h revision 4a49301e 
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 *
31 * Screen, Adapter or GPU
32 *
33 * These are driver functions/facilities that are context independent.
34 */
35
36
37#ifndef P_SCREEN_H
38#define P_SCREEN_H
39
40
41#include "pipe/p_compiler.h"
42#include "pipe/p_format.h"
43#include "pipe/p_defines.h"
44
45
46
47#ifdef __cplusplus
48extern "C" {
49#endif
50
51
52/** Opaque type */
53struct pipe_fence_handle;
54struct pipe_winsys;
55struct pipe_buffer;
56struct pipe_texture;
57struct pipe_surface;
58struct pipe_video_surface;
59struct pipe_transfer;
60
61
62/**
63 * Gallium screen/adapter context.  Basically everything
64 * hardware-specific that doesn't actually require a rendering
65 * context.
66 */
67struct pipe_screen {
68   struct pipe_winsys *winsys;
69
70   void (*destroy)( struct pipe_screen * );
71
72
73   const char *(*get_name)( struct pipe_screen * );
74
75   const char *(*get_vendor)( struct pipe_screen * );
76
77   /**
78    * Query an integer-valued capability/parameter/limit
79    * \param param  one of PIPE_CAP_x
80    */
81   int (*get_param)( struct pipe_screen *, int param );
82
83   /**
84    * Query a float-valued capability/parameter/limit
85    * \param param  one of PIPE_CAP_x
86    */
87   float (*get_paramf)( struct pipe_screen *, int param );
88
89   /**
90    * Check if the given pipe_format is supported as a texture or
91    * drawing surface.
92    * \param tex_usage  bitmask of PIPE_TEXTURE_USAGE_*
93    * \param geom_flags  bitmask of PIPE_TEXTURE_GEOM_*
94    */
95   boolean (*is_format_supported)( struct pipe_screen *,
96                                   enum pipe_format format,
97                                   enum pipe_texture_target target,
98                                   unsigned tex_usage,
99                                   unsigned geom_flags );
100
101   /**
102    * Create a new texture object, using the given template info.
103    */
104   struct pipe_texture * (*texture_create)(struct pipe_screen *,
105                                           const struct pipe_texture *templat);
106
107   /**
108    * Create a new texture object, using the given template info, but on top of
109    * existing memory.
110    *
111    * It is assumed that the buffer data is layed out according to the expected
112    * by the hardware. NULL will be returned if any inconsistency is found.
113    */
114   struct pipe_texture * (*texture_blanket)(struct pipe_screen *,
115                                            const struct pipe_texture *templat,
116                                            const unsigned *stride,
117                                            struct pipe_buffer *buffer);
118
119   void (*texture_destroy)(struct pipe_texture *pt);
120
121   /** Get a surface which is a "view" into a texture */
122   struct pipe_surface *(*get_tex_surface)(struct pipe_screen *,
123                                           struct pipe_texture *texture,
124                                           unsigned face, unsigned level,
125                                           unsigned zslice,
126                                           unsigned usage );
127
128   void (*tex_surface_destroy)(struct pipe_surface *);
129
130
131   /** Get a transfer object for transferring data to/from a texture */
132   struct pipe_transfer *(*get_tex_transfer)(struct pipe_screen *,
133                                             struct pipe_texture *texture,
134                                             unsigned face, unsigned level,
135                                             unsigned zslice,
136                                             enum pipe_transfer_usage usage,
137                                             unsigned x, unsigned y,
138                                             unsigned w, unsigned h);
139
140   void (*tex_transfer_destroy)(struct pipe_transfer *);
141
142   void *(*transfer_map)( struct pipe_screen *,
143                          struct pipe_transfer *transfer );
144
145   void (*transfer_unmap)( struct pipe_screen *,
146                           struct pipe_transfer *transfer );
147
148
149   /**
150    * Create a new buffer.
151    * \param alignment  buffer start address alignment in bytes
152    * \param usage  bitmask of PIPE_BUFFER_USAGE_x
153    * \param size  size in bytes
154    */
155   struct pipe_buffer *(*buffer_create)( struct pipe_screen *screen,
156                                         unsigned alignment,
157                                         unsigned usage,
158                                         unsigned size );
159
160   /**
161    * Create a buffer that wraps user-space data.
162    *
163    * Effectively this schedules a delayed call to buffer_create
164    * followed by an upload of the data at *some point in the future*,
165    * or perhaps never.  Basically the allocate/upload is delayed
166    * until the buffer is actually passed to hardware.
167    *
168    * The intention is to provide a quick way to turn regular data
169    * into a buffer, and secondly to avoid a copy operation if that
170    * data subsequently turns out to be only accessed by the CPU.
171    *
172    * Common example is OpenGL vertex buffers that are subsequently
173    * processed either by software TNL in the driver or by passing to
174    * hardware.
175    *
176    * XXX: What happens if the delayed call to buffer_create() fails?
177    *
178    * Note that ptr may be accessed at any time upto the time when the
179    * buffer is destroyed, so the data must not be freed before then.
180    */
181   struct pipe_buffer *(*user_buffer_create)(struct pipe_screen *screen,
182                                             void *ptr,
183                                             unsigned bytes);
184
185   /**
186    * Allocate storage for a display target surface.
187    *
188    * Often surfaces which are meant to be blitted to the front screen (i.e.,
189    * display targets) must be allocated with special characteristics, memory
190    * pools, or obtained directly from the windowing system.
191    *
192    * This callback is invoked by the pipe_screenwhen creating a texture marked
193    * with the PIPE_TEXTURE_USAGE_DISPLAY_TARGET flag  to get the underlying
194    * buffer storage.
195    */
196   struct pipe_buffer *(*surface_buffer_create)(struct pipe_screen *screen,
197						unsigned width, unsigned height,
198						enum pipe_format format,
199						unsigned usage,
200						unsigned tex_usage,
201						unsigned *stride);
202
203
204   /**
205    * Map the entire data store of a buffer object into the client's address.
206    * flags is bitmask of PIPE_BUFFER_USAGE_CPU_READ/WRITE flags.
207    */
208   void *(*buffer_map)( struct pipe_screen *screen,
209			struct pipe_buffer *buf,
210			unsigned usage );
211   /**
212    * Map a subrange of the buffer data store into the client's address space.
213    *
214    * The returned pointer is always relative to buffer start, regardless of
215    * the specified range. This is different from the ARB_map_buffer_range
216    * semantics because we don't forbid multiple mappings of the same buffer
217    * (yet).
218    */
219   void *(*buffer_map_range)( struct pipe_screen *screen,
220                              struct pipe_buffer *buf,
221                              unsigned offset,
222                              unsigned length,
223                              unsigned usage);
224
225   /**
226    * Notify a range that was actually written into.
227    *
228    * Can only be used if the buffer was mapped with the
229    * PIPE_BUFFER_USAGE_CPU_WRITE and PIPE_BUFFER_USAGE_FLUSH_EXPLICIT flags
230    * set.
231    *
232    * The range is relative to the buffer start, regardless of the range
233    * specified to buffer_map_range. This is different from the
234    * ARB_map_buffer_range semantics because we don't forbid multiple mappings
235    * of the same buffer (yet).
236    *
237    */
238   void (*buffer_flush_mapped_range)( struct pipe_screen *screen,
239                                      struct pipe_buffer *buf,
240                                      unsigned offset,
241                                      unsigned length);
242
243   /**
244    * Unmap buffer.
245    *
246    * If the buffer was mapped with PIPE_BUFFER_USAGE_CPU_WRITE flag but not
247    * PIPE_BUFFER_USAGE_FLUSH_EXPLICIT then the pipe driver will
248    * assume that the whole buffer was written. This is mostly for backward
249    * compatibility purposes and may affect performance -- the state tracker
250    * should always specify exactly what got written while the buffer was
251    * mapped.
252    */
253   void (*buffer_unmap)( struct pipe_screen *screen,
254                         struct pipe_buffer *buf );
255
256   void (*buffer_destroy)( struct pipe_buffer *buf );
257
258   /**
259    * Create a video surface suitable for use as a decoding target by the
260    * driver's pipe_video_context.
261    */
262   struct pipe_video_surface*
263   (*video_surface_create)( struct pipe_screen *screen,
264                            enum pipe_video_chroma_format chroma_format,
265                            unsigned width, unsigned height );
266
267   void (*video_surface_destroy)( struct pipe_video_surface *vsfc );
268
269   /**
270    * Do any special operations to ensure buffer size is correct
271    */
272   void (*update_buffer)( struct pipe_screen *ws,
273                          void *context_private );
274
275   /**
276    * Do any special operations to ensure frontbuffer contents are
277    * displayed, eg copy fake frontbuffer.
278    */
279   void (*flush_frontbuffer)( struct pipe_screen *screen,
280                              struct pipe_surface *surf,
281                              void *context_private );
282
283
284
285   /** Set ptr = fence, with reference counting */
286   void (*fence_reference)( struct pipe_screen *screen,
287                            struct pipe_fence_handle **ptr,
288                            struct pipe_fence_handle *fence );
289
290   /**
291    * Checks whether the fence has been signalled.
292    * \param flags  driver-specific meaning
293    * \return zero on success.
294    */
295   int (*fence_signalled)( struct pipe_screen *screen,
296                           struct pipe_fence_handle *fence,
297                           unsigned flags );
298
299   /**
300    * Wait for the fence to finish.
301    * \param flags  driver-specific meaning
302    * \return zero on success.
303    */
304   int (*fence_finish)( struct pipe_screen *screen,
305                        struct pipe_fence_handle *fence,
306                        unsigned flags );
307
308};
309
310
311#ifdef __cplusplus
312}
313#endif
314
315#endif /* P_SCREEN_H */
316