llSetLinkMedia

function

Function syntax

integer llSetLinkMedia(

integer link,// Link number (1 for root, >1 for children) or a LINK_* flag. Values: Link
integer face,// Face number (side) of the prim. Values: Faces
list params// A set of property-value pairs (in no particular order) specifying media parameters, or a PrimMediaParams dictionary.

);

Returns: integer
Energy: 10

Set the media params for a particular face on the linked prim(s) without a delay.

Returns an integer that is a STATUS_* flag which details the success/failure of the operation(s).

integer result = llSetLinkMedia(0, 0, []);

Specification

From the LSL definitions: PrimMediaParam (rule, then its arguments)

// AddressPRIM_MEDIA_CURRENT_URL, string current_url  // at most 1024 characters; setting it navigatesPRIM_MEDIA_HOME_URL, string home_url  // at most 1024 characters// PlaybackPRIM_MEDIA_AUTO_PLAY, integer boolean  // plays when a resident can see itPRIM_MEDIA_AUTO_LOOP, integer booleanPRIM_MEDIA_AUTO_SCALE, integer boolean  // media fills the facePRIM_MEDIA_AUTO_ZOOM, integer boolean  // a click zooms and focusesPRIM_MEDIA_FIRST_CLICK_INTERACT, integer boolean  // TRUE passes the first click to the page// SizePRIM_MEDIA_WIDTH_PIXELS, integer width  // 0 to 2048; rounded up to a power of twoPRIM_MEDIA_HEIGHT_PIXELS, integer height  // 0 to 2048; rounded up to a power of two// Controls and accessPRIM_MEDIA_CONTROLS, integer control  // PRIM_MEDIA_CONTROLS_STANDARD or _MINIPRIM_MEDIA_PERMS_INTERACT, integer perms  // PRIM_MEDIA_PERM_*: who can interactPRIM_MEDIA_PERMS_CONTROL, integer perms  // PRIM_MEDIA_PERM_*: who sees the control barPRIM_MEDIA_WHITELIST_ENABLE, integer boolean  // navigation limited to the whitelistPRIM_MEDIA_WHITELIST, string CSV  // escaped URLs; up to 64 or 1024 charactersPRIM_MEDIA_ALT_IMAGE_ENABLE, integer boolean  // not implemented

Constant	Type	Value	Description
`STATUS_OK`	integer	`0`	Result of function call was success
`STATUS_MALFORMED_PARAMS`	integer	`1000`	Function was called with malformed parameters
`STATUS_TYPE_MISMATCH`	integer	`1001`	Argument(s) passed to function had a type mismatch
`STATUS_BOUNDS_ERROR`	integer	`1002`	Argument(s) passed to function had a bounds error
`STATUS_NOT_FOUND`	integer	`1003`	Object or other item was not found
`STATUS_NOT_SUPPORTED`	integer	`1004`	Feature not supported
`STATUS_INTERNAL_ERROR`	integer	`1999`	An internal error occurred
`STATUS_WHITELIST_FAILED`	integer	`2001`	Whitelist Failed

Success/Failure Flags		Description

Constant	Type	Value	Description
`PRIM_MEDIA_ALT_IMAGE_ENABLE`	integer	`0`
`PRIM_MEDIA_CONTROLS`	integer	`1`
`PRIM_MEDIA_CONTROLS_STANDARD`	integer	`0`	Standard web navigation controls.
`PRIM_MEDIA_CONTROLS_MINI`	integer	`1`	Mini web navigation controls; does not include an address bar.
`PRIM_MEDIA_CURRENT_URL`	integer	`2`
`PRIM_MEDIA_HOME_URL`	integer	`3`
`PRIM_MEDIA_AUTO_LOOP`	integer	`4`
`PRIM_MEDIA_AUTO_PLAY`	integer	`5`
`PRIM_MEDIA_AUTO_SCALE`	integer	`6`
`PRIM_MEDIA_AUTO_ZOOM`	integer	`7`
`PRIM_MEDIA_FIRST_CLICK_INTERACT`	integer	`8`
`PRIM_MEDIA_WIDTH_PIXELS`	integer	`9`
`PRIM_MEDIA_HEIGHT_PIXELS`	integer	`10`
`PRIM_MEDIA_WHITELIST_ENABLE`	integer	`11`
`PRIM_MEDIA_WHITELIST`	integer	`12`
`PRIM_MEDIA_PERMS_INTERACT`	integer	`13`
`PRIM_MEDIA_PERMS_CONTROL`	integer	`14`

