Difference between revisions of "RLVa RFC setsphere"

From Catznip
Jump to navigation Jump to search
(Implied restrictions)
Line 149: Line 149:
  
 
Please note that not all modes may support all 4 options (see their corresponding documentation for more details)
 
Please note that not all modes may support all 4 options (see their corresponding documentation for more details)
 
 
 
 
 
 
 
 
 
 
 
  
 
==Mode: Blend==
 
==Mode: Blend==

Revision as of 18:57, 10 January 2021

Overview

@setsphere is a visual effect that's applied to the final step of world rendering and acts on pixels that fall within its sphere of influence.

For instance, when using the blending mode each pixel on the screen that is contained by the sphere will be blended with the sphere's colour according to a linearly increasing (or decreasing) mix value.

If you're having problems visualing what that looks like: imagine standing in pitch blackness with a lightbulb hat that evenly brightens the area around you. The exact spot where you're standing is at normal brightness, but 5m away everything is only 50% as bright and at 10m away (and beyond) all you can see is total darkness. (Note that @setsphere does not actually emit - or in any way affects - light)

If you're familiar with 'vision spheres' the first screenshot below should look identical to those. However keep in mind that @setsphere only interacts with pixels that intersect an imaginary sphere around your avatar and hence does not actually obsure anything when looking from the outside in.

To illustrate, if you move the camera further back in the previous example you see the second screenshot below. Even though the camera is firmly in the 'all black' zone you can still see the avatar standing in its 'brightened' area and objects outside the visible area (like the tree in the center of the image) can still be made out as a silhouette.

Setsphere overview 1.png
Setsphere overview 2.png

Request for Comments

The current implementation of @setsphere (and hence anything documented or discussed on this page) is by no means final. The first implementation is intented to start a dialog with script creators on what is desired and hopefully spark ideas and thoughts on what's possible beyond the boredom of simply reducing someone's SL experience to the 2m around their avatar.

All comments and suggestions will be taken into consideration. However, keep in mind that once this is merged into Firestorm things will be set in stone.

