native.h revision fade8a6eb639d633cfdbba4a3ba3aa3cc5c04fa6 
1/*
2 * Mesa 3-D graphics library
3 * Version:  7.8
4 *
5 * Copyright (C) 2009-2010 Chia-I Wu <olv@0xlab.org>
6 *
7 * Permission is hereby granted, free of charge, to any person obtaining a
8 * copy of this software and associated documentation files (the "Software"),
9 * to deal in the Software without restriction, including without limitation
10 * the rights to use, copy, modify, merge, publish, distribute, sublicense,
11 * and/or sell copies of the Software, and to permit persons to whom the
12 * Software is furnished to do so, subject to the following conditions:
13 *
14 * The above copyright notice and this permission notice shall be included
15 * in all copies or substantial portions of the Software.
16 *
17 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
18 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
19 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
20 * BRIAN PAUL BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
21 * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
22 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
23 */
24
25#ifndef _NATIVE_H_
26#define _NATIVE_H_
27
28#include "EGL/egl.h"  /* for EGL native types */
29#include "GL/gl.h" /* for GL types needed by __GLcontextModes */
30#include "GL/internal/glcore.h"  /* for __GLcontextModes */
31
32#include "pipe/p_compiler.h"
33#include "pipe/p_screen.h"
34#include "pipe/p_context.h"
35#include "pipe/p_state.h"
36
37#include "native_modeset.h"
38
39/**
40 * Only color buffers are listed.  The others are allocated privately through,
41 * for example, st_renderbuffer_alloc_storage().
42 */
43enum native_attachment {
44   NATIVE_ATTACHMENT_FRONT_LEFT,
45   NATIVE_ATTACHMENT_BACK_LEFT,
46   NATIVE_ATTACHMENT_FRONT_RIGHT,
47   NATIVE_ATTACHMENT_BACK_RIGHT,
48
49   NUM_NATIVE_ATTACHMENTS
50};
51
52enum native_param_type {
53   /*
54    * Return TRUE if window/pixmap surfaces use the buffers of the native
55    * types.
56    */
57   NATIVE_PARAM_USE_NATIVE_BUFFER
58};
59
60/**
61 * Enumerations for probe results.
62 */
63enum native_probe_result {
64   NATIVE_PROBE_UNKNOWN,
65   NATIVE_PROBE_FALLBACK,
66   NATIVE_PROBE_SUPPORTED,
67   NATIVE_PROBE_EXACT,
68};
69
70/**
71 * A probe object for display probe.
72 */
73struct native_probe {
74   int magic;
75   EGLNativeDisplayType display;
76   void *data;
77
78   void (*destroy)(struct native_probe *nprobe);
79};
80
81struct native_surface {
82   /**
83    * Available for caller's use.
84    */
85   void *user_data;
86
87   void (*destroy)(struct native_surface *nsurf);
88
89   /**
90    * Swap the front and back buffers so that the back buffer is visible.  It
91    * is no-op if the surface is single-buffered.  The contents of the back
92    * buffer after swapping may or may not be preserved.
93    */
94   boolean (*swap_buffers)(struct native_surface *nsurf);
95
96   /**
97    * Make the front buffer visible.  In some native displays, changes to the
98    * front buffer might not be visible immediately and require manual flush.
99    */
100   boolean (*flush_frontbuffer)(struct native_surface *nsurf);
101
102   /**
103    * Validate the buffers of the surface.  textures, if not NULL, points to an
104    * array of size NUM_NATIVE_ATTACHMENTS and the returned textures are owned
105    * by the caller.  A sequence number is also returned.  The caller can use
106    * it to check if anything has changed since the last call. Any of the
107    * pointers may be NULL and it indicates the caller has no interest in those
108    * values.
109    *
110    * If this function is called multiple times with different attachment
111    * masks, those not listed in the latest call might be destroyed.  This
112    * behavior might change in the future.
113    */
114   boolean (*validate)(struct native_surface *nsurf, uint attachment_mask,
115                       unsigned int *seq_num, struct pipe_texture **textures,
116                       int *width, int *height);
117
118   /**
119    * Wait until all native commands affecting the surface has been executed.
120    */
121   void (*wait)(struct native_surface *nsurf);
122};
123
124struct native_config {
125   /* __GLcontextModes should go away some day */
126   __GLcontextModes mode;
127   enum pipe_format color_format;
128   enum pipe_format depth_format;
129   enum pipe_format stencil_format;
130
131   /* treat it as an additional flag to mode.drawableType */
132   boolean scanout_bit;
133};
134
135/**
136 * A pipe winsys abstracts the OS.  A pipe screen abstracts the graphcis
137 * hardware.  A native display consists of a pipe winsys, a pipe screen, and
138 * the native display server.
139 */
140struct native_display {
141   /**
142    * The pipe screen of the native display.
143    *
144    * Note that the "flush_frontbuffer" and "update_buffer" callbacks will be
145    * overridden.
146    */
147   struct pipe_screen *screen;
148
149   /**
150    * Available for caller's use.
151    */
152   void *user_data;
153
154   void (*destroy)(struct native_display *ndpy);
155
156   /**
157    * Query the parameters of the native display.
158    *
159    * The return value is defined by the parameter.
160    */
161   int (*get_param)(struct native_display *ndpy,
162                    enum native_param_type param);
163
164   /**
165    * Get the supported configs.  The configs are owned by the display, but
166    * the returned array should be free()ed.
167    *
168    * The configs will be converted to EGL config by
169    * _eglConfigFromContextModesRec and validated by _eglValidateConfig.
170    * Those failing to pass the test will be skipped.
171    */
172   const struct native_config **(*get_configs)(struct native_display *ndpy,
173                                               int *num_configs);
174
175   /**
176    * Test if a pixmap is supported by the given config.  Required unless no
177    * config has GLX_PIXMAP_BIT set.
178    *
179    * This function is usually called to find a config that supports a given
180    * pixmap.  Thus, it is usually called with the same pixmap in a row.
181    */
182   boolean (*is_pixmap_supported)(struct native_display *ndpy,
183                                  EGLNativePixmapType pix,
184                                  const struct native_config *nconf);
185
186
187   /**
188    * Create a window surface.  Required unless no config has GLX_WINDOW_BIT
189    * set.
190    */
191   struct native_surface *(*create_window_surface)(struct native_display *ndpy,
192                                                   EGLNativeWindowType win,
193                                                   const struct native_config *nconf);
194
195   /**
196    * Create a pixmap surface.  Required unless no config has GLX_PIXMAP_BIT
197    * set.
198    */
199   struct native_surface *(*create_pixmap_surface)(struct native_display *ndpy,
200                                                   EGLNativePixmapType pix,
201                                                   const struct native_config *nconf);
202
203   /**
204    * Create a pbuffer surface.  Required unless no config has GLX_PBUFFER_BIT
205    * set.
206    */
207   struct native_surface *(*create_pbuffer_surface)(struct native_display *ndpy,
208                                                    const struct native_config *nconf,
209                                                    uint width, uint height);
210
211   const struct native_display_modeset *modeset;
212};
213
214/**
215 * The handler for events that a native display may generate.  The events are
216 * generated asynchronously and the handler may be called by any thread at any
217 * time.
218 */
219struct native_event_handler {
220   /**
221    * This function is called when a surface needs to be validated.
222    */
223   void (*invalid_surface)(struct native_display *ndpy,
224                           struct native_surface *nsurf,
225                           unsigned int seq_num);
226};
227
228/**
229 * Test whether an attachment is set in the mask.
230 */
231static INLINE boolean
232native_attachment_mask_test(uint mask, enum native_attachment att)
233{
234   return !!(mask & (1 << att));
235}
236
237/**
238 * Return a probe object for the given display.
239 *
240 * Note that the returned object may be cached and used by different native
241 * display modules.  It allows fast probing when multiple modules probe the
242 * same display.
243 */
244struct native_probe *
245native_create_probe(EGLNativeDisplayType dpy);
246
247/**
248 * Probe the probe object.
249 */
250enum native_probe_result
251native_get_probe_result(struct native_probe *nprobe);
252
253const char *
254native_get_name(void);
255
256struct native_display *
257native_create_display(EGLNativeDisplayType dpy,
258                      struct native_event_handler *handler);
259
260#endif /* _NATIVE_H_ */
261