Package com.openinventor.remoteviz.rendering

Class RenderAreaListener

java.lang.Object
com.openinventor.inventor.Inventor
com.openinventor.remoteviz.rendering.RenderAreaListener
public class RenderAreaListener extends Inventor
This class can be overridden by an application to receive notifications from a RenderArea. There are several categories of notifications:
  • Connection: To know when a connection has been created, initialized and disposed.
  • Render: To know the start/end of rendering and when an image is sent to the client.
  • Input events: To handle MouseDown, MouseUp, etc. events triggered by the user.
  • Messages: To handle messages sent from the client.

For notifications related to the lifetime of the RenderArea itself, see the ServiceListener class.

Typically the application will attach a listener to the RenderArea in the onInstantiatedRenderArea() method of its ServiceListener. But applications can also create a RenderArea explicitly and attach a listener.

A typical sequence of calls to this listener is:

  • Constructor Details

    • RenderAreaListener

      public RenderAreaListener()
      Default constructor.

  • Method Details

    • onMouseLeave

      public boolean onMouseLeave(RenderArea renderArea, Connection sender, int x, int y)
      Triggered when a MouseLeave event is received from the client. Default behavior : Accept the event by returning true.

      Parameters:
      renderArea - : the RenderArea that will process the event

      sender - : the connection that sent the event

      x - : horizontal coordinate

      y - : vertical coordinate

      Returns:
      true to process the event, this will apply an SoHandleEventAction to the scene graph.
      This return value does not have any effect when the ServiceSettings.INDEPENDENT_SERVICE mode is enabled.
      If there are many listeners, the logical operator OR will be applied on all the returned value of listeners.
      If there are no listeners to call, the event will be processed.

    • onMouseEnter

      public boolean onMouseEnter(RenderArea renderArea, Connection sender, int x, int y)
      Triggered when a MouseEnter event is received from the client. Default behavior : Accept the event by returning true.

      Parameters:
      renderArea - : the RenderArea that will process the event

      sender - : the connection that sent the event

      x - : horizontal coordinate

      y - : vertical coordinate

      Returns:
      true to process the event, this will apply an SoHandleEventAction to the scene graph.
      This return value does not have any effect when the ServiceSettings.INDEPENDENT_SERVICE mode is enabled.
      If there are many listeners, the logical operator OR will be applied on all the returned value of listeners.
      If there are no listeners to call, the event will be processed.

    • onSendingFrame

      public String onSendingFrame(RenderArea renderArea, Connection sender)
      Triggered before sending a frame to the client. The sending frame can be retrieved using Connection.getLastEncodedFrame. IMPORTANT: This callback is executed in a separate thread for each connection sending a frame.

      Parameters:
      renderArea - : the RenderArea of the Connection

      sender - : the connection that will send the frame to the client

      Returns:
      a text message attached to the frame. Default value is an empty string. This message can be retrieved from the client listeners: onReceivedFrame and onDecodedFrame.

    • onRefusedEncoder

      public void onRefusedEncoder(RenderArea renderArea, Connection sender, FrameEncoders encoders)
      Triggered when a frame encoder cannot be initialized. If this case occurs, set another frame encoder. The status of encoders explains the reason for refusal.

      Default behavior: Try to load other encoders automatically (fallback): H264_NVENC/H264_NVENC => VP9_VPX/VP9_VPX => H264_OPENH264/H264_OPENH264 => PNG/JPEG => JPEG/JPEG Fallback directly to JPEG/JPEG if the pair of frame encoders are incompatible. If none of frame encoders can be initialized, the connection will be closed.

      Parameters:
      renderArea - : the RenderArea of the Connection

      sender - : the connection that requests frame encoders

      encoders - : frame encoders refused by the connection

    • onMouseWheel

      public boolean onMouseWheel(RenderArea renderArea, Connection sender, int x, int y, int delta)
      Triggered when a mouse wheel event (rotatation) is received from the client. Default behavior : Accept the event by returning true.

      Parameters:
      renderArea - : the RenderArea that will process the event

      sender - : the connection that sent the event

      x - : horizontal coordinate

      y - : vertical coordinate

      delta - : abstract value which indicates how far the wheel turned

      Returns:
      true to process the event, this will apply an SoHandleEventAction to the scene graph.
      This return value does not have any effect when the ServiceSettings.INDEPENDENT_SERVICE mode is enabled.
      If there are many listeners, the logical operator OR will be applied on all the returned value of listeners.
      If there are no listeners to call, the event will be processed.

    • onRequestedFrame

      public boolean onRequestedFrame(RenderArea renderArea, Connection sender, SbRasterImage rasterImage)
      Triggered when a new frame is requested by a connection. This method only works when the ServiceSettings.INDEPENDENT_SERVICE mode is enabled.

      To send a new frame to the client, set the pixel buffer of the raster image using a buffer object. If the buffer object of the raster image is NULL, no frame will be sent to the client. IMPORTANT: This callback is executed in a separate thread for each connection requesting a frame.

      Parameters:
      renderArea - : the RenderArea of the Connection

      sender - : the connection that requests a new frame

      rasterImage - : contains the RGB raster image to render.

      isInteractive - : This value can be modified to indicate if an user interaction is in progress. Default value is true.
      If true (interactive frame), the frame will be compressed with the interactive frame encoder and a quality adapted to the bandwidth setting.
      If false (still frame), the frame will be compressed with the still frame encoder and the best available quality.
      See Also:

    • onMouseDown

      public boolean onMouseDown(RenderArea renderArea, Connection sender, int x, int y, SoMouseButtonEvent.Buttons button)
      Triggered when a MouseDown event is received from the client.
      Default behavior : Accept the event by returning true.

      Parameters:
      renderArea - : the RenderArea that will process the event

      sender - : the connection that sent the event

      x - : horizontal coordinate

      y - : vertical coordinate

      button - : The button that was pressed when the mouse event was fired.

      Returns:
      true to process the event, this will apply an SoHandleEventAction to the scene graph.
      This return value does not have any effect when the ServiceSettings.INDEPENDENT_SERVICE mode is enabled.
      If there are many listeners, the logical operator OR will be applied on all the returned value of listeners.
      If there are no listeners to call, the event will be processed.

    • onMouseUp

      public boolean onMouseUp(RenderArea renderArea, Connection sender, int x, int y, SoMouseButtonEvent.Buttons button)
      Triggered when a MouseUp event is received from the client. Default behavior : Accept the event by returning true.

      Parameters:
      renderArea - : the RenderArea that will process the event

      sender - : the connection that sent the event

      x - : horizontal coordinate

      y - : vertical coordinate

      button - : The button that was pressed when the mouse event was fired.

      Returns:
      true to process the event, this will apply an SoHandleEventAction to the scene graph.
      This return value does not have any effect when the ServiceSettings.INDEPENDENT_SERVICE mode is enabled.
      If there are many listeners, the logical operator OR will be applied on all the returned value of listeners.
      If there are no listeners to call, the event will be processed.

    • onInitializedConnection

      public void onInitializedConnection(RenderArea renderArea, Connection sender, FrameEncoders frameEncoders)
      Triggered when the connection and the frame encoders are initialized successfully. Use the FrameEncoders object to query which frame encoders will actually be used.

      Parameters:
      renderArea - : the RenderArea requested by the connection

      sender - : the Connection

      frameEncoders - : frame encoders that have been initialized by the connection

    • onMouseMove

      public boolean onMouseMove(RenderArea renderArea, Connection sender, int x, int y)
      Triggered when a MouseMove event is received from the client. Default behavior : Accept the event by returning true.

      Parameters:
      renderArea - : the RenderArea that will process the event

      sender - : the connection that sent the event

      x - : horizontal coordinate

      y - : vertical coordinate

      Returns:
      true to process the event, this will apply an SoHandleEventAction to the scene graph.
      This return value does not have any effect when the ServiceSettings.INDEPENDENT_SERVICE mode is enabled.
      If there are many listeners, the logical operator OR will be applied on all the returned value of listeners.
      If there are no listeners to call, the event will be processed.

    • onMouseDoubleClick

      public boolean onMouseDoubleClick(RenderArea renderArea, Connection sender, int x, int y, SoMouseButtonEvent.Buttons button)
      Triggered when a MouseDoubleClick event is received from the client. Default behavior : Accept the event by returning true.

      Parameters:
      renderArea - : the RenderArea that will process the event

      sender - : the connection that sent the event

      x - : horizontal coordinate

      y - : vertical coordinate

      button - : The button that was pressed when the mouse event was fired.

      Returns:
      true to process the event, this will apply an SoHandleEventAction to the scene graph.
      This return value does not have any effect when the ServiceSettings.INDEPENDENT_SERVICE mode is enabled.
      If there are many listeners, the logical operator OR will be applied on all the returned value of listeners.
      If there are no listeners to call, the event will be processed.

    • onReceivedMessage

      public void onReceivedMessage(RenderArea renderArea, Connection sender, Collection<Byte> buffer)
      Triggered when a binary message is received from a client. Default behavior : do nothing

      Parameters:
      renderArea - : the RenderArea

      sender - : the Connection that receives the binary message

      buffer - : the received binary buffer sent by the client

    • onTouchEnd

      public boolean onTouchEnd(RenderArea renderArea, Connection sender, int id, int x, int y)
      Triggered when a TouchEnd event is received from the client. Default behavior : Accept the event by returning true.

      Parameters:
      renderArea - : the RenderArea that will process the event

      sender - : the connection that sent the event

      id - : touch identifier

      x - : horizontal coordinate

      y - : vertical coordinate

      Returns:
      true to process the event, this will apply an SoHandleEventAction to the scene graph.
      This return value does not have any effect when the ServiceSettings.INDEPENDENT_SERVICE mode is enabled.
      If there are many listeners, the logical operator OR will be applied on all the returned value of listeners.
      If there are no listeners to call, the event will be processed.

    • onPreRender

      public boolean[] onPreRender(RenderArea renderArea, boolean clearWindow, boolean clearZbuffer)
      Triggered before a rendering is done. Default behavior : Do the rendering by returning true.

      In the ServiceSettings.INDEPENDENT_SERVICE mode, this callback is never triggered.

      Parameters:
      renderArea - : the RenderArea that will perform the rendering.

      clearWindow - : if true, this clears the graphics window before rendering

      clearZbuffer - : if true, the z buffer will be cleared before rendering

      Returns:
      false to abort the rendering.
      If there are many listeners, the logical operator OR will be applied on all the returned value of listeners.
      If there are no listeners to call, the rendering will be not aborted.

    • onClosedConnection

      public void onClosedConnection(RenderArea renderArea, String connectionId, boolean aborted)
      Triggered when a connection is closed. Default behavior : Dispose the renderArea if all its connections are closed and the application does not have a reference to the renderArea. If the application has a reference, it can use RenderArea.isDisposed() to know the state.

      Parameters:
      renderArea - : the RenderArea

      connectionId - : ID identifying the connection

      aborted - : true if the network connection was closed unexpectedly by the client or has been lost.

    • onOpenedConnection

      public void onOpenedConnection(RenderArea renderArea, Connection connection, FrameEncoders frameEncoders)
      Triggered when a client connects to the RenderArea. Use this method to set the encoding format for images sent to the client, using the frameEncoders parameter. The default is JPEG for interactive frames (i.e. while the user is interacting) and PNG for still frames. Video encoding (H264 or VP9) may provide better performance by reducing bandwidth requirements. Use the ConnectionSettings.isSupportedEncoders() method to query if the proposed encoders are available. If a requested frame encoder cannot be initialized, RenderAreaListener.onRefusedEncoder will be triggered. Otherwise, RenderAreaListener.onInitializedConnection will be triggered.

      Parameters:
      renderArea - : the RenderArea requested by the connection

      connection - : the Connection

      frameEncoders - : frame encoders for interactive and still frames
      Supported pairs of frame encoders (still/interactive): JPEG/JPEG, PNG/JPEG, H264_NVENC/H264_NVENC, H264_OPENH264/H264_OPENH264, VP9_VPX/VP9_VPX
      Default behavior: PNG/JPEG.

    • onReceivedMessage

      public void onReceivedMessage(RenderArea renderArea, Connection sender, String message)
      Triggered when a text message is received from a client. Default behavior : do nothing

      Parameters:
      renderArea - : the RenderArea requested by the connection

      sender - : the Connection that receives the text message

      message - : the received message sent by the client

    • onTouchMove

      public boolean onTouchMove(RenderArea renderArea, Connection sender, int id, int x, int y)
      Triggered when a TouchMove event is received from the client. Default behavior : Accept the event by returning true.

      Parameters:
      renderArea - : the RenderArea that will process the event

      sender - : the connection that sent the event

      id - : touch identifier

      x - : horizontal coordinate

      y - : vertical coordinate

      Returns:
      true to process the event, this will apply an SoHandleEventAction to the scene graph.
      This return value does not have any effect when the ServiceSettings.INDEPENDENT_SERVICE mode is enabled.
      If there are many listeners, the logical operator OR will be applied on all the returned value of listeners.
      If there are no listeners to call, the event will be processed.

    • onKeyDown

      public boolean onKeyDown(RenderArea renderArea, Connection sender, int x, int y, SoKeyboardEvent.Keys key)
      Triggered when a KeyDown event is received from the client. Default behavior : Accept the event by returning true.

      Parameters:
      renderArea - : the RenderArea that will process the event

      sender - : the connection that sent the event

      x - : horizontal coordinate

      y - : vertical coordinate

      key - : pressed key

      Returns:
      true to process the event, this will apply an SoHandleEventAction to the scene graph.
      This return value does not have any effect when the ServiceSettings.INDEPENDENT_SERVICE mode is enabled.
      If there are many listeners, the logical operator OR will be applied on all the returned value of listeners.
      If there are no listeners to call, the event will be processed.

    • onRequestedSize

      public void onRequestedSize(RenderArea renderArea, Connection sender, int width, int height)
      Triggered when a client requests a new renderArea size. To resize the renderArea, call the method RenderArea.resize.
      Default behavior : Resize the renderArea to the requested size.

      Parameters:
      renderArea - : the RenderArea of the Connection

      sender - : the connection that made the size request

      width - : requested width

      height - : requested height
      See Also:

    • onKeyUp

      public boolean onKeyUp(RenderArea renderArea, Connection sender, int x, int y, SoKeyboardEvent.Keys key)
      Triggered when a KeyUp event is received from the client. Default behavior : accept the event by returning true.

      Parameters:
      renderArea - : the RenderArea that will process the event

      sender - : the connection that sent the event

      x - : horizontal coordinate

      y - : vertical coordinate

      key - : released key

      Returns:
      true to process the event, this will apply an SoHandleEventAction to the scene graph.
      This return value does not have any effect when the ServiceSettings.INDEPENDENT_SERVICE mode is enabled.
      If there are many listeners, the logical operator OR will be applied on all the returned value of listeners.
      If there are no listeners to call, the event will be processed.

    • onPostRender

      public void onPostRender(RenderArea renderArea)
      Triggered after a rendering is done. Default behavior : Do nothing.

      In the ServiceSettings.INDEPENDENT_SERVICE mode, this callback is never triggered.

      Parameters:
      renderArea - : the RenderArea that performed the rendering.

    • onTouchStart

      public boolean onTouchStart(RenderArea renderArea, Connection sender, int id, int x, int y)
      Triggered when a TouchStart event is received from the client. Default behavior : Accept the event by returning true.

      Parameters:
      renderArea - : the RenderArea that will process the event

      sender - : the connection that sent the event

      id - : touch identifier

      x - : horizontal coordinate

      y - : vertical coordinate

      Returns:
      true to process the event, this will apply an SoHandleEventAction to the scene graph.
      This return value does not have any effect when the ServiceSettings.INDEPENDENT_SERVICE mode is enabled.
      If there are many listeners, the logical operator OR will be applied on all the returned value of listeners.
      If there are no listeners to call, the event will be processed.

    • onResize

      public void onResize(RenderArea renderArea, int width, int height)
      Triggered when the renderArea is resized. See RenderArea.resize(). Default behavior : Do nothing.

      Parameters:
      renderArea - : the resized RenderArea

      width - : new width of the renderArea

      height - : new height of the renderArea