Skip to content

images

Jump to bottom
Black Ram edited this page Jul 11, 2024 · 32 revisions

Images

To make adding and managing images on the canvas easier than pixi.js methods, Pixi’VN it has very basic functions for showing an image.

Show Image

The simplest and fastest method to show an image on the canvas is to use the showImage function.

This function has the following parameters:

  • tag: Is a tag (or id) for the image. There can only be one item in the canvas with that id, if you add an image with the same tag, the previous image will be removed.
  • imageUrl: The URL or path of the image.
import { showImage } from '@drincs/pixi-vn'

showImage('image1', 'path/to/image.png')

This function is a combination of the addImage and load functions. It is very simple to use, but in cases where you want to manipulate the image before showing it, it is better to use the addImage and load functions separately.

Add image

To add an image to the canvas, you can use the addImage function. This function will return a CanvasImage object that you can use to manipulate the image. CanvasImage is a class the extends CanvasSprite, so you can use all the methods and properties of CanvasSprite.

It is important to take into account that this function only adds the element to the canvas but does not show it and does not load its texture.

addImage function has the following parameters:

  • tag: Is a tag (or id) for the image. There can only be one item in the canvas with that id, if you add an image with the same tag, the previous image will be removed.
  • imageUrl: The URL or path of the image.
import { addImage } from '@drincs/pixi-vn'

const image = addImage('image1', 'path/to/image.png')

If you want initialize the image before and then add it to the canvas, you can use the GameWindowManager.addCanvasElementfunction.

import { GameWindowManager, CanvasImage } from '@drincs/pixi-vn'

let alien = new CanvasImage({
    anchor: { x: 0.5, y: 0.5 },
    x: 100,
    y: 100,
}, 'https://pixijs.com/assets/eggHead.png')

GameWindowManager.addCanvasElement("alien", alien)

Load Image

After adding the image, you can load the texture and show it on the canvas using the CanvasImage.load method.

This method is asynchronous, so:

  • You can use the await to wait for the image to load. So if you show the image in a step, you can disable the next step until the image is loaded.
  • You can not use the await and show the image in the next step. In this case, the image will be loaded in the background and will be shown when it is ready.
import { addImage } from '@drincs/pixi-vn'

const image = addImage('image1', 'path/to/image.png')
await image.load()

In some cases you may need to ensure that multiple images are displayed at the same time. In this case, you can use the loadImage function to load a array of CanvasImage.

import { addImage, loadImage } from '@drincs/pixi-vn'

const image1 = addImage('image1', 'path/to/image1.png')
const image2 = addImage('image2', 'path/to/image2.png')

await loadImage([image1, image2])

You can use loadImage also to show a single image.

import { addImage, loadImage } from '@drincs/pixi-vn'

const image = addImage('image1', 'path/to/image.png')

await loadImage(image)
// or await image.load()

Another way to make sure multiple images are displayed at the same time is to use the PIXI.Assets function, for add the textures in cache.

import { addImage, loadImage } from '@drincs/pixi-vn'
import { Assets } from "pixi.js";

// Load the images and add them to the cache
await Assets.load('path/to/image1.png')
await Assets.load('path/to/image2.png')

const image1 = addImage('image1', 'path/to/image1.png')
const image2 = addImage('image2', 'path/to/image2.png')

// The images are already loaded, so you can show them without waiting
image1.load()
image2.load()

Load Image Textures in Cache when a label is called

If a label shows a sequence of very large images, it can be very useful to load the images in the cache when the label is called. This way, the images will be loaded in the background and will be ready to be displayed when they are needed.

export const startLabel = newLabel("StartLabel", [
    // use the image1 ...
    // ...
    ], () => {
        // Load the images in the cache asynchronously, so the images will be loaded in the background
        Assets.load('path/to/image1.png')
        Assets.load('path/to/image2.png')
    }
)
export const startLabel = newLabel("StartLabel", [
    // use the image1 ...
    // ...
    ], () => {
        // Load the images in the cache synchronously, so before the next step the images will be loaded
        await Assets.load('path/to/image1.png')
        await Assets.load('path/to/image2.png')
    }
)

Remove Image

As for the Canvas Elements, you can remove an image from the canvas using the removeCanvasElement function.

Show/Remove Image with Transition

Functions have been implemented to show images with some "standard" transitions.

( More are on the way )

Dissolve Transition

With the Dissolve Transition means that the image will be shown with a fade-in effect. If exist a image with the same tag, then the image is replaced and the first image is removed after the effect is done.

( This transition is created with the TickerFade )

The showWithDissolveTransition function has the following parameters:

  • tag: The unique tag of the image. You can use this tag to refer to this image
  • image: The imageUrl or the canvas element
  • props: The properties of the effect
  • priority: ( optional ) The priority of the effect
import { showWithDissolveTransition } from '@drincs/pixi-vn'

showWithDissolveTransition('image1', 'path/to/image.png', { duration: 2 })
import { showWithDissolveTransition } from '@drincs/pixi-vn'

let sprite = new CanvasSprite(yourTexture)
// you can pass a canvas element
showWithDissolveTransition('image1', sprite, { duration: 2 })

For remove an image with a fade-out effect, you can use the removeWithDissolveTransition function.

import { removeWithDissolveTransition } from '@drincs/pixi-vn'

removeWithDissolveTransition('image1', { duration: 2 })

Fade Transition

With the Fade Transition means that the image will be shown with a fade-in effect. If exist a image with the same tag, the existing image is removed with a fade transition, and after the effect is done, the new image is shown with a fade transition.

( This transition is created with the TickerFade )

The showWithFadeTransition function has the following parameters:

  • tag: The unique tag of the image. You can use this tag to refer to this image
  • image: The imageUrl or the canvas element
  • props: The properties of the effect
  • priority: ( optional ) The priority of the effect
import { showWithFadeTransition } from '@drincs/pixi-vn'

showWithFadeTransition('image1', 'path/to/image.png', { duration: 2 })
import { showWithFadeTransition } from '@drincs/pixi-vn'

let sprite = new CanvasSprite(yourTexture)
// you can pass a canvas element
showWithFadeTransition('image1', sprite, { duration: 2 })

For remove an image with a fade-out effect, you can use the removeWithFadeTransition function.

import { removeWithFadeTransition } from '@drincs/pixi-vn'

removeWithFadeTransition('image1', { duration: 2 })

Other Transitions and Animations

The functions above do nothing more than add an image to the canvas, display it and start a Ticker. So you can use GameWindowManager.addTicker to add your own transitions and animations.

If you create or need a transition or animation, please create a issue to share/propose it.

How to force completion of an Transition in the next step?

Read this

Clone this wiki locally