Linden Lab Official:Media Plugin System Messages
Overview
This article specifies the messages used in the Second Life Viewer media rendering plugin system. These messages are used to communicate between each plugin loader shell (PLS) and its media rendering plugin, and between each PLS and the Viewer.
Message categories
Messages fall into these general categories:
- Base messages for initialization, connection management, and shared memory setup. All plugins must implement these basic messages.
- Media messages for negotiating the pixel buffer and handling updates of subsections of it, specifying a media source URL, and passing mouse and keyboard events. All media rendering plugins must implement these messages.
- Time-based media messages for functions such as play, pause, stop, seek, and so on. All time-based media (video-like) rendering plugins must implement these messages.
- Browser-like media messages for functions such as forward, back, reload, and so on. All browser-like media rendering plugins must implement these messages.
- Internal system messages for communication between the viewer and the plugin loader shell. These messages are not delivered to a plugin. Plugin developers need not be concerned with them; their documentation is provided for Viewer developers.
Base messages
All plugins need to handle these messages.
Messages from the PLS to the plugin
init
Initialization message the PLS sends. Plugin responds with init_response.
No parameters.
idle
Call-in for plugin to do processing. No response required.
Parameters
Key | Type | Description |
---|---|---|
time | Real | interval (in seconds) at which idle messages are being sent. |
cleanup
The plugin is about to be unloaded, and should perform any cleanup it needs to do beforehand.
shm_added
Shared memory segment has been set up.
Parameters
Key | Type | Description |
---|---|---|
name | String | Supplied to the plugin by the Viewer. Human-readable; plugin should not try to change. |
size | String | Size of segment in bytes. |
address | String | Since this is going from the PLS to the plugin (not crossing a process boundary),
the pointer will actually be valid. LLSD doesn't have an encoding for a pointer (or even an unsigned 32 bit value), so this will be the full pointer (either 32 or 64 bits, depending on the pointer size of the platform) as a hexadecimal string. |
shm_remove
PLS will remove the shared memory segment. The segment will be effectively removed when plugin responds with shm_remove_response.
Parameters
Key | Type | Description |
---|---|---|
name | String | Name of memory segment to remove. |
Messages from the plugin to the PLS
init_response
This message is the plugin's response to the init message sent by the PLS.
Parameters
Key | Type | Description |
---|---|---|
versions | Map | Lists version corresponding to each plugin class.
|
plugin_version | String | Free-form version string for the plugin. This is expected to contain the versions of libraries the plugin uses (for example, quicktime, webkit, and so on) and may end up in the Viewer's about box. |
shm_remove_response
Plugin is done with the shared memory segment, safe to delete. Plugin responds with this message when it receives a shm_remove message.
Parameters
Key | Type | Description |
---|---|---|
name | String | Name of shared memory segment to delete. |
Media messages
Messages from the PLS to the plugin
load_uri
Parameters
Key | Type | Description |
---|---|---|
uri | String | URI to load. |
key_event
Parameters
Key | Type | Description |
---|---|---|
event | String | One of:
|
key | String | Platform-specific keycode |
modifiers | String | Contains zero or more of the following, concatenated together with '|' characters in between. There may be a spurious trailing '|'.
|
text_event
Text input event not associated with a single keystroke.
Parameters
Key | Type | Description |
---|---|---|
text | String | Encoded in utf8 |
modifiers | String | Contains zero or more of the following, concatenated together with '|' characters in between. There may be a spurious trailing '|'.
|
mouse_event
Parameters
Key | Type | Description |
---|---|---|
event | String | One of:
|
x | Integer | x-coordinate in texture space |
y | Integer | Y-coordinate in texture space (taking into account whether vertical flip was requested or not). |
button | Integer | Mouse button number associated with this event. If this parameter is not present, assume the left button.
|
modifiers | String | Contains zero or more of the following, concatenated together with '|' characters in between. There may be a spurious trailing '|'.
|
scroll_event
Parameters
Key | Type | Description |
---|---|---|
x | Integer | x-horizontal scroll steps |
y | Integer | Y-vertical scroll steps |
modifiers | String | Contains zero or more of the following, concatenated together with '|' characters in between. There may be a spurious trailing '|'.
|
size_change
Either host-initiated or after a request from the plugin.
Parameters
Key | Type | Description |
---|---|---|
width | Integer | Width in pixels; size at which the plugin is expected to render |
height | Integer | Height in pixels |
texture_width | Integer | Width of texture in pixels; Number of pixesl in the buffer its being asked to draw into. May be larger than width parameter value. |
texture_height | Integer | Height of texture in pixels; Number of pixesl in the buffer its being asked to draw into. May be larger than height parameter value. |
name | String | Name of the shared memory segment the texture will draw into. Matches with the name in an shm_added. |
set_priority
Tells the plugin its relative priority.
Parameters
Key | Type | Description |
---|---|---|
priority | String | One of:
|
edit_cut
Perform an edit-menu "cut" operation to the system clipboard.
No parameters
edit_copy
Perform an edit-menu "copy" operation to the system clipboard.
No parameters
edit_paste
Perform an edit-menu "paste" operation from the system clipboard.
No parameters
Messages from the plugin to the PLS
texture_params
- Note that the hexadecimal GLint and GLenum values used for internalformat, format and type are fixed by the OpenGL ARB, so passing them across process boundaries should be safe.
- Although the pixel size in bytes is completely determined by the format and type, deriving it from only those values is complex. To simplify things, the plugin must provide the pixel size to the host.
Parameters
Key | Type | Description |
---|---|---|
default_width | String | Optional. Default width for the texture. |
default_height | String | Optional. Default height for the texture. |
depth | String | Pixel size in bytes. |
internalformat | String | Texture internal format for glTexImage2D. The value is a string containing hexadecimal digits, (e.g. "0xDEADBEEF") representing a GLint. |
format | String | Texture format for glTexImage2D. The value is a string containing hexadecimal digits, (e.g. "0xDEADBEEF") representing a GLenum. |
type | String | Texture type for glTexImage2D. The value is a string containing hexadecimal digits, (e.g. "0xDEADBEEF") representing a GLenum. |
swap_bytes | Boolean | Optional. True if the host should use glPixelStorei(GL_UNPACK_SWAP_BYTES, 1) when loading the data. If not specified, defaults to false. |
coords_opengl | Boolean | True if the plugin wants to work in OpenGL coordinates (where (0,0) is the lower left corner of the texture), false to work in a coordinate system where (0,0) is the upper left. |
allow_downsample | Boolean | Optional. If true, the host may negotiate a smaller texture when the plugin's priority is reduced. The plugin should not set this if downscaling the media is more expensive than drawing it at native size.
If the plugin sets the allow_downsample field in the texture_params message and the media's priority has been lowered, the host may reduce the requested draw dimensions.
|
padding | String | Optional. Specifies how the rows of the texture should be padded. Useful values:
Note that it's possible to request pixel size/alignment combinations that don't come out even when using 3-byte RGB pixels. If the host detects this, it will disable padding. |
updated
The update rectangle; Coordinates within the buffer that is being drawn in.
coords_opengl flag in #texture_params specifies how coords are interpreted.
Parameters
Key | Type | Description |
---|---|---|
left | Integer | |
top | Integer | |
right | Integer | |
bottom | Integer | |
current_time | Real | Optional. Current playhead time in seconds. |
duration | Real | Optional. Total duration of the media in seconds |
current_rate | Real | Optional. Rate at which the media is currently playing. |
loaded_duration | Real | Optional. For media which is partially loaded, the duration through which the media could currently play or seek. For media which can't be loaded incrementally, either omit this parameter or set it to the same value as 'duration'. |
media_status
Plugin describing the state to the PLS.
Parameters
Key | Type | Description |
---|---|---|
status | String | One of:
|
name_text
Parameters
Key | Type | Description |
---|---|---|
name | String | The name of the media. Typically the <title> tag in a Web page or the name in time based media. |
size_change_request
When the stream wants to change its native size.
Parameters
Key | Type | Description |
---|---|---|
width | Integer | |
height | Integer | |
name | String | Name of the shared memory segment the texture will draw into. This may induce the host to send a size_change message. The plugin may stop drawing to the texture until an appropriate size_change message has been received. |
size_change_response
Sent by the plugin in response to size_change when the size change is complete.
Parameters
Key | Type | Description |
---|---|---|
width | String | |
height | String | |
texture_width | String | |
texture_height | String | |
name | String | Name of the shared memory segment the texture will draw into |
cursor_changed
Parameters
Key | Type | Description |
---|---|---|
name | String | One of:
|
edit_state
Update the state of the edit menu items in the host. Note:
- items that are not present in the update message should have their state unchanged.
- All states start out false in the host.
- False means the operation is not possible and the menu should be disabled.
Parameters
Key | Type | Description |
---|---|---|
cut | Boolean | OPTIONAL |
copy | Boolean | OPTIONAL |
paste | Boolean | OPTIONAL |
Media_browser messages
Messages from the PLS to the plugin
focus
Parameters
Key | Type | Description |
---|---|---|
focused | Boolean | true if the browser instance has focus |
clear_cache
No Parameters.
clear_cookies
No Parameters.
enable_cookies
Parameters
Key | Type | Description |
---|---|---|
enable | Boolean | Whether to enable cookies. |
proxy_setup
Parameters
Key | Type | Description |
---|---|---|
enable | Boolean | |
host | String | |
port | String |
browse_stop
No Parameters.
browse_reload
Parameters
Key | Type | Description |
---|---|---|
ignore_cache | Boolean | If true, bypass cache for this reload. |
browse_forward
No Parameters.
browse_back
No Parameters.
set_status_redirect
Parameters
Key | Type | Description |
---|---|---|
code | String | The HTTP status code on which to redirect (currently, only be 404). |
url | String | URL to which to redirect. |
init_history
Parameters
Key | Type | Description |
---|---|---|
history | Array of strings | Array of string URIs to add to the browser history. |
Messages from the plugin to the PLS
Parameters
Key | Type | Description |
---|---|---|
uri | String | URI to which the browser is navigating. |
Parameters
Key | Type | Description |
---|---|---|
uri | String | URI to which the browser was navigating. |
result_code | String | For example, 200, 404. |
result_string | String | "OK", "Not Found", etc. |
history_back_available | Boolean | True if the "back" button should be enabled |
history_forward_available | Boolean | True if the "forward" button should be enabled |
progress
Parameters
Key | Type | Description |
---|---|---|
percent | String | Percent of page load that has completed |
status_text
Parameters
Key | Type | Description |
---|---|---|
status | String | New browser status string. |
location_changed
Parameters
Key | Type | Description |
---|---|---|
uri | String | New browser URI for the navigation bar. |
click_href
Occurs when the user clicks on a link.
Parameters
Key | Type | Description |
---|---|---|
uri | String | URI of the link. |
target | String | Target property of the link. |
click_nofollow
Parameters
Key | Type | Description |
---|---|---|
uri | String | URI of the link. |
Media_time messages
Messages from the PLS to the plugin
stop
No parameters.
start
Key | Type | Description |
---|---|---|
rate | Real | Optional. Rate to play at:
|
pause
No parameters.
seek
Key | Type | Description |
---|---|---|
time | Real | updated] message. |
set_loop
Key | Type | Description |
---|---|---|
loop | Boolean | True to make the media loop, false to make it play once. |
set_volume
Key | Type | Description |
---|---|---|
volume | Real | Muted is zero (0) and full volume is 1.0. |