/**********************************************************
 * 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.
 */

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 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
{
   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);

   /**
    * 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
{
   /**
    * 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 *ctx,
                                      struct st_framebuffer *fb);

   /**
    * Replace the texutre image of a texture object at the specified level.
    *
    * This function is optional.
    */
   boolean (*teximage)(struct st_context *ctx, enum st_bind_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 *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);

/**
 * Represent a rendering API such as OpenGL or OpenVG.
 *
 * Implemented by the state tracker and used by the state tracker manager.
 */
struct st_api
{
   /**
    * Create a 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