Cabal Common Library Doc Overlay
Contents
Overview
This is the main class for the overlay helpers with its members and part of the Cabal_Common_Library.
It handles 19 slots for inflight overlays (10x characters, 9x notifications) and uses shaders to place them on screen and works in a similiar way to the overlays in Vector (this OXP will be changed to use this mechanism).
The underlaying shader uses shaderInt1 and shaderInt2 for moving the overlay, shaderFloat1 for brightness, shaderFloat2 for highlighting (see ovSpeak()), shaderVector1 for positioning (x/y) and size (z) and shaderVector2 for coloring (only if cclov_color is used for character overlays).
As all overlays are done as screen aligned quads their appearance is based on the used screen resolution.
Methods
ovAdd()
| worldScripts.Cabal_Common_Overlay.ovAdd( obj, off ) |
Adds overlay to one of the available slots. Added overlays will stay inflight until the calling script explicitely removes them, the VisualEffect becomes invalid or the autoremove option is used. All overlays will be removed when the player docks or leaves the system, but are respawned (offscreen) when the player launches or enters a new system. The script does not store anything to the savedgame though, so scripts are responsible to add them if necessary.
If used when docked the overlay will be stored and spawned offscreen when the player launches.
Parameters:
- obj
- Object. Properties see below.
- off
- Boolean. If true overlay is added, but offscreen.
Returns:
- result
- Visual Effect (or when docked true) or false.
Properties:
- cclov_id
- String. Unique Identifier.
- Required.
- cclov_type
- Number. 0=Notification, 1=Character.
- Required.
- cclov_blend
- Number. Duration for effect in seconds. Set to -1 for permanent.
- Required.
- cclov_autoremove
- Boolean. Removes effect after cclov_blend seconds.
- Optional.
- cclov_color
- Array. RGB values in range 0...3 for character overlays.
- Optional.
- cclov_decal
- Number. Bitmask for used decals for character overlays.
- Optional. Added in v1.7.1.
- cclov_fx
- String. VisualEffect to be used instead.
- Optional.
- cclov_png
- String/Texture. Must be specified if cclov_fx is not used.
- Required/Optional.
ovSpeak()
| worldScripts.Cabal_Common_Overlay.ovSpeak( who, cclov_blend, message, whom, autoremove ) |
Lights up the overlay and displays a commsMessage for character overlays or consoleMessage for notifications. If whom is specified the script will use a commsMessage for this entity. Areas with a alpha setting <0.9 will be filled with a rgb color.
Parameters:
- who
- String. Identifier (see ovAdd() - cclov_id).
- Required.
- cclov_blend
- Number. Duration for effect in seconds.
- Required.
- message
- String.
- Required.
- autoremove
- Boolean. Removes effect after cclov_blend seconds.
- Optional.
- whom
- Entity.
- Optional.
Returns:
- result
- Boolean. True on success. Otherwise false.
ovRemove()
| worldScripts.Cabal_Common_Overlay.ovRemove( who ) |
Remove specified overlay.
Parameters:
- who
- String. Identifier (see ovAdd() - cclov_id).
- Required.
Returns:
- result
- Boolean. True on success. Otherwise false.
Coloring and Decals
For character overlays (cclov_type=1) three different shaders can be used. The script chooses them automatically based on the specified parameters, except if cclov_fx is used.
Standard
The easiest way is to use the standard output which does not apply any coloring or decals. The texture is taken 1:1 and only a fadeIn and the highlighting is processed. Areas with a alpha setting below 0.9 are discarded. The pic shows the input of a 128px x 128px texture.
As all overlays are done as screen aligned quads their appearance is based on the used screen resolution (see Result).
Coloring
Additionally character overlays can be colored by specifying cclov_color. The shader applies the new color to areas where the blue channel is higher than red + green channel (blue-(0.75*(red+green))). This is done explicitely to allow grey areas staying untouched without the need of a additional masking texture. It can be combined with the Decals option.
Decals
A third option is using decals. The shader splits the texture coordinates of the input image in 4 areas. cclov_decal specifies which of the areas gets mixed with the main area. It is a bitmask value (1, 2 and 4) and processing is done in descending order to allow elements hiding each other. A value of 7 applies all decals. It can be combined with the Coloring option. Added in v1.7.1.
Result
The final output for a overlay using coloring and decals.
