A story is the entry point of BeamToIX web browser library.
It has the following functions:
The workflow summary is:
DevToIXstory.render which will process the animation pipeline
frame by frame and sends it to the render server agent.see: workflow.
public export interface
export interface WaitMan{ }
public property [WaitMan]
funcs: _WaitFunc[];
public property [WaitMan]
pos: uint;
public method [WaitMan]
addWaitFunc(func: WaitFunc, params: AnyParams): void;
public export interface
export interface Story{ }
Implementation of _Story class.
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.
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;
readonly public property [Story]
readonly hasServer: boolean;
True if it's running a supporting server program for frame storage.
readonly public property [Story]
readonly serverName: string;
The name of the server.
The server will assign this property value.
public property [Story]
serverFeatures: ServerFeatures;
Provides information about the running server.
readonly public property [Story]
readonly metadata: StoryMetadata;
Numerical value of the frame width in pixels.
readonly public property [Story]
readonly width: uint;
Numerical value of the frame width in pixels.
readonly public property [Story]
readonly height: uint;
Numerical value of the frame height in pixels.
readonly public property [Story]
readonly frameCount: uint;
Total number of frames from all the scenes.
readonly public property [Story]
readonly renderDir: DirectionInt;
Render direction. 1 for forward, -1 for backwards.
Defined during the call to story.render.
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.
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.
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.
readonly public property [Story]
readonly isRendering: boolean;
True if the rendering has started.
Use finishRender to abort the rendering process.
readonly public property [Story]
readonly isTeleporting: boolean;
True if it's teleporting.
readonly public property [Story]
readonly args: BeamToIXArgs;
Returns BeamToIXArgs.
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.
public property [Story]
strictMode: boolean;
public property [Story]
logLevel: uint;
public property [Story]
isVerbose: boolean;
readonly public property [Story]
readonly scenes: Scene[];
List of the scenes.
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.
public property [Story]
storyAdapter: SceneAdapter;
Allows flyovers to find elements on the document body or in the virtual world.
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
public property [Story]
onRenderFinished?: (args?: BeamToIXArgs) => void;
Event triggered when render finished the rendering process.
EXPERIMENTAL The behavior can changed or be deprecated.
public property [Story]
onServerReady?: (args?: BeamToIXArgs) => 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.
public property [Story]
onBeforeRenderFrame?: (args?: BeamToIXArgs) => void;
Event triggered before a frame is rendered.
public property [Story]
onAfterRenderFrame?: (args?: BeamToIXArgs) => void;
Event triggered after a frame is rendered.
public property [Story]
onNextFrame?: (args?: BeamToIXArgs) => void;
Event triggered during the rendering process after a frame is rendered and is ready to move to following frame.
public property [Story]
onGetVirtualElement?: (id: string, args?: BeamToIXArgs) => VirtualElement;
Maps Ids into Virtual Elements
Used only in non-DOM elements such as WebGL elements.
param: id virtual element Id without '%'
public property [Story]
virtualAnimators: VirtualAnimator[];
@deprecated Use addVirtualAnimator instead.
The direct access to virtualAnimators in future versions will likely be disabled
public method [Story]
addVirtualAnimator(animator: VirtualAnimator): void;
Adds a VirtualAnimator to the story.
Use story.removeVirtualAnimator to take it from the story.
public method [Story]
removeVirtualAnimator(animator: VirtualAnimator): void;
Removes a VirtualAnimator to the story.
Use story.addVirtualAnimator to add it to the story.
public method [Story]
addDefaultScenes(): void;
Adds scenes defined in the html by .beamtoix-scene class.
These classes are added automatically during Story constructor.
Add only after a story.reset().
public method [Story]
addScene(sceneSelector: SceneSelector): Scene;
Adds a scene to the story.
HTML elements with beamtoix-scene class are added automatically.
param: sceneSelector DOM selector, JQuery object or Virtual Scene
returns: A pointer to newly created scene
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.
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.
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.
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.
public method [Story]
addFlyover(handler: FlyoverHandler, params?: FlyoverParams): void;
Adds a flyover, which is a function executed on every render step.
see: flyovers.
public method [Story]
gotoScene(scene: Scene): void;
Changes the active and visible to a different scene.
public method [Story]
findSceneByName(sceneName: string): Scene;
public method [Story]
rewind(): void;
Rewinds the animation to the start.
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
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.
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.beamtoix is forbidden for 3rd-party
remote server rendering.
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:
isTeleporting === truebeamtoix render ...Use this method instead of getStoryToTeleport.
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.
public property [Story]
bestPlaySpeed: () => uint;
Returns the play speed that best matches the fps.
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. BeamToIX doesn't guarantee the exact timing.
If it's undefined, it will play at full speed.
public method [Story]
finishRender(): void;
Aborts the rendering process.
public method [Story]
exit(): void;
Terminates the server in case is a headless webpage capture program.
In other cases, it has no effect.
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]
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.
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.
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.
public method [Story]
getElementAdapters(selector: ElSelectorHandler): ElementAdapter[];
public export type
export type DoneFunc = () => void;
public export type
export type WaitFunc = (args: BeamToIXArgs, params: AnyParams,
onDone: DoneFunc) => void;
public export interface
export interface WaitMan{ }
public method [WaitMan]
addWaitFunc(func: WaitFunc, params: AnyParams): void;
public export type
export type DirectionInt = -1 | 1;
public export type
export type LogType = 0 | 1 | 2;
public export type
export type SceneHandler = Scene | uint | string;
Scene by Object, index or name
public export interface
export interface StoryConfig{ }
public property [StoryConfig]
config: {
beamtoix: any;
public export interface
export interface StoryMetadata{ }
public property [StoryMetadata]
version?: string;
public property [StoryMetadata]
author?: string;
public property [StoryMetadata]
email?: string;
public property [StoryMetadata]
copyrights?: string;
public property [StoryMetadata]
categories?: string[];
public property [StoryMetadata]
keywords?: string[];
public property [StoryMetadata]
comments?: string[];
public property [StoryMetadata]
rating?: uint;
public property [StoryMetadata]
createdDateTime?: string;
ISO DateTime stamp of the creation time.
public property [StoryMetadata]
modifiedDateTime?: string;
ISO DateTime stamp of the last modified time.
public export interface
export interface CreateStoryParams{ }
Parameters passed to the story when it's created
public property [CreateStoryParams]
dontAddDefaultScenes?: boolean;
Adds automatically the default scenes.
public property [CreateStoryParams]
toTeleport?: boolean;
Defines if the story is going to be teleported.
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
public property [CreateStoryParams]
storyAdapter?: SceneAdapter;
Set this value, if you need use a Virtual Story Adapter inside of the default DOM Adapter.
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.
public export interface
export interface RenderFrameOptions{ }
BeamToIX 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.
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
public property [RenderFrameOptions]
renderCount?: TimeHandler;
Total number of frames to render.
EXPERIMENTAL Use a negative value to render backwards.
For backward rendering, BeamToIX first has to consume all the frames forward,
bypassing all middle frames, only after can render backwards.
default: the total number of frames
public property [RenderFrameOptions]
startScene?: SceneHandler;
First scene to be rendered.
Before start rendering the startScene, first,
BeamToIX 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'
public property [RenderFrameOptions]
endScene?: SceneHandler;
Last scene to be rendered.
Accepts by 'Scene Zero-Based Index', 'Name' or by 'Scene Object'.
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.
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.