Description

A story is the entry point of ABeamer web browser library.
It has the following functions:

  • Manage multiple scenes, including insert and remove.
  • Manage scene transitions.
  • Manage flyovers.
  • Start the rendering process.
  • Communicate with the render server agent.
  • Load the complete story from a configuration file.

The workflow summary is:

  • A story automatically creates DOM scenes.
  • In each scene, the user adds its animations.
  • The user executes story.render which will process the animation pipeline frame by frame and sends it to the render server agent.
  • The render server agent will communicate with a headless server such as puppeteer to store each frame on the disk.

see: workflow.

 

API

 

WaitMan

public export interface

export interface WaitMan{ }

WaitMan.funcs

public property [WaitMan]

funcs: _WaitFunc[];

WaitMan.pos

public property [WaitMan]

pos: uint;

WaitMan.addWaitFunc()

public method [WaitMan]

addWaitFunc(func: WaitFunc, params: AnyParams): void;
 

Story

public export interface

export interface Story{ }

Implementation of _Story class.

Story.fps

readonly public property [Story]

readonly fps: uint;

Frames per second.
All the time values is converted into frames using this value.
Defined during the call to createStory.

Story.defaultUnit

public property [Story]

defaultUnit: TimeUnit;

Default unit used when input time values are used in numeric forms.
Supports minutes, seconds, milliseconds and frames.
TimeUnit.f = 0;
TimeUnit.ms = 1;
TimeUnit.s = 2;
TimeUnit.m = 3;

Story.hasServer

readonly public property [Story]

readonly hasServer: boolean;

True if it's running a supporting server program for frame storage.

Story.serverName

readonly public property [Story]

readonly serverName: string;

The name of the server.
The server will assign this property value.

Story.serverFeatures

public property [Story]

serverFeatures: ServerFeatures;

Provides information about the running server.

Story.metadata

readonly public property [Story]

readonly metadata: StoryMetadata;

Numerical value of the frame width in pixels.

Story.width

readonly public property [Story]

readonly width: uint;

Numerical value of the frame width in pixels.

Story.height

readonly public property [Story]

readonly height: uint;

Numerical value of the frame height in pixels.

Story.frameCount

readonly public property [Story]

readonly frameCount: uint;

Total number of frames from all the scenes.

Story.renderDir

readonly public property [Story]

readonly renderDir: DirectionInt;

Render direction. 1 for forward, -1 for backwards.
Defined during the call to story.render.

Story.renderFrameEnd

readonly public property [Story]

readonly renderFrameEnd: uint;

The number of the last frame to be rendered within the story.
Defined during the call to story.render.
This value doesn't changes during the rendering process.

Story.renderFramePos

readonly public property [Story]

readonly renderFramePos: uint;

The number of the current frame being rendered.
Defined during the call to story.render.
This value changes during the rendering process.

Story.renderFrameCount

readonly public property [Story]

readonly renderFrameCount: uint;

The number of the current frame being rendered.
Defined during the call to story.render.
This value doesn't changes during the rendering process.

Story.isRendering

readonly public property [Story]

readonly isRendering: boolean;

True if the rendering has started.
Use finishRender to abort the rendering process.

Story.isTeleporting

readonly public property [Story]

readonly isTeleporting: boolean;

True if it's teleporting.

Story.args

readonly public property [Story]

readonly args: ABeamerArgs;

Returns ABeamerArgs.
This should be used only in specific cases such the access to --var.
In most cases, this property is passed as an argument to plugins and callbacks.

Story.strictMode

public property [Story]

strictMode: boolean;

Story.logLevel

public property [Story]

logLevel: uint;

Story.isVerbose

public property [Story]

isVerbose: boolean;

Story.scenes

readonly public property [Story]

readonly scenes: Scene[];

List of the scenes.

Story.curScene

readonly public property [Story]

readonly curScene: Scene | undefined;

Current active and visible scene.
Valid both for adding animations and rendering.
Use gotoScene to change this value.

Story.storyAdapter

public property [Story]

storyAdapter: SceneAdapter;

