summaryrefslogtreecommitdiffstats
path: root/src/gallium/include/state_tracker/st_api.h
blob: bc62a69da378ca99f27b7bd39923d61b492cd335 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
/**********************************************************
 * Copyright 2010 VMware, Inc.  All rights reserved.
 *
 * Permission is hereby granted, free of charge, to any person
 * obtaining a copy of this software and associated documentation
 * files (the "Software"), to deal in the Software without
 * restriction, including without limitation the rights to use, copy,
 * modify, merge, publish, distribute, sublicense, and/or sell copies
 * of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be
 * included in all copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
 * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
 * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 * SOFTWARE.
 *
 **********************************************************/


#ifndef _ST_API_H_
#define _ST_API_H_

#include "pipe/p_compiler.h"
#include "pipe/p_format.h"

/**
 * \file API for communication between state trackers and state tracker
 * managers.
 *
 * While both are state tackers, we use the term state tracker for rendering
 * APIs such as OpenGL or OpenVG, and state tracker manager for window system
 * APIs such as EGL or GLX in this file.
 *
 * This file defines an API to be implemented by both state trackers and state
 * tracker managers.
 */

/**
 * The supported rendering API of a state tracker.
 */
enum st_api_type {
   ST_API_OPENGL,
   ST_API_OPENVG,

   ST_API_COUNT
};

/**
 * The profile of a context.
 */
enum st_profile_type
{
   ST_PROFILE_DEFAULT,			/**< OpenGL compatibility profile */
   ST_PROFILE_OPENGL_CORE,		/**< OpenGL 3.2+ core profile */
   ST_PROFILE_OPENGL_ES1,		/**< OpenGL ES 1.x */
   ST_PROFILE_OPENGL_ES2		/**< OpenGL ES 2.0 */
};

/* for profile_mask in st_api */
#define ST_PROFILE_DEFAULT_MASK      (1 << ST_PROFILE_DEFAULT)
#define ST_PROFILE_OPENGL_CORE_MASK  (1 << ST_PROFILE_OPENGL_CORE)
#define ST_PROFILE_OPENGL_ES1_MASK   (1 << ST_PROFILE_OPENGL_ES1)
#define ST_PROFILE_OPENGL_ES2_MASK   (1 << ST_PROFILE_OPENGL_ES2)

/**
 * Optional API/state tracker features.
 */
enum st_api_feature
{
   ST_API_FEATURE_MS_VISUALS  /**< support for multisample visuals */
};

/* for feature_mask in st_api */
#define ST_API_FEATURE_MS_VISUALS_MASK (1 << ST_API_FEATURE_MS_VISUALS)

/**
 * New context flags for GL 3.0 and beyond.
 *
 * Profile information (core vs. compatibilty for OpenGL 3.2+) is communicated
 * through the \c st_profile_type, not through flags.
 */
#define ST_CONTEXT_FLAG_DEBUG               (1 << 0)
#define ST_CONTEXT_FLAG_FORWARD_COMPATIBLE  (1 << 1)
#define ST_CONTEXT_FLAG_ROBUST_ACCESS       (1 << 2)
#define ST_CONTEXT_FLAG_RESET_NOTIFICATION_ENABLED (1 << 3)
#define ST_CONTEXT_FLAG_NO_ERROR            (1 << 4)

/**
 * Reasons that context creation might fail.
 */
enum st_context_error {
   ST_CONTEXT_SUCCESS = 0,
   ST_CONTEXT_ERROR_NO_MEMORY,
   ST_CONTEXT_ERROR_BAD_API,
   ST_CONTEXT_ERROR_BAD_VERSION,
   ST_CONTEXT_ERROR_BAD_FLAG,
   ST_CONTEXT_ERROR_UNKNOWN_ATTRIBUTE,
   ST_CONTEXT_ERROR_UNKNOWN_FLAG
};

/**
 * Used in st_context_iface->teximage.
 */
enum st_texture_type {
   ST_TEXTURE_1D,
   ST_TEXTURE_2D,
   ST_TEXTURE_3D,
   ST_TEXTURE_RECT
};

/**
 * Available attachments of framebuffer.
 */
enum st_attachment_type {
   ST_ATTACHMENT_FRONT_LEFT,
   ST_ATTACHMENT_BACK_LEFT,
   ST_ATTACHMENT_FRONT_RIGHT,
   ST_ATTACHMENT_BACK_RIGHT,
   ST_ATTACHMENT_DEPTH_STENCIL,
   ST_ATTACHMENT_ACCUM,
   ST_ATTACHMENT_SAMPLE,

