more display documentation

1 files changed, 25 insertions, 10 deletions

diff --git a/src/display.h b/src/display.h
index a6c9024..8839a07 100644
--- a/src/display.h
+++ b/src/display.h
@@ -26,13 +26,22 @@ enum class AnimationType : uint8_t {
  */
 struct animation {
 	/**
-	 * Specific kind of animation described in this struct. Controls the
+	 * Type of patern/animation described in this struct. Controls the
 	 * behaviour of Display::multiplex() and Display::update().
 	 */
 	AnimationType type;
 
 	/**
-	 * Length of data in bytes
+	 * Length of animation in bytes. Also controls the behaviour of
+	 * Display::update().
+	 *
+	 * For length <= 128, the whole animation is stored in data and
+	 * Display::update() simply traverses the data array.
+	 *
+	 * For length > 128, only up to 128 bytes of animation data are stored
+	 * in data. When Display::update() reaches the end of the array, it will
+	 * use Storage::loadChunk() to load the next 128 byte chunk of animation
+	 * data into the data array.
 	 */
 	uint16_t length;
 
@@ -43,7 +52,7 @@ struct animation {
 	uint8_t speed;
 
 	/**
-	 * Delay after the last text symbol / animation frame. Not yet supported.
+	 * Delay after the last text symbol / animation frame.
 	 */
 	uint8_t delay;
 
@@ -53,11 +62,13 @@ struct animation {
 	uint8_t direction;
 
 	/**
-	 * * If type == AnimationType::TEXT: character array pointing to the
+	 * * If type == AnimationType::TEXT: pointer to an arary containing the
 	 *   animation text in standard ASCII format (+ special font chars)
 	 * * If type == AnimationType::FRAMES: Frame array. Each element encodes
 	 *   a display column (starting with the leftmost one), each group of
 	 *   eight elements is a frame.
+	 *
+	 * The data array must always hold at least 128 elements.
 	 */
 	uint8_t *data;
 };
@@ -66,7 +77,7 @@ typedef struct animation animation_t;
 
 /**
  * Controls the display. Handles multiplexing, scrolling and supports loading
- * arbitrary animations.
+ * arbitrary animations. Also handles partial animations and chunk loading.
  */
 class Display {
 	private:
@@ -90,14 +101,14 @@ class Display {
 		Display();
 
 		/**
-		 * Enable the display driver.
+		 * Enables the display driver.
 		 * Configures ports B and D as output and enables the display
-		 * timer and interrupt.
+		 * timer and corresponding interrupt.
 		 */
 		void enable(void);
 
 		/**
-		 * Disable the display driver.
+		 * Disables the display driver.
 		 * Turns off both the display itself and the display timer.
 		 */
 		void disable(void);
@@ -124,8 +135,12 @@ class Display {
 		void update(void);
 
 		/**
-		 * Set the active animation to be shown on the display. Automatically
-		 * calls reset().
+		 * Sets the active animation to be shown on the display. Automatically
+		 * calls reset(). If direction == 1, uses Storage::loadChunk() to
+		 * load the last 128 byte-chunk of anim (so that the text can start
+		 * scrolling from its last position). If direction == 0, the first
+		 * 128 bytes of animation data are expected to already be present in
+		 * anim->data.
 		 *
 		 * @param anim active animation. Note that the data is not copied,
 		 *        so anim has to be kept in memory until a new one is loaded