Allows flyovers to find elements on the document body or in the virtual world.

Story.toExitOnRenderFinished

public property [Story]

toExitOnRenderFinished: boolean;

If true, it terminates the server when the render call finishes or if it's aborted.
For a serverless execution, it has no effect.
default: true

Story.onRenderFinished

public property [Story]

onRenderFinished?: (args?: ABeamerArgs) => void;

Event triggered when render finished the rendering process.
EXPERIMENTAL The behavior can changed or be deprecated.

Story.onServerReady

public property [Story]

onServerReady?: (args?: ABeamerArgs) => void;

Event triggered by server, stating that it's ready to receive frames.
A server is usually a headless capture program such as puppeteer.
If the animation is running without server, this event is never fired.

Story.onBeforeRenderFrame

public property [Story]

onBeforeRenderFrame?: (args?: ABeamerArgs) => void;

Event triggered before a frame is rendered.

Story.onAfterRenderFrame

public property [Story]

onAfterRenderFrame?: (args?: ABeamerArgs) => void;

Event triggered after a frame is rendered.

Story.onNextFrame

public property [Story]

onNextFrame?: (args?: ABeamerArgs) => void;

Event triggered during the rendering process after a frame is rendered and is ready to move to following frame.

Story.onGetVirtualElement

public property [Story]

onGetVirtualElement?: (id: string, args?: ABeamerArgs) => VirtualElement;

Maps Ids into Virtual Elements Used only in non-DOM elements such as WebGL elements.
param: id virtual element Id without '%'

Story.virtualAnimators

public property [Story]

virtualAnimators: VirtualAnimator[];

@deprecated Use addVirtualAnimator instead.
The direct access to virtualAnimators in future versions will likely be disabled

Story.addVirtualAnimator()

public method [Story]

addVirtualAnimator(animator: VirtualAnimator): void;

Adds a VirtualAnimator to the story.
Use story.removeVirtualAnimator to take it from the story.

Story.removeVirtualAnimator()

public method [Story]

removeVirtualAnimator(animator: VirtualAnimator): void;

Removes a VirtualAnimator to the story.
Use story.addVirtualAnimator to add it to the story.

Story.addDefaultScenes()

public method [Story]

addDefaultScenes(): void;

Adds scenes defined in the html by .abeamer-scene class.
These classes are added automatically during Story constructor.
Add only after a story.reset().

Story.addScene()

public method [Story]

addScene(sceneSelector: SceneSelector): Scene;

Adds a scene to the story.
HTML elements with abeamer-scene class are added automatically.
param: sceneSelector DOM selector, JQuery object or Virtual Scene returns: A pointer to newly created scene

Story.removeScene()

public method [Story]

removeScene(scene: Scene): void;

Removes a frame from scene list and removes the its rendering pipeline but its DOM elements aren't removed.

Story.clear()

public method [Story]

clear(): void;

Rewinds the animation to the start.
Deletes all the scenes and frames from the story.
The DOM is left untouched.

Story.addStoryAnimations()

public method [Story]

addStoryAnimations(sceneSerialAnimes: Animations[][]): void;

Adds a list scene/serial/parallel animations.
In essence, it represents the complete storyline.
Use this method to load the whole storyline from an external file.
Otherwise is preferable to add animation scene by scene.

Story.addStoryAnimationsBySceneId()

public method [Story]

addStoryAnimationsBySceneId(sceneSerialAnimes:
      { [sceneId: string]: Animation[][] }): void;

Adds a list of serial/parallel animations per scene Id.
It requires that each scene has defined the id (DOM attribute).
It bypasses invalid scene ids.

Story.addFlyover()

public method [Story]

addFlyover(handler: FlyoverHandler, params?: FlyoverParams): void;

Adds a flyover, which is a function executed on every render step.

see: flyovers.

Story.gotoScene()

public method [Story]

gotoScene(scene: Scene): void;

Changes the active and visible to a different scene.

Story.findSceneByName()

public method [Story]

findSceneByName(sceneName: string): Scene;

Story.rewind()

public method [Story]

rewind(): void;

