.. role:: ts-api-decorator

############
CloudSession
############

.. js:module:: cee
   :noindex:

.. container:: ts-api-section

   .. js:class:: CloudSession

      The CloudSession's responsibility is to manage the ``Viewers`` and the main event loop of 
      EnvisionWeb (``handleAnimationFrameCallback``).

      All EnvisionWeb applications need a CloudSession object. There is only need for one, even in apps
      with multiple viewers, views, models and remote servers.



.. container:: api-index-section

   .. rubric:: Constructors

   .. rst-class:: api-index-list-item api-kind-constructor api-parent-kind-class

   * :js:meth:`~cee.CloudSession.constructor`



.. container:: api-index-section

   .. rubric:: Accessors

   .. rst-class:: api-index-list-item api-kind-accessor api-parent-kind-class

   * :js:attr:`~cee.CloudSession.buildDateTimeString`
   * :js:attr:`~cee.CloudSession.version`
   * :js:attr:`~cee.CloudSession.viewerCount`



.. container:: api-index-section

   .. rubric:: Methods

   .. rst-class:: api-index-list-item api-kind-method api-parent-kind-class

   * :js:meth:`~cee.CloudSession.addModelToProcessingSet`
   * :js:meth:`~cee.CloudSession.addViewer`
   * :js:meth:`~cee.CloudSession.deleteAllViewers`
   * :js:meth:`~cee.CloudSession.deleteViewerAt`
   * :js:meth:`~cee.CloudSession.destroySession`
   * :js:meth:`~cee.CloudSession.getViewerArray`
   * :js:meth:`~cee.CloudSession.getViewerAt`
   * :js:meth:`~cee.CloudSession.handleAnimationFrameCallback`
   * :js:meth:`~cee.CloudSession.removeModelFromProcessingSet`





------------

Constructors
============

.. container:: ts-api-section

   .. js:function:: CloudSession.constructor()



      Constructor


      :rtype: CloudSession



Accessors
=========

.. container:: ts-api-section

   .. js:function:: CloudSession.buildDateTimeString()



      Returns the date and time this version of EnvisionWeb was built


      :rtype: string



.. container:: ts-api-section

   .. js:function:: CloudSession.version()



      Returns the version of HOOPS Envision for Web

      Format: Major.Minor.Patch-Build. E.g. '1.2.0+34145A' or '1.2.0-rc1++38C14A


      :rtype: string



.. container:: ts-api-section

   .. js:function:: CloudSession.viewerCount()



      Returns the number of viewers in the client application.


      :rtype: number



Methods
=======

.. rst-class:: ts-api-section

addModelToProcessingSet
-----------------------

.. js:method:: CloudSession.addModelToProcessingSet( model)

   :param model: None
   :type model: ProcessableModel


   Manually add a model to the set of models that need background processing


   :rtype: void

.. rst-class:: ts-api-section

addViewer
---------

.. js:method:: CloudSession.addViewer( canvas[, viewerOptions])

   :param canvas: None
   :type canvas: HTMLCanvasElement
   :param viewerOptions: :ts-api-decorator:`optional` None
   :type viewerOptions: ViewerOptions


   Adds a new Viewer to the session. 

   The Viewer is tied to a HTML Canvas element, and the provided canvas must be capable of rendering WebGL. 
   Returns null if the canvas is not capable of rendering WebGL or if WebGL resources are exhausted.

   A Viewer can have many ``Views``, and all the Views within a Viewer can share WebGL resources. 
   So, to show the same Model in two Views, using one Viewer with two Views is more efficient
   than using two Viewers with one View each.

   A client application can contain many Viewers, but each Viewer must be linked to single unique Canvas.


   :rtype: Viewer

.. rst-class:: ts-api-section

deleteAllViewers
----------------

.. js:method:: CloudSession.deleteAllViewers()



   Deletes all viewers from the app.


   :rtype: void

.. rst-class:: ts-api-section

deleteViewerAt
--------------

.. js:method:: CloudSession.deleteViewerAt( index)

   :param index: None
   :type index: number


   Deletes the viewer at the given index.

   The index must be zero based and between 0 and viewerCount - 1


   :rtype: void

.. rst-class:: ts-api-section

destroySession
--------------

.. js:method:: CloudSession.destroySession()



   Destroys the session object. This will delete all the viewers.


   :rtype: void

.. rst-class:: ts-api-section

getViewerArray
--------------

.. js:method:: CloudSession.getViewerArray()



   Returns a read only array with all viewers in the session


   :rtype: unknown

.. rst-class:: ts-api-section

getViewerAt
-----------

.. js:method:: CloudSession.getViewerAt( index)

   :param index: None
   :type index: number


   Returns the viewer with the given index.

   The index must be zero based and between 0 and viewerCount - 1


   :rtype: Viewer

.. rst-class:: ts-api-section

handleAnimationFrameCallback
----------------------------

.. js:method:: CloudSession.handleAnimationFrameCallback( highResTimestamp_ms)

   :param highResTimestamp_ms: None
   :type highResTimestamp_ms: number


   Mandatory update method for the HOOPS Envision Client.

   This method must be called from a requestAnimationFrame() for animations to run and 
   server communication to work as expected.

   The standard code for doing this is:

   .. code-block:: javascript

      // Setup timer to keep the session viewer up-to-date
      function myAnimationFrameCallback(highResTimestamp) {
          mySession.handleAnimationFrameCallback(highResTimestamp);
          requestAnimationFrame(myAnimationFrameCallback);
      }

      requestAnimationFrame(myAnimationFrameCallback);



   :rtype: boolean

.. rst-class:: ts-api-section

removeModelFromProcessingSet
----------------------------

.. js:method:: CloudSession.removeModelFromProcessingSet( model)

   :param model: None
   :type model: ProcessableModel


   Remove a model that was previously added manually to the processing set


   :rtype: void

