Difference between revisions of "LlSetLinkMedia"

From Second Life Wiki
Jump to navigation Jump to search
m (Clarified a point regarding width/height in relation to auto scaling. Marked a section as "pending review.")
(Pending text sounds reasonable and doesn't conflict with other text on the page.)
 
Line 1: Line 1:
{{LSL_Function
{{LSL_Function
|inject-2={{LSL_Function/face|face|notall=*}}{{LSL_Function/link|link|nogroup=*}}{{Issues/SVC-7422}}
|inject-2={{LSL_Function/face|face|notall=*}}{{LSL_Function/link|link|nogroup=*|noavatar=*}}{{Issues/SVC-7422}}
|func_id=?|func_sleep=0.0|func_energy=0.0|mode
|func_id=?|func_sleep=0.0|func_energy=0.0|mode
|func=llSetLinkMedia|return_type=integer|return_subtype=status
|func=llSetLinkMedia|return_type=integer|return_subtype=status
Line 13: Line 13:
*If prim media is newly added to this object, params not specified take their default value.
*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.
*If prim media is already on this object, params not specified are unchanged.
* About <code>PRIM_MEDIA_WIDTH_PIXELS</code> (''width'') and <code>PRIM_MEDIA_HEIGHT_PIXELS</code> (''height'') ...
* About <code>[[PRIM_MEDIA_WIDTH_PIXELS]]</code> ({{LSLPT|width}}) and <code>[[PRIM_MEDIA_HEIGHT_PIXELS]]</code> ({{LSLPT|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."
** Both {{LSLPT|width}} and {{LSLPT|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.
*** If {{LSLPT|width}} and {{LSLPT|height}} are not specified, the function assumes 1024 for each.
** When <code>PRIM_MEDIA_AUTO_SCALE</code> is <code>TRUE</code>, any value for ''width'' and ''height'' that is not precisely 2<sup>''n''</sup> where 0 &le; ''n'' &lt; 12 will be "rounded up" to the next value, i.e. setting <code>PRIM_MEDIA_WIDTH_PIXELS</code> 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 <code>DEBUG_CHANNEL</code> and fail. Using 0 (zero) is equivalent to using 1024.
** When <code>[[PRIM_MEDIA_AUTO_SCALE]]</code> is <code>[[TRUE]]</code>, any value for {{LSLPT|width}} and {{LSLPT|height}} that is not precisely 2<sup>''n''</sup> where 0 &le; ''n'' &lt; 12 will be "rounded up" to the next value, i.e. setting <code>[[PRIM_MEDIA_WIDTH_PIXELS]]</code> to 257 has the same effect as setting it to 512. Any value outside the range of {{Interval|gte=0|lte=2048}} will cause the function to shout a message to <code>[[DEBUG_CHANNEL]]</code> 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><sub>''Pending review. - NM''</sub>
** <strike>It might be helpful to think of {{LSLPT|width}} and {{LSLPT|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><sub>''Pending review. - NM''</sub>
* Width and height scaled larger than 1024 pixels will require the texture backdrop to be resized to fit. (See [[#Useful_Snippets|Useful Snippets]])
* {{LSLPT|width}} and {{LSLPT|height}} scaled larger than 1024 pixels will require the texture backdrop to be resized to fit. (See [[#Useful_Snippets|Useful Snippets]])
** If resized to fit, the resulting view will cut off scrolled content outside the bounds making it impossible to be viewed.
** If resized to fit, the resulting view will cut off scrolled content outside the bounds making it impossible to be viewed.
|constants={{LSL Constants/ReturnStatus|table=*|sortable=*}}{{LSL Constants/PrimMedia|set}}
|constants={{LSL Constants/ReturnStatus|table=*|sortable=*}}{{LSL Constants/PrimMedia|set}}

Latest revision as of 10:37, 18 December 2015

Summary

Function: integer llSetLinkMedia( integer link, integer face, list params );

Set the media params for a particular face on the linked prim(s) without a delay.
Returns a status (an integer) that is a STATUS_* flag which details the success/failure of the operation(s).

• integer link – Link number (0: unlinked, 1: root prim, >1: child prims) or a LINK_* flag
• integer face – face number
• list params – a set of name/value pairs (in no particular order)

Flag Description
LINK_ROOT 1 refers to the root prim in a multi-prim linked set[1]
Flag Description
LINK_THIS -4 refers to the prim the script is in

Success/Failure Flags Description
STATUS_OK 0 Result of function call was success
STATUS_MALFORMED_PARAMS 1000 Function was called with malformed parameters
STATUS_TYPE_MISMATCH 1001 Argument(s) passed to function had a type mismatch
STATUS_BOUNDS_ERROR 1002 Argument(s) passed to function had a bounds error
STATUS_NOT_FOUND 1003 Object or other item was not found
STATUS_NOT_SUPPORTED 1004 Feature not supported
STATUS_INTERNAL_ERROR 1999 An internal error occurred
STATUS_WHITELIST_FAILED 2001 Whitelist Failed
Parameter Additional Parameters Description
[ PRIM_MEDIA_ALT_IMAGE_ENABLE ] 0 [ 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.

[ PRIM_MEDIA_CONTROLS ] 1 [ integer control ] Sets the style of controls. Can be either PRIM_MEDIA_CONTROLS_STANDARD or PRIM_MEDIA_CONTROLS_MINI.
controls Flags Description
PRIM_MEDIA_CONTROLS_STANDARD 0 Standard web navigation controls.
PRIM_MEDIA_CONTROLS_MINI 1 Mini web navigation controls; does not include an address bar.
[ PRIM_MEDIA_CURRENT_URL ] 2 [ string current_url ] Sets the current url displayed on the chosen face. Changing this URL causes navigation. 1024 characters Max
[ PRIM_MEDIA_HOME_URL ] 3 [ string home_url ] Sets the home url for the chosen face. 1024 characters max
[ PRIM_MEDIA_AUTO_LOOP ] 4 [ integer boolean ] Sets whether auto-looping is enabled.
[ PRIM_MEDIA_AUTO_PLAY ] 5 [ integer boolean ] Sets whether the media auto-plays when a Resident can view it.
[ PRIM_MEDIA_AUTO_SCALE ] 6 [ integer boolean ] Sets whether auto-scaling is enabled. Auto-scaling forces the media to the full size of the texture.
[ PRIM_MEDIA_AUTO_ZOOM ] 7 [ integer boolean ] Sets whether clicking the media triggers auto-zoom and auto-focus on the media.
[ PRIM_MEDIA_FIRST_CLICK_INTERACT ] 8 [ integer boolean ] Sets whether the first click interaction is enabled.

Note: This flag appears not to work.

[ PRIM_MEDIA_WIDTH_PIXELS ] 9 [ integer width ] Sets the width of the media in pixels.
[ PRIM_MEDIA_HEIGHT_PIXELS ] 10 [ integer height ] Sets the height of the media in pixels.
[ PRIM_MEDIA_WHITELIST_ENABLE ] 11 [ integer boolean ] Sets whether navigation is restricted to URLs in PRIM_MEDIA_WHITELIST.
[ PRIM_MEDIA_WHITELIST ] 12 [ 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.
[ PRIM_MEDIA_PERMS_INTERACT ] 13 [ integer perms ] Sets the permissions mask that control who can interact with the object:
[ PRIM_MEDIA_PERMS_CONTROL ] 14 [ integer perms ] Sets the permissions mask that control who can see the media control bar above the object:

Caveats

  • link needs to be either an actual link number or a link constants that equate to a single prim, such as LINK_ROOT and LINK_THIS.
  • link cannot be a seated avatar.
  • The function silently fails if its face value indicates a face that does not exist.
  • 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 2n 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.
    • 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.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.

Examples

Useful Snippets

//-- 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 ) );
}

Notes

Link Numbers

Each prim that makes up an object has an address, a link number. To access a specific prim in the object, the prim's link number must be known. In addition to prims having link numbers, avatars seated upon the object do as well.

  • If an object consists of only one prim, and there are no avatars seated upon it, the (root) prim's link number is zero.
  • However, if the object is made up of multiple prims or there is an avatar seated upon the object, the root prim's link number is one.

When an avatar sits on an object, it is added to the end of the link set and will have the largest link number. In addition to this, while an avatar is seated upon an object, the object is unable to link or unlink prims without unseating all avatars first.

Counting Prims & Avatars

There are two functions of interest when trying to find the number of prims and avatars on an object. 

integer GetPrimCount() { //always returns only the number of prims
    if(llGetAttached())//Is it attached?
        return llGetNumberOfPrims();//returns avatars and prims but attachments can't be sat on.
    return llGetObjectPrimCount(llGetKey());//returns only prims but won't work on attachments.
}
See llGetNumberOfPrims for more about counting prims and avatars.

Errata

If a script located in a child prim erroneously attempts to access link 0, it will get or set the property of the linkset's root prim. This bug (BUG-5049) is preserved for broken legacy scripts.

See Also

Functions

•  llGetLinkNumber – Returns the link number of the prim the script is in.
•  llSetPrimMediaParams
•  llGetLinkMedia
•  llClearLinkMedia

Articles

Deep Notes

History

Date of Release 10/08/2011

Footnotes

  1. ^ LINK_ROOT does not work on single prim objects. Unless there is an avatar sitting on the object.
  2. ^ The ranges in this article are written in Interval Notation.

Signature

function integer llSetLinkMedia( integer link, integer face, list params );
integer PRIM_MEDIA_ALT_IMAGE_ENABLE = 0;
integer PRIM_MEDIA_CONTROLS = 1;
integer PRIM_MEDIA_CURRENT_URL = 2;
integer PRIM_MEDIA_HOME_URL = 3;
integer PRIM_MEDIA_AUTO_LOOP = 4;
integer PRIM_MEDIA_AUTO_PLAY = 5;
integer PRIM_MEDIA_AUTO_SCALE = 6;
integer PRIM_MEDIA_AUTO_ZOOM = 7;
integer PRIM_MEDIA_FIRST_CLICK_INTERACT = 8;
integer PRIM_MEDIA_WIDTH_PIXELS = 9;
integer PRIM_MEDIA_HEIGHT_PIXELS = 10;
integer PRIM_MEDIA_WHITELIST_ENABLE = 11;
integer PRIM_MEDIA_WHITELIST = 12;
integer PRIM_MEDIA_PERMS_INTERACT = 13;
integer PRIM_MEDIA_PERM_OWNER;
integer PRIM_MEDIA_PERM_GROUP;
integer PRIM_MEDIA_PERM_ANYONE;
integer PRIM_MEDIA_PERMS_CONTROL = 14;

integer PRIM_MEDIA_CONTROLS_STANDARD = 0;//Standard web navigation controls.
integer PRIM_MEDIA_CONTROLS_MINI = 1;//Mini web navigation controls; does not include an address bar.
Retrieved from "https://wiki.secondlife.com/w/index.php?title=LlSetLinkMedia&oldid=1198402"