RemoteVizRenderArea.h

/*=======================================================================
*** THE CONTENT OF THIS WORK IS PROPRIETARY TO FEI S.A.S, (FEI S.A.S.),            ***
***              AND IS DISTRIBUTED UNDER A LICENSE AGREEMENT.                     ***
***                                                                                ***
***  REPRODUCTION, DISCLOSURE,  OR USE,  IN WHOLE OR IN PART,  OTHER THAN AS       ***
***  SPECIFIED  IN THE LICENSE ARE  NOT TO BE  UNDERTAKEN  EXCEPT WITH PRIOR       ***
***  WRITTEN AUTHORIZATION OF FEI S.A.S.                                           ***
***                                                                                ***
***                        RESTRICTED RIGHTS LEGEND                                ***
***  USE, DUPLICATION, OR DISCLOSURE BY THE GOVERNMENT OF THE CONTENT OF THIS      ***
***  WORK OR RELATED DOCUMENTATION IS SUBJECT TO RESTRICTIONS AS SET FORTH IN      ***
***  SUBPARAGRAPH (C)(1) OF THE COMMERCIAL COMPUTER SOFTWARE RESTRICTED RIGHT      ***
***  CLAUSE  AT FAR 52.227-19  OR SUBPARAGRAPH  (C)(1)(II)  OF  THE RIGHTS IN      ***
***  TECHNICAL DATA AND COMPUTER SOFTWARE CLAUSE AT DFARS 52.227-7013.             ***
***                                                                                ***
***                   COPYRIGHT (C) 1996-2020 BY FEI S.A.S,                        ***
***                        BORDEAUX, FRANCE                                        ***
***                      ALL RIGHTS RESERVED                                       ***
**=======================================================================*/

  import RemoteVizRenderArea = require("./RemoteVizClient");
  \endverbatim
