Add DESIGN.

1 files changed, 77 insertions, 0 deletions

diff --git a/DESIGN b/DESIGN
new file mode 100644
index 0000000..15a7c0b
--- /dev/null
+++ b/DESIGN
@@ -0,0 +1,77 @@
+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_context->make_current?
+
+   UNRESOLVED:  olv thinks st_context->make_current should be replaced by
+   st_manager_api->get_current_context, st_framebuffer->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.