Package com.openinventor.remoteviz.rendering

Class 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 Detail

      • RenderAreaListener

        public RenderAreaListener()
        Default constructor.

    • Method Detail

      • 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 java.lang.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:
        ServiceSettings.setRunMode

      • 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,
                              java.util.Collection<java.lang.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,
                               java.lang.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,
                              java.lang.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:
        onResize, RenderArea.resize

      • 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