llSetPrimMediaParams

function

Replaces deprecated llRefreshPrimURL, llSetPrimURL.

Function syntax

integer llSetPrimMediaParams(

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.

);

Returns: integer
Delay: 1 s
Energy: 10

Sets the media parameters specified by params on the designated face of the prim. Returns an integer STATUS_* flag detailing success or failure.

Set the media params for a particular face.

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

integer result = llSetPrimMediaParams(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, add it.
Params not specified are unchanged, or if new media is added set to the default specified.
Both width and height must be specified together to work, and they narrow the texture space while inversely widening the aperture.
width and height scaled larger than 1024pixels 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
Face needs to be a single face. If you want the media on multiple faces (e. g. opposing sides of an object), you have to call the function multiple times with different face numbers. Bitwise AND for face numbers does not work.
PRIM_MEDIA_FIRST_CLICK_INTERACT can be overridden by the viewer setting Me > Preferences > Sound & Media > Media first-interact. By default, it works on Worn HUDs, Owned Objects, Friend Objects, Group Objects, and Landowner Objects

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 (width/height are in pixels)
//-- 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);
    llSetPrimitiveParams( [PRIM_TEXTURE, vIntFace] +
                          llListReplaceList( llGetPrimitiveParams( [PRIM_TEXTURE, vIntFace] ),
                                             [vSizScale, ((vSizScale - <1.0, 1.0, 0.0>) / 2.0)],
                                             1,
                                             2 ) );
}

ref: original source

History

SVN:2816 r134947 Trunk
SVC-4939
Functionality available in Client 2.0

Known issues

From the issue templates included by the wiki article:

SVC-4939 (bug): [http://svn.secondlife.com/trac/linden/changeset/2816 SVN Changeset 2816 in Trunk] is immature
VWR-17719 (bug): llSetPrimMediaParams PRIM_MEDIA_FIRST_CLICK_INTERACT doesn’t work