ON THIS PAGE

This object allows you to configure resolution and other video output settings. The same video resolution is applied to all video outputs on a BrightSign player. Video or images that are subsequently decoded and displayed will be scaled (using the hardware scalar) to this output resolution if necessary.

Object Creation: The roVideoMode object is created with no parameters.

CreateObject("roVideoMode")

The roVideoMode object generates roHdmiInputChanged and roHdmiOutputChanged event objects whenever the hotplug status of the HDMI input or output changes.

ifVideoMode

SetMode(mode As String) As Boolean 

Sets the video output mode. See here for a list of supported video modes. Calling this method causes the application to restart if the specified video mode is different from the current video mode. This method also accepts "auto" as a mode parameter. The following optional parameters can be appended to the string

BrightSign hardware has a video anti-aliasing low-pass filter that is set automatically.

SetModeForNextBoot(video_mode As String) As Boolean

Specifies the target video mode of the device the next time it reboots. Once a video mode is specified using SetMode(), it can only be changed by a device reboot.

GetModeForNextBoot() As String

Returns the target video mode of the device the next time it reboots. The return value is specified with the SetModeForNextBoot() method.

GetBestMode(connector As String) As String

Returns the highest supported video mode, as reported by the display via EDID. The video connector can be specified as "hdmi" or "vga" (these values are case sensitive). If the display does not return a resolution value over EDID (or if no display is connected), this method returns a blank string.

GetMode() As String

Returns the current video mode of the device, which is specified using the SetMode() method.

GetAvailableModes() As Array 

Returns all video modes supported by the player as an array of of entries. Each entry is an associative array with the following values:

GetActiveMode() As AssociativeArray

Returns information about the current video mode as an associative array:

GetConfiguredMode() As AssociativeArray

Returns information about the video mode configured using the SetMode() method. This method returns an roAssociativeArray; see the GetAvailableModes() entry for more details about returned values. If the video mode is set to "auto", this method will return Invalid.

GetFPS() As Integer

Returns the current framerate of the video output.

SetDecoderMode(decoder As String, timeslice_mode As String, z_order As Integer, friendly_name As String, enable_mosaic_deinterlacer As Boolean) As Boolean 

Configures a video decoder for either standard mode or Mosaic mode. In standard mode, a single decoder is used to play a single video; in Mosaic mode, the decoder can be used to decode multiple videos from different local or remote sources. See the Selecting Decoders section below for more information on assigning video players to decoders in HTML or BrightScript.

Upscaling videos in Mosaic mode currently causes severe performance degradation.

GetDecoderModes() As roArray

Returns an array of associative arrays, each one corresponding to a single decoder. Each associative array contains the following entries:

Set3dMode(mode As Integer) As Boolean

Sets the 3D video output mode, which is specified by passing one the following parameters:

Screenshot(parameters As roAssociativeArray) As Boolean

Captures a screenshot of the video and graphics layer as a .jpeg or .bmp file. The screenshot is configured by passing an associative array of parameters to the method:

The default dimensions of the image file is 640x480.

GetResX() As Integer

Returns the current width of the graphics plane.

GetResY() As Integer

Returns the current height of the graphics plane.

GetVideoResX() As Integer

Returns the current width of the video plane.

GetVideoResY() As Integer

Returns the current height of the video plane.

GetOutputResX() As Integer

Returns the width of the display for the current video mode.

GetOutputResY() As Integer

Returns the height of the display for the current video mode.

In most cases, the values returned by GetResX()/GetResY(), GetVideoResX()/GetVideoResY(), and GetOutputResX()/GetOutputResY() will be identical. The "GetRes" and "GetVideoRes" values will sometimes differ when using 4K modes if the graphics plane (i.e. "GetRes") remains at 1920x1080, while the video plane (i.e. "VideoRes") expands (e.g. to 3840x2160). The "OutputRes" value will differ from the other two values when the video output is upscaled: For example, when upscaling from HD to 4K, the "GetRes" and "GetVideoRes" values will remain at 1920x1080, while the "OutputRes" values will indicate 3840x2160.

GetSafeX() As Integer

Returns the horizontal coordinate for the upper-left corner of the "safe area". For modes that are generally displayed with no overscan, this will be zero.

GetSafeY() As Integer

Returns the vertical coordinate for the upper-left corner of the "safe area". For modes that are generally displayed with no overscan, this will be zero.

GetSafeWidth() As Integer

Returns the width of the "safe area." For modes that are generally displayed with no overscan, this will return the same as GetResX.

GetSafeHeight() As Integer

Returns the height of the "safe area." For modes that are generally displayed with no overscan, this will return the same as GetResY.

More information about safe areas can be found here:

SetGraphicsZOrder(order As String) As Boolean 

Specifies the order of the graphics plane (which includes all graphical elements) in relation to the video plane(s). This method accepts three parameters:

