timeline.txt 5.94 KB
Newer Older
1 2
Timeline view design document (c) 2005 Edward Hervey

3
* How is the timeline handled in Pitivi ?
4 5 6 7 8 9 10 11

  The timeline follows the "View - Model - Data" design.
   _ Data is the gnonlin timeline (GnlTimeline)
   _ Model is the part which will be saved by pitivi
   _ View is the UI

  This design allows pitivi to have different 'views':
   _ The 'Simple' View : à la iMovie
12
   _ The 'Full' View : Allows every possible composition
13 14 15 16 17 18 19
  

* Simple View

  This view displays everything on one line. It is aimed to be very simple to
  use.

20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46
 * Display

   * Timeline
     _ The timeline contains one line, which acts as a summary of the underlying
     timeline.

   * Sources
     _ All have the same width (which doesn't mean it's fixed)
     _ Display a thumbnail of the source if it's video
     _ In normal situations, the sources follow each others without any gaps.
     _ Special Cases:
       * Gap between two sources : 
	 => Black source (which can be removed)
       * Source A overlaps part of Source B:
	 => Display normally
       * Source A is over and "inside" Source B
	 (A.start > B.start, A.stop < B.stop):
	 => Display A inside B , but it cannot be moved in the simple View

   * Effects
     _ Effects applied on one source entirely have their icons displayed in the
       corner of the source

   * Transitions
     _ Show like a source (maybe half-width)
     _ Represent somewhat differently

47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85
 * Actions

   The simple view allows only SOME actions amongst all those available through
   the model:

   * Add a Source
     _ Sources are added before or after a source.
     _ Sources CANNOT be added next to a transition.
     _ Sources CAN be added next to an effect.
     _ Once the source is added, move the following sources later in time.
     _ If the source has audio, add the audio source.

   * Move a Source
     _ follows the same rules as 'Add a Source'
     _ If the source has audio, move the audio source too.

   * Remove a Source
     _ "Collapse" the following sources
     _ If the source has audio, remove the audio source too.

   * Add an effect
     _ An effect can only be added to one source
     _ There can only be at most one effect on each source

   * Remove an effect

   * Add a transition
     _ Can ONLY go between two sources
     _ If the adjacent sources have audio, apply an audio transition to the
     audio sources.
     _ Has a given duration on each source
     _ Overlaps the two sources
     _ move the following sources back in time

   * Remove a transition
     _ if there's an audio transition, remove it too
     _ Move the following sources back into place (just after the first source)


86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225
* Complex View

  * This is a representation of the actual model

********************************************************************************

* Model

  The model must:
  _ Have objects that offer a simpler interface to gnonlin.
  _ Allow the views to do all the actions they wish to do.


* Object Hierarchy

  Object
   |
   +---- Source
   |	   |
   |	   +---- FileSource
   |	   |
   |	   +---- LiveSource
   |	   |
   |	   +---- Composition
   |		   |
   |		   +---- Group
   |
   +---- Effect
	   |
	   +---- Simple Effect (1->1)
	   |
	   +---- Transition
	   |
	   +---- Complex Effect (N->1)

  * Object
    Base class for all timeline objects

    * Properties
      _ Start/Stop Time
      _ Media Type (None, Audio, Video)
      _ Gnonlin Object
      _ Linked Object
	_ Can be None
	_ Must have same duration
      _ Brother Object
	_ This is the same object but with the other media_type
      _ Factory containing more info on the object

    * Signals
      start-stop-changed : uint64 start, uint64 stop
      linked-changed : linked_object

    * Methods
      link_object(object)
      unlink_object(object)
      relink_brother(object)
      get_brother(object)
      set_start_stop_time(start, stop)

    * Virtual methods
      _make_gnl_object()
      _make_brother()

  * Source
    Base class for all sources (0 input, 1 output)

    * Implemented Methods
      _make_gnl_object()

  * FileSource
    Seekable sources (mostly files)
    
    * Properties
      _ Media Start/Stop Time

    * Methods
      set_media_start_stop_time(mediastart, mediastop)

    * Implemented methods
      _make_brother()

  * LiveSource
    Non-seekable sources (like cameras)

  * Composition
    Combines Source(s) and Effect(s)
    _ Sets the priority of the GnlObject(s) contained within
    _ Effects have always got priorities higher than the sources
    _ Can contain global effects that have the highest priority
      _ Those global effect spread the whole duration of the composition
    _ Simple effects can overlap each other
    _ Complex Effect(s) have a lower priority than Simple Effect(s)
      _ For sanity reasons, Complex Effect(s) can't overlap each other
    _ Transitions have the lowest effect priority
    _ Source(s) contained in it follow each other if possible
    _ Source can overlap each other
      _ Knows the "visibility" of the sources contained within
    
    * Sandwich view example (top: high priority):
	     [ Global Simple Effect(s) (RGB, YUV, Speed,...)	]
	     [ Simple Effect(s), can be several layers		]
	     [ Complex Effect(s), non-overlapping		]
	     [ Transition(s), non-overlapping			]
	     [ Layers of sources				]

    * Properties:
      _ Global Simple Effect(s) (Optionnal)
      _ Simple Effect(s)
      _ Complex Effect(s)
      _ Transition(s)

    * Methods:
      add_global_effect(effect, order)
      remove_global_effect(effect)
      add_simple_effect(effect, order)
      remove_simple_effect(effect)
      add_transition(transition)
      remove_transition(transition)
      add_source(source, position)
      remove_source(source)
      
    * Implemented Methods:
      _make_gnl_object()

  * Group
    Top-level composition

  * Effect
    Base class for effects
    Belongs to a Composition

  * Simple Effect
    Only has 1 input

  * Transition
    Has 2 inputs, considered as begin and end sources

  * Complex Effect
    Has n inputs