From fde7de68ea6e06718d5969c08256fcc66ed635ff Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Joan=20Sol=C3=A0?= <jsola@iri.upc.edu>
Date: Wed, 14 Aug 2019 11:36:54 +0200
Subject: [PATCH] Add some documentation

---
 src/processor/processor_motion.cpp | 79 ++++++++++++++++++++++++++++++
 1 file changed, 79 insertions(+)

diff --git a/src/processor/processor_motion.cpp b/src/processor/processor_motion.cpp
index 432ba0d87..db24a7c40 100644
--- a/src/processor/processor_motion.cpp
+++ b/src/processor/processor_motion.cpp
@@ -92,6 +92,31 @@ void ProcessorMotion::processCapture(CaptureBasePtr _incoming_ptr)
 
         case RUNNING_WITH_PACK_BEFORE_ORIGIN :
         {
+
+            /*
+             * Legend:
+             *    * : any frame or keyframe
+             *    x : any capture
+             *    k : arriving keyframe
+             *    o : origin capture
+             *    l : last capture
+             *    e : existing capture  -> new KF splits its buffer in two parts
+             *    n : new capture       -> part of the split buffer will be given to this
+             *  --- : buffer history
+             *
+             * Trajectory before the KF, and arriving KF 'k'
+             *
+             *          k
+             *    * ========= * === ... === * ========= *
+             *    x ----------e     ... ----o ----------l
+             *
+             * Trajectory after the KF, and arriving KF 'k'
+             *
+             *          k
+             *    * === * === * === ... === * ========= *
+             *    x ----n ----e     ... ----o ----------l
+             */
+
             // extract pack elements
             FrameBasePtr keyframe_from_callback = pack->key_frame;
             TimeStamp ts_from_callback = keyframe_from_callback->getTimeStamp();
@@ -147,6 +172,35 @@ void ProcessorMotion::processCapture(CaptureBasePtr _incoming_ptr)
 
         case RUNNING_WITH_PACK_AFTER_ORIGIN :
         {
+            /*
+             * Legend:
+             *    * : any frame or keyframe
+             *    x : any capture
+             *    k : arriving keyframe
+             *    o : origin capture
+             *    l : last capture      -> new KF splits its buffer in two parts
+             *    n : new capture       -> part of the split buffer will be given to this
+             *  --- : buffer history
+             *
+             * Trajectory before the KF, and arriving KF 'k'
+             *
+             *                      k
+             *    * ========= * ========= *
+             *    x ----------o ----------l
+             *
+             * Trajectory after the KF, and arriving KF 'k'
+             *
+             *                      k
+             *    * ========= * === * === *
+             *    x ----------o ----n ----l
+             *
+             * Trajectory after the KF, and after reset
+             *
+             *                      k
+             *    * ========= * === * === *
+             *    x ----------x ----o ----l
+             */
+
             // extract pack elements
             FrameBasePtr keyframe_from_callback = pack->key_frame;
             TimeStamp    ts_from_callback       = keyframe_from_callback->getTimeStamp();
@@ -200,6 +254,31 @@ void ProcessorMotion::processCapture(CaptureBasePtr _incoming_ptr)
 
     if (permittedKeyFrame() && voteForKeyFrame())
     {
+        /*
+         * Legend:
+         *    * : any keyframe
+         *    + : last frame
+         *    x : any capture
+         *    o : origin capture
+         *    l : last capture
+         *    i : incoming capture
+         *    e : existing capture  -> new KF splits its buffer in two parts
+         *    n : new capture       -> part of the split buffer will be given to this
+         *  --- : buffer history
+         *
+         * Trajectory before the KF
+         *
+         *    * ========= * ========= +
+         *    x ----------o ----------l   i
+         *
+         * Trajectory after creating KF at last and reset
+         *
+         *    * ========= * ========= * = +
+         *    x ----------x ----------o --l
+         *
+         */
+
+
         // Set the frame of last_ptr as key
         auto key_frame_ptr = last_ptr_->getFrame();
         key_frame_ptr->setKey();
-- 
GitLab