If the player is rendering two videos, the front and back options will always place the graphics plane in front of or behind both video planes. To determine the z-order of video planes in relation to one another, use the ToFront() and ToBack() methods provided by the roVideoPlayer object. The following table shows all possible video and graphics z-order arraignments that can be specified using the SetGraphicsZOrder() method and calling the ToFront()  and ToBack() methods on a "Video1" roVideoPlayer instance.

SetGraphicsZOrder()

front

middle

back

ToFront()/ToBack()

ToFront()

ToBack()

ToFront()

ToBack()

ToFront()

ToBack()

Z-Order

Graphics

Graphics

Video1

Video2

Video1

Video2

Video1

Video2

Graphics

Graphics

Video2

Video1

Video2

Video1

Video2

Video1

Graphics

Graphics

PauseGraphics(timeout_in_ms As Integer) As Boolean 

Suspends graphics compositor updates for the specified number of milliseconds (or until the ResumeGraphics() method is called), up to a maximum interval of 10 seconds. While the graphics compositor is paused, no visual elements will be updated (except for HWZ video, scrolling tickers, and off-screen Chromium textures). Use this method to combine Show()Hide(), Raise()Lower(), and SetRectangle() operations into a single v-sync update.

ResumeGraphics() As Boolean

Resumes the graphics compositor if it has been paused with the PauseGraphics() method.

SetImageSizeThreshold(parameters As roAssociativeArray) As Boolean 

Changes the maximum allowed size for images. Images sizes are measured in bytes using the following formula: image_width * image_height * 4.

The default image size limit is 35389440 bytes (equivelant to 4096x2160x32bpp) for XTx44, XTx43, XDx34, XDx33, and 4Kx42 models and 2621440 bytes (equivelant to 2048x1280x32bpp) for other models. Displaying images larger than the default value may deplete the graphics memory and cause a crash, so we recommend testing a script that uses this method thoroughly before deploying it in a production environment. This method accepts an associative array with the following parameters:

You can also increase the default maximum width/height by reducing the bpp value (e.g. using a 4096x1280x16bpp on non-4K-capable players is allowed); however, this method is not applicable to HTML pages because Chromium always decodes images to RGBA 8888.

AdjustGraphicsColor(parameters As roAssociativeArray) As Boolean

Adjusts the video and graphics output of the player using the following parameters, which can be passed to the method as an associative array: "brightness", "hue", "contrast", "saturation". Each parameter has a default value of 0 and can accept a range of values between -1000 and 1000.

ConfigureHdmiInput(parameters As roAssociativeArray) As Boolean

Configures EDID reporting for the HDMI input. By default, the input EDID includes video modes from the display attached to the HDMI output, some video modes supported by the player, and support for PCM audio up to 48kHz; it does not report proprietary media codecs that can be decoded by the device connected to the HDMI output, so you can use this method to announce such support if available at the endpoint. Using this method to change the default configuration will trigger a reboot on the player. The passed associative array can contain the following parameters:

SetHdmiMetadata(parameters As roAssociativeArray) As roAssociativeArray

Configures strings to be sent in the HDMI metadata. This method accepts an associative array with the following parameters:

This method returns an associative array, which can contain a single parameter:

GetHdmiOutputStatus() As roAssociativeArray

Returns an associative array of Boolean and integer values if an HDMI output is currently connected to a display device. This method will return Invalid if the HDMI output is currently not connected to a display device. The associative array contains the following parameters:

If an HDR video is playing, the following values will be retrieved from the video file: "max_cll", "max_fall", "red_primary_x", "red_primary_y", "green_primary_x", "green_primary_y", "blue_primary_x", "blue_primary_y", "white_point_x", "white_point_y", "min_mastering_luminance", "max_mastering_luminance".

GetHdmiInputStatus() As roAssociativeArray

Returns an associative array of Boolean and integer values if an HDMI input is currently connected to the device. This method will return Invalid if there is currently no HDMI input source. The associative array contains the following parameters:

GetCompositorCRC() As Integer

Returns the CRC of the Y and Cb signals as a single integer.

GetTxHDCPStatus() As roAssociativeArray

Returns an associative array indicating the current HDCP status of the HDMI output. The associative array currently contains a single key labeled state, which can have the following values:

ForceHDCPOn(force As Boolean) As Boolean

Forces HDCP authentication on the HDMI output if passed True. Passing False to this method will prevent forced authentication attempts with subsequent hotplug events. This method will return False if the player does not support HDCP or if ForceHDCPOn() has already been called with the same value.

DisableHDCPRepeater(disable As Boolean) As Boolean

Prevents HDCP authentication from taking place on the HDMI input if passed True. The HDMI source will treat the player like any other non-HDCP authenticated HDMI sink. This method returns False if the HDCP state could not be changed, indicating that there's no HDMI input on the player or that HDCP has already been disabled.

SetBackgroundColor(color As Integer) As Boolean

Specifies the background color using an #rrggbb hex value (8 bits for each color).

SetPowerSaveMode(power_save_enable As Boolean) As Boolean

