Difference between revisions of "Linden Lab Official:Media Plugin System Messages"

From Second Life Wiki
Jump to navigation Jump to search
 
(85 intermediate revisions by 5 users not shown)
Line 1: Line 1:
{{Media Plugin Nav}}
{| align="right"
|--
|
{{:API Portal/navigation|media}}
|--
| 
|--
|
{{Media Messages AlphaList}}
|}
 
 
__TOC__
__TOC__
== Overview ==
== Overview ==


This article specifies the messages used by the Second Life Viewer media plugin system.
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|Base messages]]''' for initialization, connection management, and shared memory setup.  All plugins must implement these basic messages.
* '''[[#Media 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.
* '''[[#Media_browser_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.
* '''[[#Media_time_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|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|init_response]].
 
'''No parameters'''.
 
==== idle ====
 
Call-in for plugin to do processing.  No response required.
 
'''Parameters'''
 
{| class="lltable" border="1"
|--
!Key
!Type
!Description
 
|--
| time
| Real
| Interval (in seconds) at which idle messages are sent.
|}
 
==== cleanup ====
 
The plugin is about to be unloaded, and should perform any cleanup it needs to do beforehand.
 
'''No parameters'''.
 
==== shm_added ====
Shared memory segment has been set up.
 
'''Parameters'''
 
{| class="lltable" border="1"
|--
!Key
!Type
!Description
 
|--
| name
| String
| Supplied to the plugin by the Viewer.  Human-readable; plugin should not try to change.
 
|--
| size
| Integer
| 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|shm_remove_response]].
 
'''Parameters'''
 
{| class="lltable" border="1"
|--
!Key
!Type
!Description
 
|--
| name
| String
| Name of memory segment to remove.
|}
 
=== Messages from the plugin to the PLS ===
 
==== init_response ====


Arrows indicate which direction each message is sent: 
This message is the plugin's response to the [[#init|init]] message sent by the PLS.


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


< for plugin-to-host.
{| class="lltable" border="1"
|--
!Key
!Type
!Description


Keys for each command are set off as bullet items, like this:
|--
* foo: a sample argument
| versions
| Map
| Lists version corresponding to each plugin class.
* Key: message class name
* Value: version string.  All versions start at "1.0".


== Internal messages ==
|--
Sent between the viewer and the launcher shell <em>ONLY</em>.  Plugins will not need to handle these messages.
| 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.


; < 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 ==
==== shm_remove_response ====
All plugins need to handle these messages
 
Plugin is done with the shared memory segment, safe to delete.  Plugin responds with this message when it receives a [[#shm_remove|shm_remove]] message.
 
'''Parameters'''
 
{| class="lltable" border="1"
|--
!Key
!Type
!Description


; > init
|--
; < init_response
| name
* versions (map): LLSD key/value map, where each key is a message class and its value is a version string. 
| String
** All versions start at "1.0".
| Name of shared memory segment to delete.
** 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 ==
== Media messages ==
; < texture_params
 
* default_width (S32) OPTIONAL -- default width for the texture
=== Messages from the PLS to the plugin ===
* default_height (S32) OPTIONAL -- default height for the texture
 
* depth (S32) -- pixel size in bytes
==== load_uri ====
* internalformat (U32) -- texture internalformat for glTexImage2D
 
* format (U32) -- texture format for glTexImage2D
Tells the plugin to load the specified URI.
* 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
'''Parameters'''
** 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
{| class="lltable" border="1"
** 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.
!Key
* allow_downsample(bool) OPTIONAL -- If true, the host may negotiate a smaller texture when the plugin's priority is reduced.
!Type
** The plugin should not set this if downscaling the media is more expensive than drawing it at native size
!Description
* 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
| uri
** 16 -- start each row on a 16 byte boundary -- NOTE: may not work correctly with odd-sized pixels like GL_RGB
| String
** 32 -- start each row on a 32 byte boundary -- NOTE: may not work correctly with odd-sized pixels like GL_RGB
| URI to load.
; > load_uri
|}
* uri (string)
 
; > key_event
==== key_event ====
* event (string) one of:
 
** down
Simulates the user pressing a key on the keyboard.
** repeat
 
** up
'''Parameters'''
* 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 '|'.
{| class="lltable" border="1"
** control
|--
** alt -- means the 'option' key on the mac
!Key
** shift
!Type
** meta -- means the 'command' key on the mac
!Description
; > text_event -- text input event not associated with a single keystroke
 
* text(string) -- encoded in utf8
|--
; > mouse_event
| event
* event (string) : one of:
| String
** down
| One of:
** move
* down
** up
* repeat
** double_click
* up
* 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 '|'.
| key
** control
| String
** alt -- means the 'option' key on the mac
| Platform-specific keycode
** shift
 
** meta -- means the 'command' key on the mac
|--
; > scroll_event : scrollwheel
| modifiers
* x (integer) : horizontal scroll amount (positive or negative)
| String
* y (integer) : vertical scroll amount (positive or negative)
| Contains zero or more of the following, concatenated together with <nowiki>'|'</nowiki> characters in between.  There may be a spurious trailing <nowiki>'|'</nowiki>.
* modifiers -- string containing zero or more of the following, concatenated together with '|' characters in between.  There may be a spurious trailing '|'.
* control
** control
* alt -- the 'option' key on the mac
** alt -- means the 'option' key on the mac
* shift
** shift
* meta -- the 'command' key on the mac
** meta -- means the 'command' key on the mac
 
; < updated
|}
* left(S32)
 
* top(S32)
==== text_event ====
* right(S32)
 
* bottom(S32)
Text input event not associated with a single keystroke.
* current_time(float) OPTIONAL -- the current playhead time in seconds
 
* duration(float) OPTIONAL -- the total duration of the media in seconds
'''Parameters'''
* current_rate(float) OPTIONAL -- the rate at which the media is currently playing
 
; < media_status
{| class="lltable" border="1"
* status (string), one of:
|--
**<empty string> -- not initialized or no media loaded
!Key
**loading -- loading or navigating
!Type
**loaded -- preroll/navigation complete
!Description
**error -- navigation/preroll failed
 
**playing -- playing (only for time-based media)
|--
**paused -- paused (only for time-based media)
|text
; < size_change_request : when the stream wants to change its native size
| String
* width(S32)
| Encoded in utf8
* 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.
| modifiers
; > size_change: either host-initiated or after a request from the plugin
| String
* width(S32)
| Contains zero or more of the following, concatenated together with <nowiki>'|'</nowiki> characters in between.  There may be a spurious trailing <nowiki>'|'</nowiki>.
* height(S32)
* control
* texture_width(S32)
* alt -- the 'option' key on the mac
* texture_height(S32)
* shift
* name(string) -- the name of the shared memory segment the texture will draw into
* meta -- the 'command' key on the mac
; < size_change_response: sent by the plugin when the size change is complete
 
* width(S32)
|}
* height(S32)
 
* texture_width(S32)
==== mouse_event ====
* texture_height(S32)
 
* name(string) -- the name of the shared memory segment the texture will draw into
'''Parameters'''
; < cursor_changed
 
* name (string), one of:
{| class="lltable" border="1"
**<empty string>
|--
** arrow
!Key
** ibeam
!Type
** splith
!Description
** splitv
 
** hand
|--
; > set_priority : tells the plugin its relative priority
| event
* priority(string): one of:
| String
** stopped: media is not playing, shouldn't need to update at all
| One of:
** 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.  
* down
** low: media is in the far distance, may be rendered at reduced size
* move
** normal: default priority
* up
** high: media has user focus and/or is taking up most of the screen
* double_click
; > 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
|x
; < edit_state : update the state of the edit menu items in the host
|Integer
* cut(bool) OPTIONAL
| x-coordinate in texture space
* copy(bool) OPTIONAL
 
* paste(bool) OPTIONAL
|--
** items that are not present in the update message should have their state unchanged. 
| y  
** All states start out false in the host.
| Integer
** False means the operation is not possible and the menu should be disabled.
| 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 <nowiki>'|'</nowiki> characters in between.  There may be a spurious trailing <nowiki>'|'</nowiki>.
* control
* alt -- the 'option' key on the mac
* shift
* meta -- the 'command' key on the mac
 
|}
 
==== scroll_event ====
 
'''Parameters'''
 
{| class="lltable" border="1"
|--
!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 <nowiki>'|'</nowiki> characters in between.  There may be a spurious trailing <nowiki>'|'</nowiki>.
* 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'''
 
{| class="lltable" border="1"
|--
!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'''
 
{| class="lltable" border="1"
|--
!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 ====
 
'''Parameters'''
 
{| class="lltable" border="1"
|--
!Key
!Type
!Description
 
|--
| default_width
| Integer
| Optional. Default width for the texture.
 
|--
| default_height
| Integer
| Optional. Default height for the texture.
 
|--
| depth
| Integer
| Pixel size in bytes.  Although the the format and type parameters completely determine the pixel size, deriving it is complex.  Thus, the plugin must provide the value to the host.
 
|--
| internalformat
| String
| Texture internal format for glTexImage2D.  The value is a string containing hexadecimal digits, (for example, "0xDEADBEEF") representing a GLint.  See [[#GL_params|Note on OpenGL parameters]].
 
|--
| format
| String
| Texture format for glTexImage2D. The value is a string containing hexadecimal digits, (for example, "0xDEADBEEF") representing a GLenum.  See [[#GL_params|Note on OpenGL parameters]].
 
|--
| type
| String
| Texture type for glTexImage2D. The value is a string containing hexadecimal digits, (for example, "0xDEADBEEF") representing a GLenum.  See [[#GL_params|Note on OpenGL parameters]].
 
|--
| swap_bytes
| Boolean
| Optional.  True if the host should use <code>glPixelStorei(GL_UNPACK_SWAP_BYTES, 1)</code> 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|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 that 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
| Integer
| 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:''' It is 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.
 
|}
 
<span id="GL_params"></span>'''Note on OpenGL parameters''': The hexadecimal GLint and GLenum values used for internalformat, format and type are set by the OpenGL, so passing them across process boundaries is generally safe.
 
==== updated====
 
Specifies the update rectangle; the coordinates are specified within the buffer in which the media is being drawn.  The coords_opengl flag in [[#texture_params|texture_params]] message specifies how coordinatess are interpreted.
 
'''Parameters'''
 
{| class="lltable" border="1"
|--
!Key
!Type
!Description
 
|--
| left
| Integer
| Left x-coordinate of the update rectangle.
|--
| top
| Integer
| Top y-coordinate of the update rectangle.
|--
| right
| Integer
| Right x-coordinate of the update rectangle.
|--
| bottom
| Integer
| Bottom y-coordinate of the update rectangle.
|--
| 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 that 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'''
 
{| class="lltable" border="1"
|--
!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====
 
Specifies a name for the media being displayed.
 
'''Parameters'''
 
{| class="lltable" border="1"
|--
!Key
!Type
!Description
 
|--
| name
| String
| The name of the media. Typically the <code><title></code> tag in a Web page or the name in time based media.
 
|}
 
==== size_change_request ====
 
Indicates the stream wants to change its native size.
 
'''Parameters'''
 
{| class="lltable" border="1"
|--
!Key
!Type
!Description
 
|--
| width
| Integer
| Desired width in pixels.
 
|--
| height
| Integer
| Desired height in pixels.
 
|--
| name
| String
| Name of the shared memory segment the texture will draw into.  This may induce the host to send a [[#size_change|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|size_change]] when the size change is complete.
 
See [[Media_Rendering_Plugin_Operation_and_Data_Flow#Shared_memory_size_negotiation|Shared memory size negotiation]].
 
'''Parameters'''
 
{| class="lltable" border="1"
|--
!Key
!Type
!Description
 
|--
| width
| Integer
| Width in pixels.
 
|--
| height
| Integer
| Height in pixels.
 
|--
| texture_width
| Integer
| Width of texture in pixels; Number of pixels 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 pixels 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
|}
 
==== cursor_changed ====
 
'''Parameters'''
 
{| class="lltable" border="1"
|--
!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'''
 
{| class="lltable" border="1"
|--
!Key
!Type
!Description
 
|--
| cut
| Boolean
| Optional.
 
|--
| copy
| Boolean
| Optional.
 
|--
| paste
| Boolean
| Optional.
|}


== Media_browser messages ==
== Media_browser messages ==
; > focus
 
* focused (bool): true if the browser instance has focus
=== Messages from the PLS to the plugin ===
; > clear_cache
 
; > clear_cookies
==== focus ====
; > enable_cookies
 
* enable (bool)
Give the plugin focus.
; > proxy_setup
 
* enable (bool)
'''Parameters'''
* host (string)
 
* port (S32)
{| class="lltable" border="1"
; > browse_stop
|--
; > browse_reload
!Key
* ignore_cache(bool): if true, bypass cache for this reload
!Type
; > browse_forward
!Description
; > 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)
| focused  
* url(string): the URL to redirect to
| Boolean
; < navigate_begin
| True to give the plugin instance focus.
* uri (string): uri the browser is navigating to
|}
; < navigate_complete
 
* uri (string): uri the browser was navigating to
==== clear_cache ====
* result_code (S32): 200, 404, etc.
 
* result_string (string): "OK", "Not Found", etc.
Clear any cache that the plugin maintains.
* history_back_available (bool): true if the "back" button should be enabled
 
* history_forward_available (bool): true if the "forward" button should be enabled
'''No Parameters'''.
; < progress
 
* percent (S32): percent of page load that has completed
==== clear_cookies ====
; < status_text
 
* status (string): new browser status string
Clear any cookies that the plugin maintains.
; < location_changed
 
* uri (string): new browser uri for the navigation bar
'''No Parameters'''.
; < click_href
 
* uri (string): uri of the link
==== enable_cookies ====
* target (string): target property of the link
 
; < click_nofollow
Enable or disable use of cookies.
* uri (string): uri of the link
 
; > init_history
'''Parameters'''
* history (LLSD, array of strings): array of string URIs to add to the browser history
 
{| class="lltable" border="1"
|--
!Key
!Type
!Description
 
|--
|enable
|Boolean
|Whether to enable cookies.
|}
 
==== proxy_setup ====
 
Use a proxy and specify proxy settings.
 
'''Parameters'''
 
{| class="lltable" border="1"
|--
!Key
!Type
!Description
 
|---
| enable  
|Boolean
| Set to tru to enable using the spedcified proxy server.
 
|---
| host
| String
| Hostname of the proxy.
 
|---
| port
| Integer
| TCP port to use.
|}
 
==== browse_stop ====
 
'''No Parameters'''.
 
==== browse_reload ====
 
Reload the media stream.
 
'''Parameters'''
 
{| class="lltable" border="1"
|--
!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'''
 
{| class="lltable" border="1"
|--
!Key
!Type
!Description
 
|---
| code
| Integer
| The HTTP status code on which to redirect (currently, only 404).
 
|---
| url
| String
| URL to which to redirect.
|}
 
==== init_history ====
'''Parameters'''
 
{| class="lltable" border="1"
|--
!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'''
 
{| class="lltable" border="1"
|--
!Key
!Type
!Description
 
|---
| uri  
| String
| URI to which the browser is navigating.
 
|}
 
==== navigate_complete ====
 
'''Parameters'''
 
{| class="lltable" border="1"
|--
!Key
!Type
!Description
|---
| uri  
| String
| URI to which the browser was navigating.
 
|---
| result_code
| Integer
| 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'''
 
{| class="lltable" border="1"
|--
!Key
!Type
!Description
|---
| percent
| Integer
| Percent of page load that has completed; between zero (0) and 100, inclusive.
 
|}
 
==== status_text ====
 
'''Parameters'''
 
{| class="lltable" border="1"
|--
!Key
!Type
!Description
|---
| status  
| String
| New browser status string.
 
|}
 
==== location_changed ====
 
'''Parameters'''
 
{| class="lltable" border="1"
|--
!Key
!Type
!Description
 
|---
| uri  
| String
| New browser URI for the navigation bar.
 
|}
 
==== click_href ====
 
Occurs when the user clicks on a link. 
 
'''Parameters'''
 
{| class="lltable" border="1"
|--
!Key
!Type
!Description
|---
| uri  
| String
| URI of the link.
 
|---
| target  
| String
| Target property of the link.
 
|}
 
==== click_nofollow ====
 
'''Parameters'''
 
{| class="lltable" border="1"
|--
!Key
!Type
!Description
 
|---
| uri  
| String
| URI of the link.
 
|}


== Media_time messages ==
== Media_time messages ==
; > stop
 
; > start
=== Messages from the PLS to the plugin ===
* 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
==== stop ====
; > seek
 
* time (float)
'''No parameters'''.
; > set_loop
 
* loop (boolean): true to make the media loop, false to make it play once
==== start ====
; > set_volume
 
* volume (float)
{| class="lltable" border="1"
|--
!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 ====
 
{| class="lltable" border="1"
|--
!Key
!Type
!Description
 
|---
| time  
| Real
| The point in the stream to Time in seconds.  Host will know the duration of the media from the [#updated|updated] message.
 
|}
 
==== set_loop ====
 
{| class="lltable" border="1"
|--
!Key
!Type
!Description
|---
| loop  
| Boolean
| True to make the media loop, false to make it play once.
 
|}
 
==== set_volume ====
 
{| class="lltable" border="1"
|--
!Key
!Type
!Description
 
|---
| volume  
| Real
| Muted is zero (0) and full volume is 1.0.
 
|}

Latest revision as of 14:34, 4 May 2011

 


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 sent.

cleanup

The plugin is about to be unloaded, and should perform any cleanup it needs to do beforehand.

No parameters.

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 Integer 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

Tells the plugin to load the specified URI.

Parameters

Key Type Description
uri String URI to load.

key_event

Simulates the user pressing a key on the keyboard.

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

Parameters

Key Type Description
default_width Integer Optional. Default width for the texture.
default_height Integer Optional. Default height for the texture.
depth Integer Pixel size in bytes. Although the the format and type parameters completely determine the pixel size, deriving it is complex. Thus, the plugin must provide the value to the host.
internalformat String Texture internal format for glTexImage2D. The value is a string containing hexadecimal digits, (for example, "0xDEADBEEF") representing a GLint. See Note on OpenGL parameters.
format String Texture format for glTexImage2D. The value is a string containing hexadecimal digits, (for example, "0xDEADBEEF") representing a GLenum. See Note on OpenGL parameters.
type String Texture type for glTexImage2D. The value is a string containing hexadecimal digits, (for example, "0xDEADBEEF") representing a GLenum. See Note on OpenGL parameters.
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 that 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 Integer 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: It is 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.

Note on OpenGL parameters: The hexadecimal GLint and GLenum values used for internalformat, format and type are set by the OpenGL, so passing them across process boundaries is generally safe.

updated

Specifies the update rectangle; the coordinates are specified within the buffer in which the media is being drawn. The coords_opengl flag in texture_params message specifies how coordinatess are interpreted.

Parameters

Key Type Description
left Integer Left x-coordinate of the update rectangle.
top Integer Top y-coordinate of the update rectangle.
right Integer Right x-coordinate of the update rectangle.
bottom Integer Bottom y-coordinate of the update rectangle.
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 that 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:
  • <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

Specifies a name for the media being displayed.

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

Indicates the stream wants to change its native size.

Parameters

Key Type Description
width Integer Desired width in pixels.
height Integer Desired height in pixels.
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.

See Shared memory size negotiation.

Parameters

Key Type Description
width Integer Width in pixels.
height Integer Height in pixels.
texture_width Integer Width of texture in pixels; Number of pixels 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 pixels 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

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

Give the plugin focus.

Parameters

Key Type Description
focused Boolean True to give the plugin instance focus.

clear_cache

Clear any cache that the plugin maintains.

No Parameters.

clear_cookies

Clear any cookies that the plugin maintains.

No Parameters.

enable_cookies

Enable or disable use of cookies.

Parameters

Key Type Description
enable Boolean Whether to enable cookies.

proxy_setup

Use a proxy and specify proxy settings.

Parameters

Key Type Description
enable Boolean Set to tru to enable using the spedcified proxy server.
host String Hostname of the proxy.
port Integer TCP port to use.

browse_stop

No Parameters.

browse_reload

Reload the media stream.

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 Integer The HTTP status code on which to redirect (currently, only 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 Integer 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 Integer Percent of page load that has completed; between zero (0) and 100, inclusive.

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:
  • 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 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.
Retrieved from "https://wiki.secondlife.com/w/index.php?title=Linden_Lab_Official:Media_Plugin_System_Messages&oldid=1142379"