   ST_ATTACHMENT_COUNT,
   ST_ATTACHMENT_INVALID = -1
};

/* for buffer_mask in st_visual */
#define ST_ATTACHMENT_FRONT_LEFT_MASK     (1 << ST_ATTACHMENT_FRONT_LEFT)
#define ST_ATTACHMENT_BACK_LEFT_MASK      (1 << ST_ATTACHMENT_BACK_LEFT)
#define ST_ATTACHMENT_FRONT_RIGHT_MASK    (1 << ST_ATTACHMENT_FRONT_RIGHT)
#define ST_ATTACHMENT_BACK_RIGHT_MASK     (1 << ST_ATTACHMENT_BACK_RIGHT)
#define ST_ATTACHMENT_DEPTH_STENCIL_MASK  (1 << ST_ATTACHMENT_DEPTH_STENCIL)
#define ST_ATTACHMENT_ACCUM_MASK          (1 << ST_ATTACHMENT_ACCUM)
#define ST_ATTACHMENT_SAMPLE_MASK         (1 << ST_ATTACHMENT_SAMPLE)

/**
 * Enumerations of state tracker context resources.
 */
enum st_context_resource_type {
   ST_CONTEXT_RESOURCE_OPENGL_TEXTURE_2D,
   ST_CONTEXT_RESOURCE_OPENGL_TEXTURE_3D,
   ST_CONTEXT_RESOURCE_OPENGL_TEXTURE_CUBE_MAP_POSITIVE_X,
   ST_CONTEXT_RESOURCE_OPENGL_TEXTURE_CUBE_MAP_NEGATIVE_X,
   ST_CONTEXT_RESOURCE_OPENGL_TEXTURE_CUBE_MAP_POSITIVE_Y,
   ST_CONTEXT_RESOURCE_OPENGL_TEXTURE_CUBE_MAP_NEGATIVE_Y,
   ST_CONTEXT_RESOURCE_OPENGL_TEXTURE_CUBE_MAP_POSITIVE_Z,
   ST_CONTEXT_RESOURCE_OPENGL_TEXTURE_CUBE_MAP_NEGATIVE_Z,
   ST_CONTEXT_RESOURCE_OPENGL_RENDERBUFFER,
   ST_CONTEXT_RESOURCE_OPENVG_PARENT_IMAGE
};

/**
 * Flush flags.
 */
#define ST_FLUSH_FRONT                    (1 << 0)
#define ST_FLUSH_END_OF_FRAME             (1 << 1)
#define ST_FLUSH_WAIT                     (1 << 2)

/**
 * Value to st_manager->get_param function.
 */
enum st_manager_param {
   /**
    * The dri state tracker on old libGL's doesn't do the right thing
    * with regards to invalidating the framebuffers.
    *
    * For the mesa state tracker that means that it needs to invalidate
    * the framebuffer in glViewport itself.
    */
   ST_MANAGER_BROKEN_INVALIDATE
};

struct pipe_context;
struct pipe_resource;
struct pipe_fence_handle;
struct util_queue_monitoring;

/**
 * Used in st_context_iface->get_resource_for_egl_image.
 */
struct st_context_resource
{
   /* these fields are filled in by the caller */
   enum st_context_resource_type type;
   void *resource;

   /* this is owned by the caller */
   struct pipe_resource *texture;
};

/**
 * Used in st_manager_iface->get_egl_image.
 */
struct st_egl_image
{
   /* this is owned by the caller */
   struct pipe_resource *texture;

   /* format only differs from texture->format for multi-planar (YUV): */
   enum pipe_format format;

   unsigned level;
   unsigned layer;
};

/**
 * Represent the visual of a framebuffer.
 */
struct st_visual
{
   /**
    * Available buffers.  Bitfield of ST_ATTACHMENT_*_MASK bits.
    */
   unsigned buffer_mask;

   /**
    * Buffer formats.  The formats are always set even when the buffer is
    * not available.
    */
   enum pipe_format color_format;
   enum pipe_format depth_stencil_format;
   enum pipe_format accum_format;
   int samples;

   /**
    * Desired render buffer.
    */
   enum st_attachment_type render_buffer;
};


/**
 * Configuration options from driconf
 */