Rewinds the animation to the start.

Story.gotoFrame()

public method [Story]

gotoFrame(framePos: int): void;

Moves the current render Position when is not rendering by consuming the pipeline.
Use this only if you need to compute parameters at certain position.
When render starts

Story.getStoryToTeleport()

public method [Story]

getStoryToTeleport(frameOpts?: RenderFrameOptions, isPretty?: boolean): string;

Returns the animations, html, CSS as an object.
Use only if isTeleporting = true.
Send this information via Ajax to the remote server.
Due CORS, it requires a live server to access CSS information.
Set frameOpts, if you need segment rendering.
Set isPretty = true, to test only, since this mode will return a formatted output but bigger in size.

Story.getStoryToTeleportAsConfig()

public method [Story]

getStoryToTeleportAsConfig(frameOpts?: RenderFrameOptions): StoryConfig;

Same as getStoryToTeleport() but it returns as StoryConfig object.
Use this function instead of getStoryToTeleport, if you need to add extra fields.
Modifying the content of config.abeamer is forbidden for 3rd-party remote server rendering.

Story.teleport()

public method [Story]

teleport(frameOpts?: RenderFrameOptions, isPretty?: boolean);

Stores the complete story on a file in the disk.
Use this method only for testing.
This method requires that:

  1. Is on teleporting mode isTeleporting === true
  2. The render server agent. abeamer render ...

Use this method instead of getStoryToTeleport.

Story.startTeleporting()

public method [Story]

startTeleporting(): void;

Use this method only if you have created the story with toTeleport = true
and toStartTeleporting = false, because you need to inject html/css code into the page before the teleporting process starts.
Otherwise, you won't need to call this method since it's called automatically if teleporting a story.

Story.bestPlaySpeed

public property [Story]

bestPlaySpeed: () => uint;

Returns the play speed that best matches the fps.

Story.render()

public method [Story]

render(playSpeedMs?: uint | undefined, frameOpts?: RenderFrameOptions): void;

Starts the Rendering process.
It can render the whole storyline or just a segment.
Forward and backward rending is supported.
If it has a server, such as headless webpage capture program, it will render a frame, and send a message to the server to store it on the disk.
If it's running on the browser, it will render and wait playSpeedMs time.
param: playSpeedMs Play speed in milliseconds, ignored on server mode. ABeamer doesn't guarantee the exact timing.
If it's undefined, it will play at full speed.

Story.finishRender()

public method [Story]

finishRender(): void;

Aborts the rendering process.

Story.exit()

public method [Story]

exit(): void;

Terminates the server in case is a headless webpage capture program.
In other cases, it has no effect.

Story.logFrmt()

public method [Story]

logFrmt(tag: string, params: (string | number)[][], logType?: LogType): void;

Formats a log using a format supported by exact test framework.
This is mostly used internally for testing, but it's publicly available.
param: params list of [name, value]

Story.logMsg()

public method [Story]

logMsg(msg: string): void;

If a server is present and supports logging, it sends a log message to server otherwise it sends to the browser console.

Story.logWarn()

public method [Story]

logWarn(msg: string): void;

If a server is present and supports logging, it sends a warn message to server otherwise it sends to the browser console.

Story.logError()

public method [Story]

logError(msg: string): void;

If a server is present and supports logging, it sends a error message to server otherwise it sends to the browser console.

Story.getElementAdapters()

public method [Story]

getElementAdapters(selector: ElSelectorHandler): ElementAdapter[];

DoneFunc

public export type

export type DoneFunc = () => void;

WaitFunc

public export type

export type WaitFunc = (args: ABeamerArgs, params: AnyParams,
    onDone: DoneFunc) => void;
 

WaitMan

public export interface

export interface WaitMan{ }

WaitMan.addWaitFunc()

public method [WaitMan]

addWaitFunc(func: WaitFunc, params: AnyParams): void;

DirectionInt

public export type

export type DirectionInt = -1 | 1;

LogType

public export type

export type LogType = 0 | 1 | 2;

SceneHandler

public export type

export type SceneHandler = Scene | uint | string;

