path: root/st_api.h

/**********************************************************
 * 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 entry points of the state trackers.
 */
#define ST_MODULE_OPENGL_SYMBOL      "st_module_OpenGL"
#define ST_MODULE_OPENGL_ES1_SYMBOL  "st_module_OpenGL_ES1"
#define ST_MODULE_OPENGL_ES2_SYMBOL  "st_module_OpenGL_ES2"
#define ST_MODULE_OPENVG_SYMBOL      "st_module_OpenVG"

/**
 * The supported rendering API of a state tracker.
 */
enum st_module_api {
   ST_MODULE_OPENGL,
   ST_MODULE_OPENGL_ES1,
   ST_MODULE_OPENGL_ES2,
   ST_MODULE_OPENVG,
};

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

/**
 * Available attachments of framebuffer.
 */
enum st_framebuffer_attachment {
   ST_FRAMEBUFFER_FRONT_LEFT,
   ST_FRAMEBUFFER_BACK_LEFT,
   ST_FRAMEBUFFER_FRONT_RIGHT,
   ST_FRAMEBUFFER_BACK_RIGHT,
   ST_FRAMEBUFFER_DEPTH_STENCIL,
   ST_FRAMEBUFFER_ACCUM,
   ST_FRAMEBUFFER_SAMPLE,
};

/* for buffer_mask in st_visual */
#define ST_FRAMEBUFFER_FRONT_LEFT_MASK  (1 << ST_FRAMEBUFFER_FRONT_LEFT)
#define ST_FRAMEBUFFER_BACK_LEFT_MASK   (1 << ST_FRAMEBUFFER_FRONT_RIGHT)
#define ST_FRAMEBUFFER_FRONT_RIGHT_MASK (1 << ST_FRAMEBUFFER_FRONT_RIGHT)
#define ST_FRAMEBUFFER_BACK_RIGHT_MASK  (1 << ST_FRAMEBUFFER_BACK_RIGHT)
#define ST_FRAMEBUFFER_DEPTH_STENCIL    (1 << ST_FRAMEBUFFER_DEPTH_STENCIL)
#define ST_FRAMEBUFFER_ACCUM_MASK       (1 << ST_FRAMEBUFFER_ACCUM)
#define ST_FRAMEBUFFER_SAMPLE_MASK      (1 << ST_FRAMEBUFFER_SAMPLE)

enum st_manager_resource_type {
   ST_MANAGER_RESOURCE_EGL_IMAGE,   /* return struct pipe_texture */
};

enum st_context_resource_type {
   /* all of them return struct pipe_texture */
   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,
};

struct pipe_context;
struct pipe_texture;
struct pipe_fence_handle;

struct st_visual
{
   /**
    * Available buffers.  Tested with ST_FRAMEBUFFER_*_MASK.
    */
   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_framebuffer_attachment render_buffer;
};

/**
 * Represent a windowing system drawable.
 *
 * The framebuffer is implemented by the state tracker manager and
 * used by the state trackers.
 *
 * 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
{
   const struct st_visual *visual;

   /**
    * Flush the front buffer.
    *
    * @att is either FRONT_LEFT or FRONT_RIGHT.
    */
   boolean (*flush_front)(struct st_framebuffer *stfb,
                          enum st_framebuffer_attachment 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_framebuffer *stfb,
                       const enum st_framebuffer_attachment *statts,
                       unsigned count,
                       struct pipe_texture **out);

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

/**
 * Represent a rendering context.
 *
 * This entity is created from st_api and used by the state tracker manager.
 */
struct st_context
{
   /**
    * Lock and unlock a state tracker context resource.
    *
    * This gives access to the underlying data structure of a state tracker
    * context resource.  Unless there is some mechanism not defined here that
    * can lengthen the lifetime of the data structure, it is valid only until
    * unlocked.
    */
   void *(*lock_resource)(struct st_context *stctx,
		          enum st_context_resource_type type, void *res);
   void (*unlock_resource)(struct st_context *stctx,
		           enum st_context_resource_type type, void *res);

   /**
    * Invalidate the current textures that was taken from a framebuffer.
    *
    * The state tracker manager calls this function to let the rendering
    * 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
    * than the thread that the context is currently bound in, and must
    * therefore be thread safe. But it is the state tracker manager's
    * responsibility to make sure that the framebuffer is bound to the 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 *stctx,
                                      struct st_framebuffer *stfb);

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

   /**
    * Flush all drawing from context to the pipe also flushes the pipe.
    */
   void (*flush)(struct st_context *stctx,
                 unsigned pipe_flush_flags,
                 struct pipe_fence_handle **fence);

   /**
    * Used to implement glXCopyContext.
    */
   void (*copy)(struct st_context *stctx, struct st_context *stsrc,
		unsigned mask);

   void (*destroy)(struct st_context *stctx);

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

/**
 * Dummy function pointer used for get_proc_address.
 */
typedef void (*st_proc_t)(void);

/**
 * 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
{
   /**
    * Lock and unlock a state tracker manager resource.
    *
    * This gives access to the underlying data structure of a state tracker
    * manager resource.  Unless there is some mechanism not defined here that
    * can lengthen the lifetime of the data structure, it is valid only until
    * unlocked.
    */
   void *(*lock_resource)(struct st_manager *smapi,
		          enum st_manager_resource_type type, void *res);
   void (*unlock_resource)(struct st_manager *smapi,
		           enum st_manager_resource_type type, void *res);
};

/**
 * Represent a rendering API such as OpenGL or OpenVG.
 *
 * Implemented by the state tracker and used by the state tracker manager.
 */
struct st_api
{
   /**
    * Return true if the visual is supported by the state tracker.
    */
   boolean (*is_visual_supported)(struct st_api *stapi,
                                  const struct st_visual *visual);

   /**
    * Create a rendering context.
    *
    * XXX: The pipe argument should go away once
    * the pipe_screen can create contexts.
    * XXX: Is visual needed?
    */
   struct st_context *(*create_context)(struct st_api *stapi,
                                        struct st_manager *smapi,
                                        struct pipe_context *pipe,
                                        const struct st_visual *visual,
                                        struct st_context *stshare);

   /**
    * Bind the context to this thread with draw and read as drawables.
    */
   boolean (*make_current)(struct st_api *stapi,
                           struct st_context *stctx,
                           struct st_framebuffer *stdraw,
                           struct st_framebuffer *stread);

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

   /**
    * 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 *stapi, const char *procname);

   void (*destroy)(struct st_api *stapi);
};

/**
 * Represent a state tracker.
 *
 * This is the entry point of a state tracker.
 */
struct st_module
{
   enum st_module_api api;
   struct st_api *(*create_api)(void);
};

/**
 * 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);
}

/* these symbols may need to be dynamically lookup up */
extern PUBLIC const struct st_module st_module_OpenGL;
extern PUBLIC const struct st_module st_module_OpenGL_ES1;
extern PUBLIC const struct st_module st_module_OpenGL_ES2;
extern PUBLIC const struct st_module st_module_OpenVG;

#endif /* _ST_API_H_ */