struct st_config_options
{
   boolean disable_blend_func_extended;
   boolean disable_glsl_line_continuations;
   boolean disable_shader_bit_encoding;
   boolean force_glsl_extensions_warn;
   unsigned force_glsl_version;
   boolean force_s3tc_enable;
   boolean allow_glsl_extension_directive_midshader;
   boolean allow_glsl_builtin_variable_redeclaration;
   boolean allow_higher_compat_version;
   boolean glsl_zero_init;
   boolean force_glsl_abs_sqrt;
   unsigned char config_options_sha1[20];
};

/**
 * Represent the attributes of a context.
 */
struct st_context_attribs
{
   /**
    * The profile and minimal version to support.
    *
    * The valid profiles and versions are rendering API dependent.  The latest
    * version satisfying the request should be returned.
    */
   enum st_profile_type profile;
   int major, minor;

   /** Mask of ST_CONTEXT_FLAG_x bits */
   unsigned flags;

   /**
    * The visual of the framebuffers the context will be bound to.
    */
   struct st_visual visual;

   /**
    * Configuration options.
    */
   struct st_config_options options;
};

struct st_context_iface;
struct st_manager;

/**
 * Represent a windowing system drawable.
 *
 * The framebuffer is implemented by the state tracker manager and
 * used by the state trackers.
 *
 * Instead of the winsys poking into the API context to figure
 * out what buffers that might be needed in the future by the API
 * context, it calls into the framebuffer to get the textures.
 *
 * This structure along with the notify_invalid_framebuffer
 * allows framebuffers to be shared between different threads
 * but at the same make the API context free from thread
 * synchronization primitves, with the exception of a small
 * atomic flag used for notification of framebuffer dirty status.
 *
 * The thread synchronization is put inside the framebuffer
 * and only called once the framebuffer has become dirty.
 */
struct st_framebuffer_iface
{
   /**
    * Atomic stamp which changes when framebuffers need to be updated.
    */
   int32_t stamp;

   /**
    * Identifier that uniquely identifies the framebuffer interface object.
    */
   uint32_t ID;

   /**
    * The state tracker manager that manages this object.
    */
   struct st_manager *state_manager;

   /**
    * Available for the state tracker manager to use.
    */
   void *st_manager_private;

   /**
    * The visual of a framebuffer.
    */
   const struct st_visual *visual;

   /**
    * Flush the front buffer.
    *
    * On some window systems, changes to the front buffers are not immediately
    * visible.  They need to be flushed.
    *
    * @att is one of the front buffer attachments.
    */
   boolean (*flush_front)(struct st_context_iface *stctx,
                          struct st_framebuffer_iface *stfbi,
                          enum st_attachment_type statt);

   /**
    * The state tracker asks for the textures it needs.
    *
    * It should try to only ask for attachments that it currently renders
    * to, thus allowing the winsys to delay the allocation of textures not
    * needed. For example front buffer attachments are not needed if you
    * only do back buffer rendering.
    *
    * The implementor of this function needs to also ensure
    * thread safty as this call might be done from multiple threads.
    *
    * The returned textures are owned by the caller.  They should be
    * unreferenced when no longer used.  If this function is called multiple
    * times with different sets of attachments, those buffers not included in
    * the last call might be destroyed.  This behavior might change in the
    * future.
    */
   boolean (*validate)(struct st_context_iface *stctx,
                       struct st_framebuffer_iface *stfbi,
                       const enum st_attachment_type *statts,
                       unsigned count,
                       struct pipe_resource **out);
};

/**
 * Represent a rendering context.
 *
 * This entity is created from st_api and used by the state tracker manager.
 */
struct st_context_iface
{
   /**
    * Available for the state tracker and the manager to use.
    */
   void *st_context_private;
   void *st_manager_private;

   /**
    * The state tracker manager that manages this object.
    */
   struct st_manager *state_manager;

   /**
    * The CSO context associated with this context in case we need to draw
    * something before swap buffers.
    */
   struct cso_context *cso_context;

   /**
    * The gallium context.
    */
   struct pipe_context *pipe;

   /**
    * Destroy the context.
    */
   void (*destroy)(struct st_context_iface *stctxi);

   /**
    * Flush all drawing from context to the pipe also flushes the pipe.
    */
   void (*flush)(struct st_context_iface *stctxi, unsigned flags,
                 struct pipe_fence_handle **fence);

   /**
    * Replace the texture image of a texture object at the specified level.
    *
    * This function is optional.
    */
   boolean (*teximage)(struct st_context_iface *stctxi,
                       enum st_texture_type target,
                       int level, enum pipe_format internal_format,
                       struct pipe_resource *tex, boolean mipmap);