Scene by Object, index or name

 

StoryConfig

public export interface

export interface StoryConfig{ }

StoryConfig.config

public property [StoryConfig]

config: {
      abeamer: any;
 

StoryMetadata

public export interface

export interface StoryMetadata{ }

StoryMetadata.version

public property [StoryMetadata]

version?: string;

StoryMetadata.author

public property [StoryMetadata]

author?: string;

StoryMetadata.email

public property [StoryMetadata]

email?: string;

StoryMetadata.copyrights

public property [StoryMetadata]

copyrights?: string;

StoryMetadata.categories

public property [StoryMetadata]

categories?: string[];

StoryMetadata.keywords

public property [StoryMetadata]

keywords?: string[];

StoryMetadata.comments

public property [StoryMetadata]

comments?: string[];

StoryMetadata.rating

public property [StoryMetadata]

rating?: uint;

StoryMetadata.createdDateTime

public property [StoryMetadata]

createdDateTime?: string;

ISO DateTime stamp of the creation time.

StoryMetadata.modifiedDateTime

public property [StoryMetadata]

modifiedDateTime?: string;

ISO DateTime stamp of the last modified time.

 

CreateStoryParams

public export interface

export interface CreateStoryParams{ }

Parameters passed to the story when it's created

CreateStoryParams.dontAddDefaultScenes

public property [CreateStoryParams]

dontAddDefaultScenes?: boolean;

Adds automatically the default scenes.

CreateStoryParams.toTeleport

public property [CreateStoryParams]

toTeleport?: boolean;

Defines if the story is going to be teleported.

CreateStoryParams.toStartTeleporting

public property [CreateStoryParams]

toStartTeleporting?: boolean;

Set this parameter to false, if you need to inject html/css code into the page before the teleporting process starts.
default: true

CreateStoryParams.storyAdapter

public property [CreateStoryParams]

storyAdapter?: SceneAdapter;

Set this value, if you need use a Virtual Story Adapter inside of the default DOM Adapter.

CreateStoryParams.logLevel

public property [CreateStoryParams]

logLevel?: uint;

Defines the log level. Use LL_VERBOSE for debugging.
The server can modify this mode.
Set this parameter to log during the constructor phase, otherwise is also possible to set later via story.logLevel.

 

RenderFrameOptions

public export interface

export interface RenderFrameOptions{ }

ABeamer still has to render all the previous frames of active scene bypassing the middle frames, but it won't be render to disk and it will bypass any unnecessary frames.

RenderFrameOptions.renderPos

public property [RenderFrameOptions]

renderPos?: TimeHandler;

First render frame.
If startScene isn't defined it will be relative to the story, otherwise is relative to the startScene.
default: 0

RenderFrameOptions.renderCount

public property [RenderFrameOptions]

renderCount?: TimeHandler;

Total number of frames to render.

EXPERIMENTAL Use a negative value to render backwards.
For backward rendering, ABeamer first has to consume all the frames forward, bypassing all middle frames, only after can render backwards.
default: the total number of frames

RenderFrameOptions.startScene

public property [RenderFrameOptions]

startScene?: SceneHandler;

First scene to be rendered.
Before start rendering the startScene, first, ABeamer first has to consume all the frames until it reaches the beginning of Scene.
Accepts by 'Scene Zero-Based Index', 'Name' or by 'Scene Object'

RenderFrameOptions.endScene

public property [RenderFrameOptions]

endScene?: SceneHandler;

Last scene to be rendered.
Accepts by 'Scene Zero-Based Index', 'Name' or by 'Scene Object'.

createStory()

public export function

export function createStory(fps?: uint,
    createParams?: CreateStoryParams): Story;

Creates a story. Loading parameters from style data.
fps property can also be defined on body.data-fps or config file.

see: config-file.

createStoryFromConfig()

public export function

export function createStoryFromConfig(
    cfgUrl: string,
    callback: (story: Story) => void,
    fps?: uint,
    createParams?: CreateStoryParams): void;

Creates a story by loading the configuration from a file or a teleported story.

see: config-file.