Parameter		Additional Parameters		Description
[ integer boolean ]		Sets the default image state (the image that the user sees before a piece of media is active) for the chosen face. The default image is specified by Second Life’s server for that media type. Note: This flag is not currently implemented.
[ integer control ]		Sets the style of controls. Can be either `PRIM_MEDIA_CONTROLS_STANDARD` or `PRIM_MEDIA_CONTROLS_MINI`.
controls Flags		Description
[ string current_url ]		Sets the current url displayed on the chosen face. Changing this URL causes navigation. 1024 characters Max
[ string home_url ]		Sets the home url for the chosen face. 1024 characters max
[ integer boolean ]		Sets whether auto-looping is enabled.
[ integer boolean ]		Sets whether the media auto-plays when a Resident can view it.
[ integer boolean ]		Sets whether auto-scaling is enabled. Auto-scaling forces the media to the full size of the texture.
[ integer boolean ]		Sets whether clicking the media triggers auto-zoom and auto-focus on the media.
[ integer boolean ]		Sets what happens when someone click on a playing, but unfocused media face: `TRUE`: Does the same thing a focused media face does, and forwards the click to the web browser. `FALSE`: Focuses the media prim so that future clicks are forwarded to the web browser. Note: Viewer settings affect this flag. It works by default on most prims.
[ integer width ]		Sets the width of the media in pixels.
[ integer height ]		Sets the height of the media in pixels.
[ integer boolean ]		Sets whether navigation is restricted to URLs in `PRIM_MEDIA_WHITELIST`.
[ string CSV ]		Sets the whitelist as a string of `escaped`, comma-separated URLs. This string can hold up to 64 URLs or 1024 characters, whichever comes first.
[ integer perms ]		Sets the permissions mask that control who can interact with the object: `PRIM_MEDIA_PERM_NONE` `PRIM_MEDIA_PERM_OWNER` `PRIM_MEDIA_PERM_GROUP` `PRIM_MEDIA_PERM_ANYONE`
[ integer perms ]		Sets the permissions mask that control who can see the media control bar above the object: `PRIM_MEDIA_PERM_NONE` `PRIM_MEDIA_PERM_OWNER` `PRIM_MEDIA_PERM_GROUP` `PRIM_MEDIA_PERM_ANYONE`

Caveats

If prim media is not already on this object, it will be added.
If prim media is newly added to this object, params not specified take their default value.
If prim media is already on this object, params not specified are unchanged.
About PRIM_MEDIA_WIDTH_PIXELS (width) and PRIM_MEDIA_HEIGHT_PIXELS (height) …
Both width and height must be specified for either to work. They narrow the texture space while inversely widening the aperture, i.e. smaller values “zoom in.”
If width and height are not specified, the function assumes 1024 for each.
When PRIM_MEDIA_AUTO_SCALE is TRUE, any value for width and height that is not precisely 2ⁿ where 0 ≤ n < 12 will be “rounded up” to the next value, i.e. setting PRIM_MEDIA_WIDTH_PIXELS to 257 has the same effect as setting it to 512. Any value outside the range of [0, 2048] will cause the function to shout a message to DEBUG_CHANNEL and fail. Using 0 (zero) results in the default value being used, which is 1024.
<strike>It might be helpful to think of width and height as setting your “screen size.” If the media is smaller than this “screen,” there will be empty space below and/or to the right of the media. If the media is larger than this “screen,” scroll bars will be made visible. Re-scaling the prim without altering the face’s Horizontal scale, Vertical scale, Horizontal offset, and Vertical offset will only distort (stretch/compress) the media.</strike>_{Pending review. - NM}
width and height scaled larger than 1024 pixels will require the texture backdrop to be resized to fit. (See Useful Snippets)
If resized to fit, the resulting view will cut off scrolled content outside the bounds making it impossible to be viewed.

Helper functions

//-- expand media textures greater than 1024 pixel in a direction to fit the media face
//-- does exactly what the "align" button does in the edit window
//-- original by Edelman Linden (or Kate Linden), tweaked by Void Singer
uExpandMediaTexture( integer vIntWidth, integer vIntHeight, integer vIntFace ){
    integer vIntTemp;
    vector  vSizScale;

    while (vIntWidth >> ++vIntTemp);
    vSizScale.x = vIntWidth / (float)(1 << vIntTemp);
    vIntTemp = 0;
    while (vIntHeight >> ++vIntTemp);
    vSizScale.y = vIntHeight / (float)(1 << vIntTemp);
    llSetLinkPrimitiveParamsFast( LINK_THIS,
                                  [PRIM_TEXTURE, vIntFace] +
                                  llListReplaceList( llGetLinkPrimitiveParams(LINK_THIS, [PRIM_TEXTURE, vIntFace] ),
                                                    [vSizScale, ((vSizScale - <1.0, 1.0, 0.0>) / 2.0)],
                                                    1,
                                                    2 ) );
}

History

Date of Release 10/08/2011

Known issues

From the issue templates included by the wiki article:

SVC-7422 (bug): ll*LinkMedia functions do not work with LINK_* flags