*
* <h2> Web browser image streaming support </h2>
*
* Image streaming mode (JPEG/PNG) is supported by all modern web browsers. 
*
* <h2> Web browser video streaming support </h2>
*
* <h3> H.264 streaming support </h3>
*
* H.264 streaming mode requires that the web browser supports Media Source extension API and H.264 live streaming (no frame delay).\n
* The array below shows the supported web browsers:
*
* <table>
* <tr>
* <td>&nbsp;</td>
* <td>Google Chrome</td>
* <td>Mozilla Firefox</td>
* <td>Edge (version 12 to 18)</td>
* <td>Edge (version 79 and higher)</td>
* <td>Safari</td>
* </tr>
* <tr>
* <td>Windows 7</td>
* <td bgcolor="#ffff99">&nbsp;<a href="https://bugs.chromium.org/p/chromium/issues/detail?id=679746">Frames latency</a></td>
* <td bgcolor="#99ff66">&nbsp;OK</td>
* <td bgcolor="#ff3300">&nbsp;<a href="https://developer.microsoft.com/en-us/microsoft-edge/platform/issues/10570808/">Not functional</a></td>
* <td bgcolor="#ffff99">&nbsp;Frames latency</td>
* <td bgcolor="#7f7f7f">&nbsp;Web browser not available on this platform</td>
* </tr>
* <tr>
* <td>Windows 8.X / 10</td>
* <td bgcolor="#99ff66">&nbsp;OK</td>
* <td bgcolor="#99ff66">&nbsp;OK</td>
* <td bgcolor="#ff3300">&nbsp;<a href="https://developer.microsoft.com/en-us/microsoft-edge/platform/issues/10570808/">Not functional</a></td>
* <td bgcolor="#99ff66">&nbsp;OK</td>
* <td bgcolor="#7f7f7f">&nbsp;Web browser not available on this platform</td>
* </tr>
* <tr>
* <td>MacOSX</td>
* <td bgcolor="#ffff99">&nbsp;Frames latency</td>
* <td bgcolor="#99ff66">&nbsp;OK</td>
* <td bgcolor="#7f7f7f">&nbsp;Web browser not available on this platform</td>
* <td bgcolor="#ffff99">&nbsp;Frames latency</td>
* <td bgcolor="#99ff66">&nbsp;OK</td>
* </tr>
* <tr>
* <td>Linux</td>
* <td bgcolor="#99ff66">&nbsp;OK</td>
* <td bgcolor="#99ff66">&nbsp;OK</td>
* <td bgcolor="#7f7f7f">&nbsp;Web browser not available on this platform</td>
* <td bgcolor="#99ff66">&nbsp;OK</td>
* <td bgcolor="#7f7f7f">&nbsp;Web browser not available on this platform</td>
* </tr>
* <tr>
* <td>Android</td>
* <td bgcolor="#99ff66">&nbsp;OK</td>
* <td bgcolor="#99ff66">&nbsp;OK</td>
* <td bgcolor="#99ff66">&nbsp;OK</td>
* <td bgcolor="#99ff66">&nbsp;OK</td>
* <td bgcolor="#7f7f7f">&nbsp;Web browser not available on this platform</td>
* </tr>
* <tr>
* <td>iOS</td>
* <td bgcolor="#ff6600">&nbsp;Media Source Extension not supported by iOS</td>
* <td bgcolor="#ff6600">&nbsp;Media Source Extension not supported by iOS</td>
* <td bgcolor="#7f7f7f">&nbsp;Web browser not available on this platform</td>
* <td bgcolor="#ff6600">&nbsp;Media Source Extension not supported by iOS</td>
* <td bgcolor="#ff6600">&nbsp;Media Source Extension not supported by iOS</td>
* </tr>
* <tr>
* <td>iPadOS</td>
* <td bgcolor="#ff6600">&nbsp;Media Source Extension not available</td>
* <td bgcolor="#ff6600">&nbsp;Media Source Extension not available</td>
* <td bgcolor="#ff6600">&nbsp;Media Source Extension not available</td>
* <td bgcolor="#ff6600">&nbsp;Media Source Extension not available</td>
* <td bgcolor="#99ff66">&nbsp;OK</td>
* </tr>
* </table>
* \n
*
* <h3> VP9 streaming support </h3>
*
* VP9 streaming mode requires that the web browser supports Media Source extension API and VP9 live streaming.\n
* The array below shows the supported web browsers:
*
* <table>
* <tr>
* <td>&nbsp;</td>
* <td>Google Chrome</td>
* <td>Mozilla Firefox</td>
* <td>Edge (version 12 to 18)</td>
* <td>Edge (version 79 and higher)</td>
* <td>Safari</td>
* </tr>
* <tr>
* <td>Windows 7</td>
* <td bgcolor="#99ff66">&nbsp;OK</td>
* <td bgcolor="#99ff66">&nbsp;OK</td>
* <td bgcolor="#ff3300">&nbsp;Not supported</td>
* <td bgcolor="#99ff66">&nbsp;OK</td>
* <td bgcolor="#7f7f7f">&nbsp;Web browser not available on this platform</td>
* </tr>
* <tr>
* <td>Windows 8.X / 10</td>
* <td bgcolor="#99ff66">&nbsp;OK</td>
* <td bgcolor="#99ff66">&nbsp;OK</td>
* <td bgcolor="#ff3300">&nbsp;Not supported</td>
* <td bgcolor="#99ff66">&nbsp;OK</td>
* <td bgcolor="#7f7f7f">&nbsp;Web browser not available on this platform</td>
* </tr>
* <tr>
* <td>MacOSX</td>
* <td bgcolor="#99ff66">&nbsp;OK</td>
* <td bgcolor="#99ff66">&nbsp;OK</td>
* <td bgcolor="#7f7f7f">&nbsp;Web browser not available on this platform</td>
* <td bgcolor="#99ff66">&nbsp;OK</td>
* <td bgcolor="#ff3300">&nbsp;Not supported</td>
* </tr>
* <tr>
* <td>Linux</td>
* <td bgcolor="#99ff66">&nbsp;OK</td>
* <td bgcolor="#99ff66">&nbsp;OK</td>
* <td bgcolor="#7f7f7f">&nbsp;Web browser not available on this platform</td>
* <td bgcolor="#99ff66">&nbsp;OK</td>
* <td bgcolor="#7f7f7f">&nbsp;Web browser not available on this platform</td>
* </tr>
* <tr>
* <td>Android</td>
* <td bgcolor="#99ff66">&nbsp;OK</td>
* <td bgcolor="#99ff66">&nbsp;OK</td>
* <td bgcolor="#ff3300">&nbsp;Not supported</td>
* <td bgcolor="#99ff66">&nbsp;OK</td>
* <td bgcolor="#7f7f7f">&nbsp;Web browser not available on this platform</td>
* </tr>
* <tr>
* <td>iOS</td>
* <td bgcolor="#ff6600">&nbsp;Media Source Extension not supported by iOS</td>
* <td bgcolor="#ff6600">&nbsp;Media Source Extension not supported by iOS</td>
* <td bgcolor="#7f7f7f">&nbsp;Web browser not available on this platform</td>
* <td bgcolor="#ff6600">&nbsp;Media Source Extension not supported by iOS</td>
* <td bgcolor="#ff6600">&nbsp;Media Source Extension not supported by iOS</td>
* </tr>
* <tr>
* <td>iPadOS</td>
* <td bgcolor="#ff6600">&nbsp;Media Source Extension not available</td>
* <td bgcolor="#ff6600">&nbsp;Media Source Extension not available</td>
* <td bgcolor="#ff6600">&nbsp;Media Source Extension not available</td>
* <td bgcolor="#ff6600">&nbsp;Media Source Extension not available</td>
* <td bgcolor="#ff3300">&nbsp;Not supported</td>
* </tr>
* </table>
* \n
* The function RemoteVizRenderArea#isImageStreamingSupported enables to know if image streaming mode (JPEG/PNG decoding) is supported by the web browser.\n\n
* The function RemoteVizRenderArea#isVideoStreamingSupported enables to know if video streaming mode (H.264/VP9 decoding) is supported by the web browser.\n\n
*
* <h2> HTTP Content-Security-Policy </h2>
*
* The HTTP Content-Security-Policy response header allows web site administrators to control resources the user agent is 
* allowed to load for a given page. This helps guard against cross-site scripting attacks (XSS).\n
* In order to use this feature with RemoteViz, the RemoteViz WebSocket's server address has to be explicitly set as a property
* on the 'connect-src' directive (for example: "connect-src ws://serverip:serverport" or "connect-src ws://example.com"). 
* In case of using image streaming mode, the source 'data:' has to be explicitly set as a property on the directive 'img-src'.
*
* <h2> Microsoft Edge </h2>
*
* Running the RemoteViz examples on localhost using Microsoft Edge can fail because of the network isolation.
* This happens because Edge runs as a Windows modern app different from IE and thus it is has network isolation by default for security reasons.
* You can either change the network interface used by the RemoteViz examples or enable loopback in the net isolation settings:
* \verbatim For Build 10158 or newer: CheckNetIsolation LoopbackExempt -a -n=Microsoft.MicrosoftEdge_8wekyb3d8bbwe \endverbatim
*
* <a href="https://blogs.msdn.microsoft.com/msgulfcommunity/2015/07/01/how-to-debug-localhost-on-microsoft-edge/">More information</a>
*
* @EXAMPLE
* \code
* <html>
*   <head>
*     <title>RemoteViz Example</title>
*     <link rel="stylesheet" type="text/css" href="loader.css"> <!-- include the loader css -->
*     <script type="text/javascript" src="RemoteVizClient.js"></script> <!-- include the RemoteViz javascript client -->
*     <script type="text/javascript">
*
*     var theRenderArea = null;
*
*     function init() // This function is called immediately after the page is loaded.
*     {
*       // Initialize the renderArea on the server.
*       //   "TheDiv" is the id of the image container, which must be a <div>.
*       //   "640" and "480" are the container width and height and will be set as
*       //      the requested width and height for the renderArea managed by the service.
*       theRenderArea = new RemoteVizRenderArea("TheDiv", 640, 480);
*
*       // Listen for start and stop bandwidth calibration events to display or hide the loader.
*       theRenderArea.addServiceListener(service);
*
*       // Connect to the service.
*       //   The IP address and the port refer to those of the service (see main.cpp).
*       //   "TheDemo" specifies the name of the requested renderArea.
*       theRenderArea.connectTo("ws://127.0.0.1:8080/TheDemo");
*     }
*
*     function service(event) // This function is called when a message is received from the service.
*     {
*       var message = event[0];
*       switch(message) {
*         case "startNetworkCalibration":
*         case "pendingNetworkCalibration":
*           document.getElementById("loaderGroup").style.display = "inline";
*           break;
*         case "finishedNetworkCalibration":
*           document.getElementById("loaderGroup").style.display = "none";
*           break;
*       }
*     }
*   </script>
*   </head>
*   <body onload="init()" bgcolor="silver">
*     <div id="loaderGroup" style="display:none;"><div id="loader"></div>
*     <div id="loaderText">Bandwidth calibration</div></div> <!-- loader notifying the network bandwidth calibration -->
*     <div id="TheDiv"> <!-- element displaying the renderArea -->
*     </div>
*   </body>
* </html>
* \endcode
 
