Linden Lab Official:Media Plugin System Messages

From Second Life Wiki
Jump to navigation Jump to search

Overview

This article specifies the messages used by the Second Life Viewer media plugin system.

Arrows indicate which direction each message is sent:

> for host-to-plugin (or host-to-launcher shell for internal messages)

< for plugin-to-host.

Keys for each command are set off as bullet items, like this:

  • foo: a sample argument

Internal messages

Sent between the viewer and the launcher shell ONLY. Plugins will not need to handle these messages.

< hello
first command sent from the launcher shell to the viewer when it comes up
> load_plugin
tells the loader to load a plugin and send the base init message
  • file (string): the full path to the plugin DLL/dylib/so file.
< load_plugin_response
plugin loaded and initialized
  • versions (map): LLSD key/value map, where each key is a message class and its value is a version string. All versions start at "1.0".
  • plugin_version (string): Freeform version string for the plugin itself. This is expected to contain the versions of libraries the plugin uses (i.e. quicktime, webkit, etc.) and may end up in the viewer's about box.
< heartbeat
plugin launcher shell sends these once per second to show that the plugin isn't locked up
> shm_add
shared memory segment has been set up in the parent
  • name (string)
  • size (S32)
< shm_add_response
shared memory has been mapped into the child
  • name (string)
> shm_remove
shared memory segment will be removed once you respond
  • name (string)
< shm_remove_response
plugin is done with the shared memory segment, safe to delete
  • name (string)
> sleep_time
set the interval between idle messages to the plugin
  • time (float): time in seconds (default is 1/100)

Base messages

All plugins need to handle these messages

> init
< init_response
  • versions (map): LLSD key/value map, where each key is a message class and its value is a version string.
    • All versions start at "1.0".
    • the host will need to check these against what it understands and send the proper versions of each message set to the plugin
  • plugin_version (string): Freeform version string for the plugin itself. This is expected to contain the versions of libraries the plugin uses (i.e. quicktime, webkit, etc.) and may end up in the viewer's about box.
> idle
call-in for plugin to do processing, no response
  • time (float): 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
  • name (string)
  • size (S32)
  • address (string)
    • Since this is going from the loader shell to the plugin (i.e. 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 pointer's value as a hexadecimal string
> shm_remove
shared memory segment will be removed once you respond
  • name (string)
< shm_remove_response
plugin is done with the shared memory segment, safe to delete
  • name (string)

Media messages

< texture_params
  • default_width (S32) OPTIONAL -- default width for the texture
  • default_height (S32) OPTIONAL -- default height for the texture
  • depth (S32) -- pixel size in bytes
  • internalformat (U32) -- texture internalformat for glTexImage2D
  • format (U32) -- texture format for glTexImage2D
  • type (U32) -- texture type for glTexImage2D
  • swap_bytes(bool) 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(bool) -- 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
    • Note that the hexadecimal GLenum values for these 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.
  • allow_downsample(bool) 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
  • padding(S32) 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
> load_uri
  • uri (string)
> key_event
  • event (string) one of:
    • down
    • repeat
    • up
  • key(S32) -- platform-specific keycode
  • modifiers -- string containing zero or more of the following, concatenated together with '|' characters in between. There may be a spurious trailing '|'.
    • control
    • alt -- means the 'option' key on the mac
    • shift
    • meta -- means the 'command' key on the mac
> text_event -- text input event not associated with a single keystroke
  • text(string) -- encoded in utf8
> mouse_event
  • event (string) : one of:
    • down
    • move
    • up
    • double_click
  • x -- x coordinate in texture space
  • y -- y coordinate in texture space (taking into account whether vertical flip was requested or not)
  • modifiers -- string containing zero or more of the following, concatenated together with '|' characters in between. There may be a spurious trailing '|'.
    • control
    • alt -- means the 'option' key on the mac
    • shift
    • meta -- means the 'command' key on the mac
> scroll_event
scrollwheel
  • x (integer) : horizontal scroll amount (positive or negative)
  • y (integer) : vertical scroll amount (positive or negative)
  • modifiers -- string containing zero or more of the following, concatenated together with '|' characters in between. There may be a spurious trailing '|'.
    • control
    • alt -- means the 'option' key on the mac
    • shift
    • meta -- means the 'command' key on the mac
< updated
  • left(S32)
  • top(S32)
  • right(S32)
  • bottom(S32)
  • current_time(float) OPTIONAL -- the current playhead time in seconds
  • duration(float) OPTIONAL -- the total duration of the media in seconds
  • current_rate(float) OPTIONAL -- the rate at which the media is currently playing
< media_status
  • 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)
< size_change_request
when the stream wants to change its native size
  • width(S32)
  • height(S32)
  • name(string) -- the name of the shared memory segment the texture will draw into
    • this may or may not 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
either host-initiated or after a request from the plugin
  • width(S32)
  • height(S32)
  • texture_width(S32)
  • texture_height(S32)
  • name(string) -- the name of the shared memory segment the texture will draw into
< size_change_response
sent by the plugin when the size change is complete
  • width(S32)
  • height(S32)
  • texture_width(S32)
  • texture_height(S32)
  • name(string) -- the name of the shared memory segment the texture will draw into
< cursor_changed
  • name (string), one of:
    • <empty string>
    • arrow
    • ibeam
    • splith
    • splitv
    • hand
> set_priority
tells the plugin its relative priority
  • 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.
    • 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
do an edit-menu "cut" operation to the system clipboard
> edit_copy
do an edit-menu "copy" operation to the system clipboard
> edit_paste
do an edit-menu "paste" operation from the system clipboard
< edit_state
update the state of the edit menu items in the host
  • cut(bool) OPTIONAL
  • copy(bool) OPTIONAL
  • paste(bool) OPTIONAL
    • 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.

Media_browser messages

> focus
  • focused (bool): true if the browser instance has focus
> clear_cache
> clear_cookies
> enable_cookies
  • enable (bool)
> proxy_setup
  • enable (bool)
  • host (string)
  • port (S32)
> browse_stop
> browse_reload
  • ignore_cache(bool): if true, bypass cache for this reload
> browse_forward
> browse_back
> set_status_redirect (we use a 404 redirect in Web based search)
  • code(S32): the code to redirect on (should only be 404 for now)
  • url(string): the URL to redirect to
< navigate_begin
  • uri (string): uri the browser is navigating to
< navigate_complete
  • uri (string): uri the browser was navigating to
  • result_code (S32): 200, 404, etc.
  • result_string (string): "OK", "Not Found", etc.
  • history_back_available (bool): true if the "back" button should be enabled
  • history_forward_available (bool): true if the "forward" button should be enabled
< progress
  • percent (S32): percent of page load that has completed
< status_text
  • status (string): new browser status string
< location_changed
  • uri (string): new browser uri for the navigation bar
< click_href
  • uri (string): uri of the link
  • target (string): target property of the link
< click_nofollow
  • uri (string): uri of the link
> init_history
  • history (LLSD, array of strings): array of string URIs to add to the browser history

Media_time messages

> stop
> start
  • rate (float) 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, etc.
> pause
> seek
  • time (float)
> set_loop
  • loop (boolean): true to make the media loop, false to make it play once
> set_volume
  • volume (float)