[cogl/wip/outputs: 71/71] stash

[Robert Bragg <rbragg src gnome org>]

commit 372e064dd15d2b140b6252733699da35ecc251cc
Author: Robert Bragg <robert linux intel com>
Date:   Mon Aug 19 11:36:29 2013 +0100

    stash

 cogl/winsys/cogl-winsys-egl-kms.c |   81 ++++++++++++++++++++++++++----------
 1 files changed, 58 insertions(+), 23 deletions(-)
---
diff --git a/cogl/winsys/cogl-winsys-egl-kms.c b/cogl/winsys/cogl-winsys-egl-kms.c
index 950dc92..98fb172 100644
--- a/cogl/winsys/cogl-winsys-egl-kms.c
+++ b/cogl/winsys/cogl-winsys-egl-kms.c
@@ -1322,52 +1322,87 @@ ROLL_BACK:
        *    an output configuration associating the framebuffer with
        *    a hardware overlay?
        * A: In this case we'll see that kms_output->overlays is NULL.
-       *    We can lock the front buffer and set it as the ->next_bo.
-       *    If ->next_bo is already set then we can release ->next_bo
-       *    and lock the new front buffer. XXX: what about issuing
-       *    a _FRAME_SYNC event for the previous frame?
+       *    We lock the front buffer, set it on ->next_bo and directly
+       *    call page_flip_handler() to behave as if the flip
+       *    completed immediately. This will make sure we issue a
+       *    _FRAME_SYNC event for the swap and move the bo to
+       *    ->current_bo.
        *
-       *    How this relates to display configuration:
-       *    --
-       *    During a _commit we always check that a source either has
-       *    a valid ->current_bo or ->next_bo (otherwise we report an
-       *    error) since we can't set a mode without a framebuffer and
-       *    we don't want to be automatically allocating place holder
+       * Q: How do we _commit an overlay configuration?
+       * A: During a _commit we always check that a source has a valid
+       *    ->next_bo or ->current_bo (otherwise we report an error)
+       *    since we can't set a mode without a framebuffer and we
+       *    don't want to be automatically allocating place holder
        *    framebuffers in corner cases or displaying undefined
        *    buffer contents.
        *
-       *    If ->current_bo is set then we assume there is no
-       *    rendering outstanding for that buffer and always use that
-       *    buffer when calling drmModeSetCrtc. If we need to call
-       *    drmModeSetCrtc() and ->current_bo is not set then we
-       *    explicitly synchronize with the GPU to make sure all
-       *    rendering to ->next_bo is complete before calling
-       *    drmModeSetCrtc().
+       *    If we need to call drmModeSetCrtc() we will pass ->next_bo
+       *    if available, otherwise ->current_bo.
        *
-       *    If ->current_bo and ->next_bo are set when calling
-       *    drmModeSetCrtc then we also call drmModePageFlip() to post
-       *    ->next_bo.
+       *    We always assume there could be outstanding rendering
+       *    associated with the chosen bo when calling drmModeSetCrtc()
+       *    and so we explicitly synchronize with the GPU to make sure
+       *    all rendering to the buffer is complete first.
+       *
+       *    If we are using ->next_bo that implies there is currently
+       *    a pending flip. We should mark the pending flip as a
+       *    "stale" flip by incrementing ->stale_flips++. Later when we
+       *    reach page_flip_handler() we will check the ->stale_flips
+       *    counter before decrementing it and whenever it is set we
+       *    should only make sure to issue any necessary _FRAME_SYNC
+       *    events but we should avoid making any updates to
+       *    ->current_bo/->next_bo pointers.
+       *
+       *XXX: why does stale_flips need to be a counter instead of just
+       *     a boolean
        *
        *    After successfully calling drmModeSetCrtc() then we insert
        *    a reference to the overlay in kms_onscreen->overlays.
        *
-       * Q: What are the semantics for committing a configuration
-       *    while there are pending page flips?
+       * Q: what if there is an error when calling drmModeSetCrtc?
+       * A: We roll-back the whole configuration
+       *
+       * Q: What are the semantics for calling drmModeSetCrtc while
+       *    there are pending page flips?
        * A: Looking at the intel drm driver it looks like setting
        *    a mode starts by disabling the crtc, which involves
        *    waiting for pending flips so I think we can assume
        *    page flip events will *always* be delivered by drm.
        *
+       * Q: What should the semantics of synchronizing a swap be when
+       *    a framebuffer is associated with multiple overlays?
+       * A: Currently we wait for all flip events for all overlays
+       *    but we should instead just wait for a flip event from
+       *    one overlay. We can add api later to choose what the
+       *    primary overlay is or even change this behaviour.
+       *
        * Q: When do we remove references from the
        *    kms_onscreen->overlays list?
        * A: XXX
        *
        * Q: What happens in _swap_buffers when the onscreen is
        *    associated with one or more overlays?
-       * A: iterate through each overlay
+       * A: We iterate through each overlay that is associated with
+       *    the onscreen framebuffer and call drmModePageFlip()
+       *
+       *    For the first overlay we pass DRM_MODE_PAGE_FLIP_EVENT
+       *    so we get a page flip event but not for the others.
+       * XXX: should we maybe just use drmModeSetCrtc() instead of
+       * drmModePageFlip() for the other overlays? If we have
+       * one 100hz display and a 60hz display then if we issue a
+       * page-flip to the 60hz display for every flip of the 100hz
+       * display then we'll quickly build up a back log.
        *
        * Q: How do we deal with roll-back when this is the first
        *    configuration to be committed?
+       * A: We should be assuming that update_outputs has been
+       *    called before any configuration so we should know the
+       *    previous state.
+       *
+       * Q: What if we disassociate a framebuffer from an overlay
+       *    while it still has a pending flip? (considering what
+       *    might go wrong if we then immediately tried to associate
+       *    the framebuffer with a different overlay)
        * A: XXX
        *
        * Q: How do we deal with an error in drmModePageFlip() also