*/
class RemoteVizRenderArea
{
 
public:

  RemoteVizRenderArea(String|HTMLElement container, Number containerWidth, Number containerHeight, String displayMode);

  connectTo(String serviceUrl);

  disconnect();

  Boolean isConnected();

  sendMessage(String|Uint8Array message);

  requestRenderAreaSize(Number width, Number height);

  resizeRenderAreaContainer(Number width, Number height);


  Number getRenderAreaWidth();

  Number getRenderAreaHeight();


  Number getContainerWidth();

  Number getContainerHeight();


  Boolean isImageStreamingSupported();

  Boolean isVideoStreamingSupported();

  String getStreamingMode();


  addServiceListener(Function serviceHandler);
  removeServiceListener(Function serviceHandler);
  serviceHandler(Object notification);



  addResizeListener(Function resizeHandler);
  removeResizeListener(Function resizeHandler);
  resizeHandler(Array size);



  addReceivedFrameListener(Function receivedFrameHandler);
  removeReceivedFrameListener(Function receivedFrameHandler);
  receivedFrameHandler(Number frameId, Number dataLength, String message);



  addDecodedFrameListener(Function decodedFrameHandler);
  removeDecodedFrameListener(Function decodedFrameHandler);
  decodedFrameHandler(Number frameId, Boolean isLossless, String message);


