Overview

st_api.h defines a new API for use by state trackers and state tracker
managers.  The most significant characteristic of the API is that the state
trackers have direct access to windowing system drawable (st_framebuffer).
Jakob Bornecrantz designs the first version of the API.

Issues

1. Should we separate st_visual for contexts and framebuffers?

   UNRESOLVED:  olv suggests that there should be st_context_config and
   st_framebuffer_config.  They are used to express user's desire (Do I want a
   context capable of multisampling?  Do I want the front buffer of a
   framebuffer to be rendered to?).  Because on modern window systems, the
   buffers of a framebuffer are allocated on demand.  We would like to provide
   necessary information about a framebuffer to the state trackers without
   them resorting to validate callback.  The st_framebuffer_config should
   provide information such as the formats of the various buffers.  Note that
   the information is available from the validate callback.  It is provided
   for saving the memory.

2. Is resource lookup complicated?

   UNRESOLVED:  It is agreed there should be a way to look up both state
   tracker and st manager's resources.  Currently, it requires two calls to
   achieve this.  The st or st manager should lock the resource to have access
   to the underlying data structure and then unlock the resource when done.
   It is possible for them to increase the reference count of the data
   structure so that they can keep using the it even if the resource is
   unlocked.  Plus, there might be no real locking mechanism.  They make
   lock/unlock a bad name.  But it does has the benefit to track the access
   to the resources.

   Another approach is to provide a single lookup_resource call, and make
   functions like eglCreatePbufferFromClientBuffer, which requires a real
   locking mechanism, special cases.

3. Do we want st_api->make_current?

   UNRESOLVED:  olv thinks st_api->make_current should be replaced by
   st_manager_api->get_current_context, st_context->bind_framebuffers, and
   st_api->notify_current_context.  He thinks the maintenance of "current
   context" belongs to the st manager.  What a state tracker cares is the
   binding framebuffers.  If a state tracker needs to have access to the
   current context, it should call st_manager_api->get_current_context.
   Because the current context is accessed in every OpenGL or OpenVG call,
   the st manager notifies the state trackers the current context when it
   is changed.  This gives state trackers a chance to remember the per-thread
   current context internally to provide quick access.

4. Does validate destroy buffers?

   UNRESOLVED:  If validate is called twice with different sets of buffers,
   those not listed in the second call may be destroyed on certain window
   systems.  olv thinks this behavior is internal to the st manager and should
   not be exposed in the interface.  He thinks the buffers should not be
   destroyed because of a call to validate.  Instead, the st manager should
   have enough knowledge to decide when to destroy buffers to save memory.

5. Do we want versioning?

   UNRESOLVED:  Because the state trackers and the state tracker managers may
   be distributed separately (e.g. in the case of EGL), a simple major/minor
   versioning should help avoid mysterious crashes.  By adding some paddings,
   and new callbacks are added to the end of the various structs, it is
   possible to keep the major version fixed for a good while (once we reach
   major version 1).

6. No state tracker or st manager implements this API.

   UNRESOLVED:  olv hopes the design phase should finish soon (in a week or
   two).  There should be some real implementations that help catch any defect
   in the design.  After two or three rounds of design/implement, the API can
   be called usable.  He suggested some relatively dramatic changes basing on
   limited test.  He personally would like to find out if they work as
   expected as soon as possible.