   /**
    * Used to implement glXCopyContext.
    */
   void (*copy)(struct st_context_iface *stctxi,
                struct st_context_iface *stsrci, unsigned mask);

   /**
    * Used to implement wglShareLists.
    */
   boolean (*share)(struct st_context_iface *stctxi,
                    struct st_context_iface *stsrci);

   /**
    * Look up and return the info of a resource for EGLImage.
    *
    * This function is optional.
    */
   boolean (*get_resource_for_egl_image)(struct st_context_iface *stctxi,
                                         struct st_context_resource *stres);

   /**
    * Start the thread if the API has a worker thread.
    * Called after the context has been created and fully initialized on both
    * sides (e.g. st/mesa and st/dri).
    */
   void (*start_thread)(struct st_context_iface *stctxi);

   /**
    * If the API is multithreaded, wait for all queued commands to complete.
    * Called from the main thread.
    */
   void (*thread_finish)(struct st_context_iface *stctxi);
};


/**
 * Represent a state tracker manager.
 *
 * This interface is implemented by the state tracker manager.  It corresponds
 * to a "display" in the window system.
 */
struct st_manager
{
   struct pipe_screen *screen;

   /**
    * Look up and return the info of an EGLImage.
    *
    * This is used to implement for example EGLImageTargetTexture2DOES.
    * The GLeglImageOES agrument of that call is passed directly to this
    * function call and the information needed to access this is returned
    * in the given struct out.
    *
    * @smapi: manager owning the caller context
    * @stctx: caller context
    * @egl_image: EGLImage that caller recived
    * @out: return struct filled out with access information.
    *
    * This function is optional.
    */
   boolean (*get_egl_image)(struct st_manager *smapi,
                            void *egl_image,
                            struct st_egl_image *out);

   /**
    * Query an manager param.
    */
   int (*get_param)(struct st_manager *smapi,
                    enum st_manager_param param);

   /**
    * Call the loader function setBackgroundContext. Called from the worker
    * thread.
    */
   void (*set_background_context)(struct st_context_iface *stctxi,
                                  struct util_queue_monitoring *queue_info);

   /**
    * Destroy any private data used by the state tracker manager.
    */
   void (*destroy)(struct st_manager *smapi);

   /**
    * Available for the state tracker manager to use.
    */
   void *st_manager_private;
};

/**
 * Represent a rendering API such as OpenGL or OpenVG.
 *
 * Implemented by the state tracker and used by the state tracker manager.
 */
struct st_api
{
   /**
    * The name of the rendering API.  This is informative.
    */
   const char *name;

   /**
    * The supported rendering API.
    */
   enum st_api_type api;

   /**
    * The supported profiles.  Tested with ST_PROFILE_*_MASK.
    */
   unsigned profile_mask;

   /**
    * The supported optional features.  Tested with ST_FEATURE_*_MASK.
    */
   unsigned feature_mask;

   /**
    * Destroy the API.
    */
   void (*destroy)(struct st_api *stapi);

   /**
    * Query supported OpenGL versions. (if applicable)
    * The format is (major*10+minor).
    */
   void (*query_versions)(struct st_api *stapi, struct st_manager *sm,
                          struct st_config_options *options,
                          int *gl_core_version,
                          int *gl_compat_version,
                          int *gl_es1_version,
                          int *gl_es2_version);

   /**
    * Create a rendering context.
    */
   struct st_context_iface *(*create_context)(struct st_api *stapi,
                                              struct st_manager *smapi,
                                              const struct st_context_attribs *attribs,
                                              enum st_context_error *error,
                                              struct st_context_iface *stsharei);

   /**
    * Bind the context to the calling thread with draw and read as drawables.
    *
    * The framebuffers might be NULL, or might have different visuals than the
    * context does.
    */
   boolean (*make_current)(struct st_api *stapi,
                           struct st_context_iface *stctxi,
                           struct st_framebuffer_iface *stdrawi,
                           struct st_framebuffer_iface *streadi);

   /**
    * Get the currently bound context in the calling thread.
    */
   struct st_context_iface *(*get_current)(struct st_api *stapi);

   /**
    * Notify the st manager the framebuffer interface object
    * is no longer valid.
    */
   void (*destroy_drawable)(struct st_api *stapi,
                            struct st_framebuffer_iface *stfbi);
};

/**
 * Return true if the visual has the specified buffers.
 */
static inline boolean
st_visual_have_buffers(const struct st_visual *visual, unsigned mask)
{
   return ((visual->buffer_mask & mask) == mask);
}

#endif /* _ST_API_H_ */