  addMessageListener(Function messageHandler);
  removeMessageListener(Function messageHandler);
  messageHandler(String|Uint8Array message);


  addMouseUpListener(Function eventHandler);
  removeMouseUpListener(Function eventHandler);


  addMouseDownListener(Function eventHandler);
  removeMouseDownListener(Function eventHandler);


  addMouseDoubleClickListener(Function eventHandler);
  removeMouseDoubleClickListener(Function eventHandler);


  addMouseMoveListener(Function eventHandler);
  removeMouseMoveListener(Function eventHandler);


  addMouseOverListener(Function eventHandler);
  removeMouseOverListener(Function eventHandler);


  addMouseOutListener(Function eventHandler);
  removeMouseOutListener(Function eventHandler);


  addMouseWheelListener(Function eventHandler);
  removeMouseWheelListener(Function eventHandler);


  addTouchStartListener(Function eventHandler);
  removeTouchStartListener(Function eventHandler);


  addTouchEndListener(Function eventHandler);
  removeTouchEndListener(Function eventHandler);


  addTouchCancelListener(Function eventHandler);
  removeTouchCancelListener(Function eventHandler);


  addTouchMoveListener(Function eventHandler);
  removeTouchMoveListener(Function eventHandler);


  addKeyUpListener(Function eventHandler);
  removeKeyUpListener(Function eventHandler);


  addKeyDownListener(Function eventHandler);
  removeKeyDownListener(Function eventHandler);

  Boolean eventHandler(Event event);
 
};