Disables HDMI output, the syncs for VGA output, and the DAC output for component video. The absence of a signal will cause some monitors to go into standby mode.

IsAttached(connector As String) As Boolean

Returns True if the specified video connector is attached to an output device (i.e. the display EDID can be read successfully). This method can be passed the following parameters (note that they are case sensitive):

HdmiAudioDisable(disable As Boolean) As Boolean

Disables audio output if True. This method is set to False by default.

SetMultiscreenBezel(x_pct As Integer, y_pct As Integer) As Boolean

Adjusts the size of the bezel used in calculations for multiscreen displays, allowing for users to compensate for the width of their screen bezels. The calculations for the percentages are as follows:

x_percentage = (width_of_bezel_between_active_screens / width_of_active_screen) * 100

y_percentage = (height_of_bezel_between_active_screens / height_of_active_screen) * 100

The bezel measurement is therefore the total of the top and bottom bezels in the y case, or the left and right bezels in the x case. When this value is set correctly, images spread across multiple screens take account of the bezel widths, leading to better alignment of images.

SaveEdids(filename As String) As Boolean

Saves the EDID information of the display(s) connected via HDMI and/or VGA. The EDID fields are saved sequentially as raw binaries into the specified file. The EDID sets are two 2kb each, resulting in a maximum file size of 4kb. This method returns True upon success and False upon failure.

GetEdidIdentity(video_connector As Boolean) As roAssociativeArray

Returns an associative array with EDID information from a compatible monitor/television. Passing True with this method specifies EDID over HDMI, while passing False specifies EDID over VGA. These are the possible parameters returned in the associative array:

The system will generate an roHdmiEdidChanged event when an HDMI cable is hotplugged and the EDID information changes. Calling GetEdidIdentity(true) at this point retrieves the new EDID information.

SetMpcdi(parameters As roAssociativeArray) As Boolean

Enables MPCDI using the passed parameters. See the MPCDI tech note for more information about configuring MPCDI on BrightSign players.

SetSyncDomain(domain As String) As Boolean 

Enables Genlock synchronization on the specified roSyncManager domain. To disable Genlock on the domain, pass an empty string to this method. To reconfigure an active Genlock synchronization, call SetSyncDomain() again using the domain name of the new or edited roSyncManager instance.

ifMessagePort

SetPort(port As Object) As Void

Posts events to the attached message port

ifUserData

SetUserData(user_data As Object)

Sets the user data that will be returned when events are raised.

GetUserData() As Object

Returns the user data that has previously been set via SetUserData(). It will return Invalid if no data has been set.

"Auto" Video Mode 

If the video mode is set to "auto," the BrightSign player will use the following algorithm to determine the best video mode to use based on connected hardware:

  1. Try VGA: If VGA is supported (and attached), use the highest-resolution mode (as reported by the monitor) that the player supports.
  2. Try HDMI: If HDMI is attached, use the highest-resolution mode (as reported by the monitor) that the player supports.

    For 4K-capable models, auto mode will default to a maximum resolution of 3840x2160x60p. If you want a maximum default of 4096x2160x60p instead, call SetMode("4096x2160x60p:preferred").


  3. Default to 640x480x60p.
  4. If an HDMI hotplug event occurs at any point, recheck the monitor EDID to determine if the highest-resolution mode has changed. If it has changed, reboot the player and use the new video mode.

Selecting Decoders for Playback 

The system software selects which video decoder to use based on the resolution probed from the video file. In standard mode, it will attempt to select the decoder that has the closest maximum supported resolution (i.e. 1920x1080 for the HD decoder and 3840x2160 for the 4K decoder), without exceeding that maximum resolution. If a decoder has been configured for Mosaic mode, it will match the video resolution against the specified timeslice_mode instead. If both decoders support the same maximum resolution, you can select a decoder by matching the z-order of the roVideoPlayer instance (set using the ToFront() and ToBack() methods) with the z-order of the decoder (set using the roVideoMode.SetDecoderMode() method).

You can also select the decoder manually. First, configure the decoder(s) using the roVideoMode.SetDecoderMode() method. Then, use the friendly_name specified when calling the method to designate a decoder to use for video playback.

To select a decoder in BrightScript, pass an associative array to the roVideoPlayer.PlayFile() method containing the decoder:[friendly_name] parameter:

PlayFile({filename:"text_1.mov", decoder:"main-video"})

To select a decoder for HTML video, include the decoder:[friendly_name] property with the hwz attribute:

<video hwz="decoder:main-video;"> </video>
<video hwz="decoder:sd-video;"> </video>


The max_usage of a decoder determines how many video players can be assigned to the decoder using the system software algorithm described above—video players beyond the  max_usage limit may be assigned to another decoder or not displayed at all. On the other hand, if you manually assign video players using the friendly_name of the decoder, you can assign more video players to the decoder than the max_usage limit, but this may cause unpredictable video-display behavior.