Play PAG File

Initialize PAGView

Bind the PAGFile object to the canvas object and instantiate it into a PAGView object.

const pagView = await PAG.PAGView.init(pagFile, canvas);

First Frame Rendering

PAGView.init will render the first frame by default.

During the first frame rendering, the VideoReader module is called when there is a BMP composition（The following section describes how to check whether the PAG filehas a BMP composition.）in the PAG animation file.

Due to the dependency of the VideoReader module on the VideoElement in the web platform, certain mobile scenarios may encounter an issue where the PAGView.init is not included in the call chain generated by user interaction. Consequently, this can result in a situation where play is prohibited, leading to abnormal rendering of the images.

When this happens, we recommend canceling the first frame rendering

const pagView = await PAG.PAGView.init(pagFile, canvas, { firstFrame: false });

Then invoke pagView.play() o render the screen in the call chain generated by user interaction.

HD Rendering

When developing for the web, we need to consider two pixel resolutions: device pixel resolution (the actual number of points on the device) and CSS pixel resolution (the number of points we use when programming). The ratio between these two is calleddevicePixelRatio. This means that if we want to display a 1px sized CSS pixel on the screen, the actual size we need to render is 1px *devicePixelRatio。

By default, PAG automatically scales the size of the Canvas to fit the visual size of the screen. This process may change the width, height and style attributes of the Canvas.

If you don't want PAG to modify the attributes of the Canvas, you can cancel scaling during initialization as follows:

const pagView = await PAG.PAGView.init(pagFile, canvas, { useScale: false });

Multiple PAGViews

Firstly, since the PAG Web version is a single-threaded SDK, we do not recommend playing multiple PAGViews on the same screen.

In scenarios where multiple PAGView instances are used, it is important to consider the limited number of active WebGL contexts in different browsers. Chrome allows up to 16 active contexts, while Safari allows up to 8. To work within these limitations, it is recommended to use the destroy method to recycle unnecessary PAGView instances and promptly remove references to Canvas objects.

The recommended solution is to use the combination mode of PAG. To do this, you can create your own PAGComposition and add the PAGFile that you want to play through the addLayer method. The SetStartTime function can be used to set the start time of each PAGFile relative to the PAGComposition, while the setMatrix function can be used to position the PAGFile within the composition.

The following are solutions for special scenarios, which are not recommended:

To have multiple PAGView instances on the same screen in the Chrome browser, without the need for Safari compatibility, you can consider utilizing the canvas2D mode by passing { useCanvas2D: true } during the PAGView.init process. This mode employs a single WebGL renderer, distributing images across multiple canvas2Ds. By doing so, you can circumvent the limitations on the number of active WebGL contexts.

We do not recommend using this mode on Safari due to the poor performance of CanvasRenderingContext2D.drawImage() on Safari.

Rendering Size

To achieve high-definition rendering, PAGView uses the Canvas size multiplied by the devicePixelRatio as the actual rendering size. However, the maximum rendering size of WebGL can differ based on the device's performance. In some cases, the rendering size may be too large, resulting in an empty screen.

It is recommended that on the mobile terminal, the actual rendering size should not be greater than 2560px.

Decoder Injection

For the restriction of the rule "the video tag can be played only after the user interacts with the page", PAG Web version provides the software decoder injection interfacePAG.registerSoftwareDecoderFactory()。

Once the software decoder is installed, PAG will send it to decode and upload the BMP composition.This will enable certain platforms to automatically play when entering the page.

Recommended decoder access: https://github.com/libpag/ffavc/tree/main/web

The platforms known to have restrictions on "users can only use video tags for video play after interacting with the page" include: mobile WeChat browsers, iPhone power-saving mode, and some Android browsers.

Animation Operations

play

pagView.play();

pause

pagView.pause();

end

pagView.stop();

destory

pagView.destroy();

Web Adaptive Descriptions

Fill Modes

When the sizes of PAGView (PAGSurface) and PAGFile are inconsistent, the fill mode will be used to adapt, and the default is LetterBox mode. You can find more information in theConfig Fill Modes section.

Fill Modes:

  • None: No scaling. Cropping starts at the upper left corner.
  • LetterBox: Black edge. Scaling to the available screen size of the device while maintaining aspect ratio ensures that the image does not deform. If the image size and filling area ratio are not consistent, black edges will appear, making it the default fill mode
  • Stretch: Filling without maintaining aspect ratio can cause deformation loss
  • Zoom: Cropping. Scaled to completely fill the available screen size while maintaining the aspect ratio

Canvas Size Changes

As mentioned in the HD Rendering section, PAGView.init() will set the width and height of the canvas to width and height * dpr by default. Afterward, it will use style to scale it back to its original size for display.

However, if the above fill modes cannot meet your needs, you can also turn off the default high-definition rendering of PAGView and manually control the rendering size.

First, you need to calculate the dimensions of the canvas:

const styleDeclaration = window.getComputedStyle(canvas, null);
canvas.width = Number(styleDeclaration.width.replace('px', '')) * window.devicePixelRatio;
canvas.height = Number(styleDeclaration.height.replace('px', '')) * window.devicePixelRatio;

Next, when initializing PAGView, pass in useScale: false to turn off the default high-definition rendering:

const pagView = await PAG.PAGView.init(pagFile, canvas, { useScale: false });

Finally, when thecanvas display size is changed, recalculate the size of the canvas and call the pagView.updateSize method:

window.onresize = () => {
  const styleDeclaration = window.getComputedStyle(canvas, null);
  canvas.width = Number(styleDeclaration.width.replace('px', '')) * window.devicePixelRatio;
  canvas.height = Number(styleDeclaration.height.replace('px', '')) * window.devicePixelRatio;
  pagView.updateSize();
  pagView.flush();
}
← Load PAG FilePlatform Capabilities →