overlay

Module(s): vncanvas-base, vncanvas-bgnd
Description: Display an overlay image on top of foreground.

Syntax

overlay, {param}

This displays an overlay image which can be used to:
- display non-actor graphic (e.g. map, CG, character closeup, etc)
- act as a curtain while background and foreground are being placed on stage
- serve as backdrops or transition and title screens (possibly with text and effects)
- add simple atmospheric effects (like a fog overlay, dim/night effects)
Parameters are given as {param:value, param:value, ...}

Parameter Summary

Parameter	Attributes and Description
src:"path_to_overlay_file" src:"valid_HTML_color" src:["path_to_overlay_filmstrip", frames, fps]	Image or color to serve as overlay. Valid HTML colors may be specified as "string" (e.g. "red"), "#RRGGBB", "rgb(rr,gg,bb)" or "rgba(rr,gg,bb,aa)". Also accepts a user variable as path to overlay file. Support for animated overlay. Src should be given as: ["image", frame, fps] where frames is the number of frames in a horizontal filmstrip defined by image and fps is the animation frames per second. See also Sprites demo.
offset:[x, y] or "scroll"	Optional The overlay images are center aligned. If offset is given as [x, y], this sets the offset from viewport center. If given as "scroll", this automatically sets scrolling for the overlay (especially for large images). Default is [0, 0].
effect:"effect_name [args]"	Optional Effect when showing or hiding overlays. Note, unlike actors, "effect" is not persistent, meaning if effect is not specified, the default or "none" is used. Supported effects: - "none" (default) - "dissolve" - "fade" - "ghost" (a semi-transparent graphic) - "left" \| "right" \| "top" \| "bottom" (slides the overlay graphic to and from the specified direction) - "scale scale_value" (scales the overlay graphic relative to base size) - "rotate rotate_value" (rotates the overlay graphic in degrees clockwise relative to previous orientation) - "translate x_value y_value" (translates the overlay graphic according to the given values relative to current position; applies only if overlay is not "scroll"-ed) The 'scale', 'rotate' and 'translate' arguments accept a user variable id. A 'nowait' argument, e.g. "fade nowait", may be added to continue without waiting for effects to complete.
filter:"filter_name [args]"	Optional NEW! Filter overlay images using image manipilation. Supported filters: - "luminance" - "grayscale" - "sepia" - "brightness" - "threshold" - "invert" - "saturate" - "horizontalFlip" - "verticalFlip" - "sharpen" - "blur" - "laplace" - "gaussianBlur" Note: Image manipulation is dependent on browser. Some browsers like Firefox allows local image manipulation. Some browsers like Chrome requires the image be hosted on a webserver, though a local webserver will do. For large images, filtering may be CPU intensive. So expect lags or delays when using filters.
time:number	Optional Same as "scene". The default transition duration is set in configuration file.
show:boolean (true/false)	Optional Displays or hides the overlay. When hiding the overlay, there is no need to provide the "src" tag.

Example

The first overlay call displays an overlay. The second one hides it.

  
chapter = [

	...
	overlay, {src:"images/overlay0.png", effect:"fade", offset:"scroll"},
	...
	overlay, {effect:"fade", show:false},
	...
];