Linden Lab Official:Media Plugin System Messages

Media Rendering Plugin System Frequently Asked Questions Technical Overview Using the Plugin Test App Getting Started Hello World Plugin Code Plugin Operation and Data Flow Messages Internal 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. Key: message class name Value: version string. All versions start at "1.0".
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: down repeat up
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 '|'. control alt -- the 'option' key on the mac shift meta -- the 'command' key on the mac

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 '|'. control alt -- the 'option' key on the mac shift meta -- the 'command' key on the mac

mouse_event

Parameters

Key	Type	Description
event	String	One of: down move up double_click
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. 0 -- left button 1 -- right button 2 -- middle button higher numbers are not specifically assigned
modifiers	String	Contains zero or more of the following, concatenated together with '|' characters in between. There may be a spurious trailing '|'. control alt -- the 'option' key on the mac shift meta -- the 'command' key on the mac

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 '|'. control alt -- the 'option' key on the mac shift meta -- the 'command' key on the mac

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: stopped: media is not playing, shouldn't need to update at all hidden: media is not being displayed or is out of view, don't need to do graphic updates, but may still update audio, playhead, etc. slideshow: media is being displayed, but is being severely throttled to reduce resource usage low: media is in the far distance, may be rendered at reduced size normal: default priority high: media has user focus and/or is taking up most of the screen

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. The plugin should only set allow_downsample if it can draw the media at different scales without changing the overall look of the media, such as scaling down a video stream Media which looks different when drawn at different pixel scales (such as a web browser where font sizes depend on pixel scale) should NOT set allow_downsample If it's more expensive to draw media downsampled than at native resolution, the plugin should NOT set allow_downsample: it's supposed to be a way to reduce load on the system, and if it doesn't accomplish that it shouldn't be used.
padding	String	Optional. Specifies how the rows of the texture should be padded. Useful values: 0 (the default) -- no padding is added -1 -- pad width to the next power of two 16 -- start each row on a 16 byte boundary -- NOTE: may not work correctly with odd-sized pixels like GL_RGB 32 -- start each row on a 32 byte boundary -- NOTE: may not work correctly with odd-sized pixels like GL_RGB 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

Parameters

Key	Type	Description
status	String	One of: <empty string> -- not initialized or no media loaded loading -- loading or navigating loaded -- preroll/navigation complete error -- navigation/preroll failed playing -- playing (only for time-based media) paused -- paused (only for time-based media)

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: <empty string> arrow ibeam splith splitv hand

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

navigate_begin

Parameters

Key	Type	Description
uri	String	URI to which the browser is navigating.

navigate_complete

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

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: 0.0 is the movie's default rate. 1.0 is normal forward (on most movies). -1.0 is reverse. Greater than 1.0 is fast foward. Less than 1.0 is slow motion.

pause

No parameters.

seek

Key	Type	Description
time	Real	Unit? ms, s, ticks, other...

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	Units? "Most go to 10 but ours go to 11"