Difference between revisions of "Cabal Common Library Doc Overlay"

From Elite Wiki
(started doc for overlay script)
 
m (Retagged!)
 
(4 intermediate revisions by one other user not shown)
Line 4: Line 4:
 
It handles 19 slots for inflight overlays (10x characters, 9x notifications) and uses shaders to place them on screen
 
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_OXP|Vector]] (this OXP will be changed to use this mechanism).
 
and works in a similiar way to the overlays in [[Vector_OXP|Vector]] (this OXP will be changed to use this mechanism).
 +
 +
The underlaying shader uses <code>shaderInt1</code> and <code>shaderInt2</code> for moving the overlay, <code>shaderFloat1</code> for brightness, <code>shaderFloat2</code> for highlighting (see [[#ovSpeak()|ovSpeak()]]), <code>shaderVector1</code> for positioning (x/y) and size (z) and <code>shaderVector2</code> 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.
  
  
Line 10: Line 14:
 
{{CodeEx|codeex=worldScripts.Cabal_Common_Overlay.ovAdd( obj, off )}}
 
{{CodeEx|codeex=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.
 
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:'''
 
'''Parameters:'''
Line 16: Line 22:
  
 
'''Returns:'''
 
'''Returns:'''
−
:;result:VisualEffect or false.
+
:;result:Visual Effect (or when docked true) or false.
  
 
'''Properties:'''
 
'''Properties:'''
 
:;cclov_id:String. Unique Identifier.
 
:;cclov_id:String. Unique Identifier.
 +
::Required.
 
:;cclov_type:Number. 0=Notification, 1=Character.
 
:;cclov_type:Number. 0=Notification, 1=Character.
 +
::Required.
 
:;cclov_blend:Number. Duration for effect in seconds. Set to -1 for permanent.
 
:;cclov_blend:Number. Duration for effect in seconds. Set to -1 for permanent.
 +
::Required.
 
:;cclov_autoremove:Boolean. Removes effect after cclov_blend seconds.
 
:;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. {{AV|1.7.1}}.
 
:;cclov_fx:String. VisualEffect to be used instead.
 
:;cclov_fx:String. VisualEffect to be used instead.
 +
::Optional.
 
:;cclov_png:String/Texture. Must be specified if cclov_fx is not used.
 
:;cclov_png:String/Texture. Must be specified if cclov_fx is not used.
−
:;cclov_color:Array. Color in rgb. Values should be in range 0...3.
+
::Required/Optional.
  
  
 
=== ovSpeak() ===
 
=== ovSpeak() ===
 
{{CodeEx|codeex=worldScripts.Cabal_Common_Overlay.ovSpeak( who, cclov_blend, message, whom, autoremove )}}
 
{{CodeEx|codeex=worldScripts.Cabal_Common_Overlay.ovSpeak( who, cclov_blend, message, whom, autoremove )}}
−
Lights up the overlay.
+
[[Image:Ccl_overlays_highlighting.png‎|right|128px|thumb|Highlighting]]
 +
Lights up the overlay and displays a commsMessage for character overlays or consoleMessage for notifications. If <tt>whom</tt> 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:'''
 
'''Parameters:'''
 
:;who:String. Identifier (see [[#ovAdd()|ovAdd() - cclov_id]]).
 
:;who:String. Identifier (see [[#ovAdd()|ovAdd() - cclov_id]]).
 +
::Required.
 
:;cclov_blend:Number. Duration for effect in seconds.
 
:;cclov_blend:Number. Duration for effect in seconds.
 +
::Required.
 
:;message:String.
 
:;message:String.
 +
::Required.
 +
:;autoremove:Boolean. Removes effect after cclov_blend seconds.
 +
::Optional.
 
:;whom:Entity.
 
:;whom:Entity.
−
:;autoremove:Boolean. Removes effect after cclov_blend seconds.
+
::Optional.
  
 
'''Returns:'''
 
'''Returns:'''
Line 49: Line 70:
 
'''Parameters:'''
 
'''Parameters:'''
 
:;who:String. Identifier (see [[#ovAdd()|ovAdd() - cclov_id]]).
 
:;who:String. Identifier (see [[#ovAdd()|ovAdd() - cclov_id]]).
 +
::Required.
  
 
'''Returns:'''
 
'''Returns:'''
 
:;result:Boolean. True on success. Otherwise false.
 
:;result:Boolean. True on success. Otherwise false.
 +
 +
 +
== Coloring and Decals ==
 +
[[Image:Ccl_overlays_character.png|right|128px|thumb|Standard]]
 +
[[Image:Ccl_overlays_decals.png‎|right|128px|thumb|Decals]]
 +
[[Image:Ccl_overlays_decals_result.png‎|right|128px|thumb|Result of coloring + decals]]
 +
For character overlays (<tt>cclov_type=1</tt>) three different shaders can be used. The script chooses them automatically based on the specified parameters, except if <tt>cclov_fx</tt> 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|Result]]).
 +
 +
 +
=== Coloring ===
 +
Additionally character overlays can be colored by specifying <tt>cclov_color</tt>. The shader applies the new color to areas where the blue channel is higher than red + green channel (<tt>blue-(0.75*(red+green))</tt>). 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|Decals]] option.
 +
 +
 +
=== Decals ===
 +
A third option is using decals. The shader splits the texture coordinates of the input image in 4 areas. <tt>cclov_decal</tt> 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|Coloring]] option. {{AV|1.7.1}}.
 +
 +
 +
=== Result ===
 +
The final output for a overlay using coloring and decals.
  
  
 
----
 
----
−
[[Category:OXPDoc]]
+
[[Category:OXP API's]]

Latest revision as of 14:10, 20 September 2023

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 )
Highlighting

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

Standard
Decals
Result of coloring + 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.


Retrieved from "https://wiki.alioth.net/index.php?title=Cabal_Common_Library_Doc_Overlay&oldid=79866"