Things I'd specifically like feedback on:

  • currently there's no limit on the number of sphere effects that can be active at the same time (this will likely be limited to 4 in the future)
  • it's possible that effects don't affect one another in the predicted order (likely the order they're created in will affect the final result) - if you notice any weirdness please let me know
  • even though you can apply an effect to the entire screen by leaving the min/max distance at 0, please let me know if all you want to do is apply a specific effect to the full screen because that can be done more efficiently
  • there's currently no validation of the values for valuemin and valuemax and hence you can set negative alpha values to intensify a colour (or a specific colour component). However this may change in the future. Feel free to experiment, but if you find a use for a value outside of what's listed in the @setsphere modifier table, let me know or you may find it no longer working in the future if no one lets me know
  • similarly there's no rule that says valuemin must be smaller than valuemax (for instance try the following for a 20m sphere to blend from pure black to the normal colour)
    @clear,setsphere=n,setsphere_distmax:20=force,setsphere_valuemax:0=force

Implied restrictions

@setsphere is a visual effect only and as such does not impose any restriction. If you want to limit the camera distance you can use the appropriate @setcam_XXX restriction to accomplish that.

To help you creat your own unique experience some new restrictions will be added and a few existing restrictions will be modified:

  • @viewtransparent=[n|y] - Prevents the user from highlighting transparent textures
  • @viewwireframe=[n|y] - If @setsphere is set as a vision restriction then wireframe could be considered a cheat. This will prevent the user from being able to switch to wireframe rendering
  • @shownametags:<distance> - TODO (Not yet implemented)
  • @edit:<distance> - TODO (Not yet implemented)

If you feel there's another restriction that you need to create the experience you want, please do let me know.

Compatibility

While it was the original intent it's not currently possible to a build a compatibilty layer for @camdraw[min|max]. @camdrawmin and @camdrawmax each take a distance value and are supposed to mix the sphere colour with the actual colour but the drop-off at the inner distance is virtually instantenous.

Below you have a example of a blending sphere starting at 5m (with alpha 0) and ending at 25m (with alpha 1). Full bright white prims were placed every 5m highlighting a point where the brightness should have dropped by 25% (with a linear distrbibution).

With @camdrawmin/camdrawmax only the first prim (which is still within the unaffected radius) is visible and the drop-off past the 5m is so tight that not even the first prim at 10m is visible at all. With @setsphere you can see the inner prim at 5m, as well as the next 3 prims at 10m, 15m and 20m with decreasing brightness and then finally the one at 25m which is completely black and not actually visible.

@camdrawmin:5=n,camdrawmax:25=n,camdrawalphamin:0=n,camdrawalphamax:1=n
@setsphere=n,setsphere_distmin:5=force,setsphere_distmax:25=force,setsphere_valuemin:0=force,setsphere_valuemax:1=force

To simulate what's visible under @setsphere from 5m to 25m the @camdrawmax value had to be increased to 90. If at any point it becomes possible to calculate @camdraw[min|max]'s distance value back to metres I'll add support for them. However, given that script creators will have likely tailored their values to a specific implementation it's better to provide no support in RLVa rathen than support something that looks completelty different from RLV to RLVa and vice versa.

@setsphere

@setsphere is the main (and only) restriction for the sphere effect. Just like @setoverlay (or @setenv) you will need to issue a series of force commands to change the appearance and/or behaviour of the restriction to your liking.

Modifier commands are of the form @setsphere_<modifier>:<param>=force and apply only to the object that issued them. If multiple objects have have their own sphere they can change their own effect but not influence another object's. The end result of multiple spheres will be cumulative (e.g. for blending the colours will mix for an alpha that is lower than 1.0). If you ever want to unset a modifier value you can issue the force command without specificying a vlue (e.g. @setsphere_param=force).

Modifier Input range Default value Description
setsphere_mode 0 - 4 0 (=blend) Type of effect that is applied (see documentation below)
0 - blend
1 - blur
2 - blur (2)
3 - chromatic aberration
4 - pixelate
setsphere_origin 0 - 1 0 (=avatar) Origin of the spere
0 - The sphere is centered around the user's avater
1 - The sphere is centered on the user's camera
setsphere_distmin 0 - ∞ 0 Distance from the sphere's origin. Determines where the effect starts (at valuemin strength)
setsphere_distmax 0 - ∞ 0 Distance from the sphere's origin. Determines where the effect ends (at valuemax strength)
Optional - if not specified (or specified with a value smaller than distmin) this will be set to distmin
setsphere_distextend 0 - 3 1 Distance from the sphere's origin. Determines where the effect ends (at valuemax strength)
setsphere_param A vector of 4 floats 0/0/0/0 Configures the base appearance of the effect (see documentation on the mode you want to use for more information)
setsphere_valuemin 0.0 - 1.0 1.0 Sets the strength of the effect at distmin
setsphere_valuemax 0.0 - 1.0 1.0 Sets the strength of the effect at distmax
setsphere_tween Time (in seconds) 0.0 When set to a non-zero value, modifier changes are no longer instant but will take X seconds to gradually reach their new value. Once set all subsequent modifier changes will be subject to tweening.
Set back to 0 if you want to make changes instant again.
'distmax', 'distmin', 'param', 'valuemax' and 'valuemin' are affected by this.

@setsphere_distextend

The 'distextend' modifier specifies how the areas on both sides of the sphere should act.

Value Description
0 The effect is only applied to pixels that lay within min and max distance. Pixels outside this range render as normal.
1 The effect extends outward so that pixels that are farther than max distance will have effect strength 'valuemax' (Default)
2 The effect extends inward so that pixels that are closer than min distance will have effect strength 'valuemin'
3 The effect extends both in- and outward

If the above wasn't clear hopefully the following 4 pictures will make it clearer. Pure black pixels signify areas that are unaffected by the effect; any shade of gray signifies an area where the effect strength is between 0 (=black / not at all) and 1 (=white / full). (If you have any Photoshop experience think of the images as a blending mask)

0 - The effect only applies for distmin < distance > distmax
1 - The effect extends outward past distmax
2 - The effect extends inward before distmin
3 - The effect extends both inward and outward


Please note that not all modes may support all 4 options (see their corresponding documentation for more details)

Mode: Blend

Command Value(s) Description
setsphere_mode 0 Switches @setsphere to 'blend' mode
setsphere_param <red>/<green>/<blue>/0 The first three numbers specify the red, green and blue value of sphere colour respectively (between 0 and 1). The 4th parameter is unused (set to 0)
setsphere_distmin <distance> Sets the distance (in m) at which the effect should start
setsphere_distmax <distance> Sets the distance (in m) at which the effect should end
setsphere_distextend 0, 1, 2 or 3 See documentation above
setsphere_valuemin <float> Sets the strength of the effect at distmin (useful range values depend on kernel size param)
setsphere_valuemax <float> Sets the strength of the effect at distmax (useful range values depend on kernel size param)

Example

  1. Clear all modifiers and switch @setsphere to 'blend' mode with a 2.5m exclusion sphere zone beyond which everything is pure black (=default sphere colour)
    @clear,setsphere=n,setsphere_distmin:2.5=force
  2. Set the outer radius of the sphere to 20m and start with an 0.0 alpha value at 0m (and end with a 1.0 alpha value at maximum which is the default)
    @setsphere_distmax:20=force,setsphere_valuemin:0=force
  3. Switch the effect's alpha at the far edge to 95% allowing you to still see things in the distance and switch the colour to a dark gray
    @setsphere_valuemax:0.95=force,setsphere_param:0.35/0.35/0.35/0=force
  4. Set the outer radius of the sphere to 50m for a more pleasing visual end-result
    @setsphere_distmax:50=force
(Step 2) Block size set to 10x10
(Step 3) Inner sphere radius set to 10m
(Step 2) Block size set to 10x10
(Step 3) Inner sphere radius set to 10m

Mode: Blur (2)

Command Value(s) Description
setsphere_mode 2 Switches @setsphere to 'variable kernel blur' mode
setsphere_param <kernel size>/0/0/0 The first number specifies the kernel size for the Gaussian blur (needs to be set in combination with valuemin/valuemax)
setsphere_distmin <distance> Sets the distance (in m) at which the effect should start
setsphere_distmax <distance> Sets the distance (in m) at which the effect should end
setsphere_distextend 0, 1, 2 or 3 See documentation above
setsphere_valuemin <float> Sets the strength of the effect at distmin (useful range values depend on kernel size param)
setsphere_valuemax <float> Sets the strength of the effect at distmax (useful range values depend on kernel size param)

Notes

  • The kernel size determines how many neighbouring pixels are sampled. A higher kernel size will result in a more blurred out end result (dependent on the sigma value in min/max value)
  • Avoid using large value for kernel since this will likely be clamped in the future once the impact on FPS can be determined

Example

  1. Clear all modifiers and switch @setsphere to 'variable blur' mode
    @clear,setsphere=n,setsphere_mode:2=force
  2. Set the kernel size to 15 and sigma value to 5
    @setsphere_param:15/0/0/0=force,setsphere_valuemax:5=force
  3. Enforce the effect only when >=2m away (only objects >2m will look blurry)
    @setsphere_distmin:2=force
(Step 2) Red shifted by 8 left and 0 down. Blue shifted by 8 right and 0 down.
(Step 3) Using valuemin/valuemax blends the original colour with the effect making it appear more like a ghost artifact

Mode: Chromatic Aberration

Command Value(s) Description
setsphere_mode 3 Switches @setsphere to 'chromatic aberration' mode
setsphere_param <horiz red shift>/<vert red shift>/<horiz blue shift>/<vert blue shift> The first 2 numbers specify the offset of the red component; the last 2 the offset of the green component
setsphere_distmin <distance> Sets the distance (in m) at which the effect should start
setsphere_distmax <distance> Sets the distance (in m) at which the effect should end
setsphere_distextend 0, 1, 2 or 3 See documentation above
setsphere_valuemin 0.0-1.0 Sets the strength of the effect at distmin
setsphere_valuemax 0.0-1.0 Sets the strength of the effect at distmax

Notes

  • If both values (valuemin and valuemax) and both distances (distmin and distmax) are different then - much like the blending mode - the offsets for the colour components of each pixel will gradually increase (or decrease) depending on the distance

Example

  1. Clear all modifiers and switch @setsphere to 'ca' mode
    @clear,setsphere=n,setsphere_mode:3=force
  2. Shift the red channel to the left by 8 pixels and blue to the right by 8 pixels
    @setsphere_param:8/0/-8/0=force
  3. Increase the color shifts but blend back with the original colour at 50% (animate the change across 5 seconds)
    @setsphere_tween:5=force,setsphere_param:0/-25/0/25=force,setsphere_valuemax:0.5=force,setsphere_tween=force
  4. Enforce the effect only when >=10m away (only objects >10m away appear affected)
    @setsphere_distmin:10=force
(Step 2) Red shifted by 8 left and 0 down. Blue shifted by 8 right and 0 down.
(Step 3) Using valuemin/valuemax blends the original colour with the effect making it appear more like a ghost artifact
(Step 4) Inner sphere radius set to 10m

Mode: Pixelate

Command Value(s) Description
setsphere_mode 4 Switches @setsphere to pixelate mode
setsphere_param <width>/<height>/0/0 Specifies the pixelate block size (in pixels) - last 2 params are unused by this mode
setsphere_distmin <distance> Sets the distance (in m) at which the effect should start
setsphere_distmax <distance> Sets the distance (in m) at which the effect should end
setsphere_distextend 1 or 0 Specify 1 (default) to extend the effect past the maximum distance or 0 to end it
setsphere_valuemin - Unused
setsphere_valuemax - Unused

Notes

  • don't use @setsphere_distextend:1=force with a min/max distance value in this mode; just setting distmin will suffice (see examples)

Example

  1. Clear all modifiers and switch @setsphere to 'pixelate' mode
    @clear,setsphere=n,setsphere_mode:4=force
  2. Set the block size to 10x10 (everything is pixelated)
    @setsphere_param:10/10/0/0=force
  3. Enforce the effect only when >=10m away (only objects >10m away appear pixelated)
    @setsphere_distmin:10=force
  4. Tween to a block size of 25x25 in 15 seconds (and then reset the tween duration for following commands)
    @setsphere_tween:15=force,setsphere_param:25/25/0/0=force,setsphere_tween=force
(Step 2) Block size set to 10x10
(Step 3) Inner sphere radius set to 10m
(Step 4) Block size set to 25x25