From 3057db60ff2113f38e9481d003abc6f8a3dcd538 Mon Sep 17 00:00:00 2001
From: Michael Jumper <mike.jumper@guac-dev.org>
Date: Sun, 18 Oct 2015 22:07:01 -0700
Subject: [PATCH] GUAC-1354: Add base Guacamole.VideoPlayer (no codec
 implementations at present). Allow custom video codec implementations via
 onvideo callback on Guacamole.Client.

---
 .../src/main/webapp/modules/Client.js         |  74 ++++++++----
 .../src/main/webapp/modules/Display.js        |  12 +-
 .../src/main/webapp/modules/VideoPlayer.js    | 111 ++++++++++++++++++
 3 files changed, 165 insertions(+), 32 deletions(-)
 create mode 100644 guacamole-common-js/src/main/webapp/modules/VideoPlayer.js

diff --git a/guacamole-common-js/src/main/webapp/modules/Client.js b/guacamole-common-js/src/main/webapp/modules/Client.js
index 894888738..463049687 100644
--- a/guacamole-common-js/src/main/webapp/modules/Client.js
+++ b/guacamole-common-js/src/main/webapp/modules/Client.js
@@ -85,6 +85,14 @@ Guacamole.Client = function(tunnel) {
      */
     var audioPlayers = {};
 
+    /**
+     * All video players currently in use by the client. Initially, this will
+     * be empty, but video players may be allocated by the server upon request.
+     *
+     * @type Object.<Number, Guacamole.VideoPlayer>
+     */
+    var videoPlayers = {};
+
     // No initial parsers
     var parsers = [];
 
@@ -459,6 +467,30 @@ Guacamole.Client = function(tunnel) {
      */
     this.onaudio = null;
 
+    /**
+     * Fired when a video stream is created. The stream provided to this event
+     * handler will contain its own event handlers for received data.
+     *
+     * @event
+     * @param {Guacamole.InputStream} stream
+     *     The stream that will receive video data from the server.
+     *
+     * @param {Guacamole.Display.VisibleLayer} layer
+     *     The destination layer on which the received video data should be
+     *     played. It is the responsibility of the Guacamole.VideoPlayer
+     *     implementation to play the received data within this layer.
+     *
+     * @param {String} mimetype
+     *     The mimetype of the video data which will be received.
+     *
+     * @return {Guacamole.VideoPlayer}
+     *     An object which implements the Guacamole.VideoPlayer interface and
+     *     has been initialied to play the data in the provided stream, or null
+     *     if the built-in video players of the Guacamole client should be
+     *     used.
+     */
+    this.onvideo = null;
+
     /**
      * Fired when the clipboard of the remote client is changing.
      * 
@@ -1197,39 +1229,29 @@ Guacamole.Client = function(tunnel) {
             var stream_index = parseInt(parameters[0]);
             var layer = getLayer(parseInt(parameters[1]));
             var mimetype = parameters[2];
-            var duration = parseFloat(parameters[3]);
 
-            // Create stream 
+            // Create stream
             var stream = streams[stream_index] =
                     new Guacamole.InputStream(guac_client, stream_index);
 
-            // Assemble entire stream as a blob
-            var blob_reader = new Guacamole.BlobReader(stream, mimetype);
+            // Get player instance via callback
+            var videoPlayer = null;
+            if (guac_client.onvideo)
+                videoPlayer = guac_client.onvideo(stream, layer, mimetype);
 
-            // Play video once finished 
-            blob_reader.onend = function() {
+            // If unsuccessful, try to use a default implementation
+            if (!videoPlayer)
+                videoPlayer = Guacamole.VideoPlayer.getInstance(stream, layer, mimetype);
 
-                // Read data from blob from stream
-                var reader = new FileReader();
-                reader.onload = function() {
+            // If we have successfully retrieved an video player, send success response
+            if (videoPlayer) {
+                videoPlayers[stream_index] = videoPlayer;
+                guac_client.sendAck(stream_index, "OK", 0x0000);
+            }
 
-                    var binary = "";
-                    var bytes = new Uint8Array(reader.result);
-
-                    // Produce binary string from bytes in buffer
-                    for (var i=0; i<bytes.byteLength; i++)
-                        binary += String.fromCharCode(bytes[i]);
-
-                    // Play video
-                    layer.play(mimetype, duration, "data:" + mimetype + ";base64," + window.btoa(binary));
-
-                };
-                reader.readAsArrayBuffer(blob_reader.getBlob());
-
-            };
-
-            // Send success response
-            tunnel.sendMessage("ack", stream_index, "OK", 0x0000);
+            // Otherwise, mimetype must be unsupported
+            else
+                guac_client.sendAck(stream_index, "BAD TYPE", 0x030F);
 
         }
 
diff --git a/guacamole-common-js/src/main/webapp/modules/Display.js b/guacamole-common-js/src/main/webapp/modules/Display.js
index ab286792f..d74035eb7 100644
--- a/guacamole-common-js/src/main/webapp/modules/Display.js
+++ b/guacamole-common-js/src/main/webapp/modules/Display.js
@@ -1183,7 +1183,7 @@ Guacamole.Display.VisibleLayer = function(width, height) {
 
     /**
      * The parent layer container of this layer, if any.
-     * @type Guacamole.Display.LayerContainer
+     * @type Guacamole.Display.VisibleLayer
      */
     this.parent = null;
 
@@ -1275,11 +1275,11 @@ Guacamole.Display.VisibleLayer = function(width, height) {
     };
 
     /**
-     * Moves the upper-left corner of this LayerContainer to the given X and Y
-     * coordinate, sets the Z stacking order, and reparents this LayerContainer
-     * to the given LayerContainer.
+     * Moves the upper-left corner of this VisibleLayer to the given X and Y
+     * coordinate, sets the Z stacking order, and reparents this VisibleLayer
+     * to the given VisibleLayer.
      * 
-     * @param {Guacamole.Display.LayerContainer} parent The parent to set.
+     * @param {Guacamole.Display.VisibleLayer} parent The parent to set.
      * @param {Number} x The X coordinate to move to.
      * @param {Number} y The Y coordinate to move to.
      * @param {Number} z The Z coordinate to move to.
@@ -1378,7 +1378,7 @@ Guacamole.Display.VisibleLayer = function(width, height) {
 
 /**
  * The next identifier to be assigned to the layer container. This identifier
- * uniquely identifies each LayerContainer, but is unrelated to the index of
+ * uniquely identifies each VisibleLayer, but is unrelated to the index of
  * the layer, which exists at the protocol/client level only.
  * 
  * @private
diff --git a/guacamole-common-js/src/main/webapp/modules/VideoPlayer.js b/guacamole-common-js/src/main/webapp/modules/VideoPlayer.js
new file mode 100644
index 000000000..5722ac886
--- /dev/null
+++ b/guacamole-common-js/src/main/webapp/modules/VideoPlayer.js
@@ -0,0 +1,111 @@
+/*
+ * Copyright (C) 2015 Glyptodon LLC
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+
+var Guacamole = Guacamole || {};
+
+/**
+ * Abstract video player which accepts, queues and plays back arbitrary video
+ * data. It is up to implementations of this class to provide some means of
+ * handling a provided Guacamole.InputStream and rendering the received data to
+ * the provided Guacamole.Display.VisibleLayer. Data received along the
+ * provided stream is to be played back immediately.
+ *
+ * @constructor
+ */
+Guacamole.VideoPlayer = function VideoPlayer() {
+
+    /**
+     * Notifies this Guacamole.VideoPlayer that all video up to the current
+     * point in time has been given via the underlying stream, and that any
+     * difference in time between queued video data and the current time can be
+     * considered latency.
+     */
+    this.sync = function sync() {
+        // Default implementation - do nothing
+    };
+
+};
+
+/**
+ * Determines whether the given mimetype is supported by any built-in
+ * implementation of Guacamole.VideoPlayer, and thus will be properly handled
+ * by Guacamole.VideoPlayer.getInstance().
+ *
+ * @param {String} mimetype
+ *     The mimetype to check.
+ *
+ * @returns {Boolean}
+ *     true if the given mimetype is supported by any built-in
+ *     Guacamole.VideoPlayer, false otherwise.
+ */
+Guacamole.VideoPlayer.isSupportedType = function isSupportedType(mimetype) {
+
+    // There are currently no built-in video players (and therefore no
+    // supported types)
+    return false;
+
+};
+
+/**
+ * Returns a list of all mimetypes supported by any built-in
+ * Guacamole.VideoPlayer, in rough order of priority. Beware that only the core
+ * mimetypes themselves will be listed. Any mimetype parameters, even required
+ * ones, will not be included in the list.
+ *
+ * @returns {String[]}
+ *     A list of all mimetypes supported by any built-in Guacamole.VideoPlayer,
+ *     excluding any parameters.
+ */
+Guacamole.VideoPlayer.getSupportedTypes = function getSupportedTypes() {
+
+    // There are currently no built-in video players (and therefore no
+    // supported types)
+    return [];
+
+};
+
+/**
+ * Returns an instance of Guacamole.VideoPlayer providing support for the given
+ * video format. If support for the given video format is not available, null
+ * is returned.
+ *
+ * @param {Guacamole.InputStream} stream
+ *     The Guacamole.InputStream to read video data from.
+ *
+ * @param {Guacamole.Display.VisibleLayer} layer
+ *     The destination layer in which this Guacamole.VideoPlayer should play
+ *     the received video data.
+ *
+ * @param {String} mimetype
+ *     The mimetype of the video data in the provided stream.
+ *
+ * @return {Guacamole.VideoPlayer}
+ *     A Guacamole.VideoPlayer instance supporting the given mimetype and
+ *     reading from the given stream, or null if support for the given mimetype
+ *     is absent.
+ */
+Guacamole.VideoPlayer.getInstance = function getInstance(stream, layer, mimetype) {
+
+    // There are currently no built-in video players
+    return null;
+
+};