Initiali commit.

Add st_api.h from
http://www.mail-archive.com/mesa3d-dev@lists.sourceforge.net/msg10792.html.

1 files changed, 237 insertions, 0 deletions

diff --git a/st_api.h b/st_api.h
new file mode 100644
index 0000000..34f8984
--- /dev/null
+++ b/st_api.h
@@ -0,0 +1,237 @@
+/**********************************************************
+ * 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 different state trackers.
+ *
+ * This file has a concept of two types of state trackers API and
+ * co state tracker. The API state tracker implements a client
+ * API used for rendering such as OpenGL or OpenVG. The co state
+ * tracker implements the client API used for createing contexts
+ * and framebuffers, such as EGL and DRI.
+ */
+
+struct pipe_context;
+struct pipe_texture;
+struct pipe_fence_handle;
+
+struct st_visual
+{
+   enum pipe_format color_format;
+   enum pipe_format stencil_format;
+   enum pipe_format depth_format;
+   enum pipe_format accum_format;
+
+   boolean double_buffer;
+};
+
+/**
+ * Used in (un)bint_texture_target.
+ */
+enum st_bind_type
+{
+   ST_TEXTURE_2D,
+   ST_TEXTURE_RECT,
+};
+
+enum st_framebuffer_attachment {
+   ST_SURFACE_FRONT_LEFT,
+   ST_SURFACE_BACK_LEFT,
+   ST_SURFACE_FRONT_RIGHT,
+   ST_SURFACE_BACK_RIGHT,
+   ST_SURFACE_DEPTH_STENCIL,
+};
+
+/**
+ * Represent a windowing system drawable.
+ *
+ * The framebuffer is implemented by the co state tracker and
+ * used by the API state tracker.
+ *
+ * Instead of the winsys pokeing 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
+ * syncronisation primitves, with the exception of a small
+ * atomic flag used for notification of framebuffer dirty status.
+ *
+ * The thread syncronisation is put inside the framebuffer
+ * and only called once the framebuffer has become dirty.
+ */
+struct st_framebuffer
+{
+   struct st_visual *visual;
+
+   /**
+    * Flush the front buffer.
+    *
+    * @att is either FRONT_LEFT or FRONT_RIGHT.
+    */
+   boolean (*flush_front)(struct st_framebuffer *fb,
+                          const enum st_framebuffer_attachment att);
+
+   /**
+    * The api 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.
+    */
+   boolean (*validate)(struct st_framebuffer *fb,
+                       const enum st_framebuffer_attachment *att,
+                       const unsigned count,
+                       struct pipe_texture **out);
+};
+
+/**
+ * Represents a API rendering context.
+ *
+ * This entity is implemented by the API state tracker and used
+ * by the co state tracker.
+ */
+struct st_context
+{
+   /**
+    * API from which this context was created from.
+    */
+   struct st_api *api;
+
+   /**
+    * Available for the co state tracker to use.
+    */
+   void *user_data;
+
+   /**
+    * Invalidate the current textures that was taken from a framebuffer.
+    *
+    * The co st calls this function to let the API context know that it
+    * should update the textures it got from st_framebuffer::validate.
+    * It should do so at the latest time possible. Possible right before
+    * sending triangles to the pipe context.
+    *
+    * For certain platforms this function might be called from a thread
+    * other then the thread that the context is currently bound in, and
+    * must therefore be thread safe. But it is the co st responsibility
+    * to make sure that the framebuffer is bound to the API context and
+    * the API context is current for the duration of this call.
+    *
+    * Thus reducing the sync primitive needed to a single atomic flag.
+    */
+   void (*notify_invalid_framebuffer)(struct st_context *ctx,
+                                      struct st_framebuffer *fb);
+
+   /**
+    * Used to implement GLX_tfp and eglBindTexImage.
+    */
+   int (*bind_texture)(struct st_context *ctx,
+                       struct pipe_texture *tex,
+                       enum st_bind_type target, int level,
+                       enum pipe_format format);
+
+   /**
+    * Used to implement eglReleaseTexImage.
+    */
+   int (*unbind_texture)(struct st_context *ctx,
+                         struct pipe_texture *tex,
+                         enum st_bind_type target, int level);
+
+   /**
+    * Flush all drawing from context to the pipe also flushes the pipe.
+    */
+   void (*flush)(struct st_context *ctx,
+                 unsigned pipe_flush_flags,
+                 struct pipe_fence_handle **fence);
+
+   /**
+    * Used to implement glXCopyContext.
+    */
+   void (*copy)(struct st_context *dst, struct st_context *src, unsigned mask);
+
+   void (*destroy)(struct st_context *ctx);
+};
+
+/**
+ * Dummy function pointer used for get_proc_address.
+ */
+typedef void (*st_proc_t)(void);
+
+/**
+ * Represents a single API such as GL and VG.
+ *
+ * Implemented by the API and used by the co state tracker, the co
+ * state tracker gets this struct from a API dependant function
+ * call that is either dynamicaly loaded or staticaly linked in.
+ */
+struct st_api
+{
+   /**
+    * Create a API rendering context
+    *
+    * XXX: The pipe argument should go away once
+    * the pipe_screen can create contexts.
+    */
+   struct st_context *(*create_context)(struct st_api *api,
+                                        struct pipe_context *pipe,
+                                        const struct st_visual *visual,
+                                        struct st_context *share);
+
+   /**
+    * Bind the context to this thread with draw and read as drawables.
+    */
+   boolean (*make_current)(struct st_api *api,
+                           struct st_context *st,
+                           struct st_framebuffer *draw,
+                           struct st_framebuffer *read);
+
+   /**
+    * Get the currently bound context in this thread.
+    */
+   struct st_context (*get_current)(struct st_api *api);
+
+   /**
+    * Return a API entry point.
+    *
+    * For GL this is the same as _glapi_get_proc_address.
+    */
+   st_proc_t (*get_proc_address)(struct st_api *api, const char *procname);
+
+   void (*destroy)(struct st_api *api);
+};
+
+#endif