UIImageGroup

UIImageGroup provides the display function of multiple images. This component allows you to control multiple Quad rendering under one component. Compared with the UIImage component, the main differences are as follows:

1. UIImageGroup multiple Quad is bound to an Object3D object. When rendering the same type of Sprite type in batches, UIImageGroup can get more efficient rendering performance;
2. Each Quad in UIImageGroup uses its own size data, and the scaling of the UITransform corresponding to the node will not affect each Quad;
3. UIImageGroup needs to specify the subscript index to find the corresponding Quad object, and the Quad attribute needs to be set by calling the corresponding set API.

Initialize the image group:

...
// Create image group node
let groupObj = new Object3D();
panelRoot.addChild(groupObj);

// The ImageGroup component needs to set how many Quad nodes are built in, the default is 1
this.imageGroup = groupObj.addComponent(UIImageGroup, (count: 2));

Set the texture

Same as a single UIImage, we first need to load the sprite atlas through Engine3D.res.loadAtlas, and then assign the texture content of the quad in the specified index in the image group through setSprite:

// Load Atlas atlas material
await Engine3D.res.loadAtlas('atlas/UI_atlas.json');
// Set the 0th sprite texture
imageGroup.setSprite(0, Engine3D.res.getGUISprite('logo'));

Modifying image color

同样，通过 setColor 更改对应 index 的 quad 颜色，如果组件有设置贴图，会乘法叠加贴图像素颜色： Similarly, change the color of the corresponding index of quad through setColor in the same way. If the component has a texture, the pixel color of the texture will be multiplied and added:

imageGroup.setColor(0, new Color(1.0, 0.0, 0.0, 1.0));

Modifying image size

通过 setSize 更改对应 index 的 quad 大小： Change the size of the corresponding index of quad through setSize:

imageGroup.setSize(0, 100, 100);

Component visible (visible / hidden)

图片组中，可以设置 visible 属性统一修改所有 quad 显示或隐藏: In the image group, you can set the visible property to uniformly modify all quad display or hide:

imageGroup.visible = false;//or true

Destroy image group

imageGroup.destroy();

Modifying the stretching / tiling type of the specified subscript sprite

Type of sprite map: refer to ImageType, set the rendering type of the sprite;

• Simple: Default type, the sprite map is stretched and tiled to the specified area
• Sliced: Stretched and rendered in a nine-grid manner
• Tiled: Not supported
• Filled: Not supported

imageGroup.setImageType(0, ImageType.Simple);

Following example shows how to set the position and size of a single Quad in UIImageGroup:

WebGPU is not supported in your browser
Please upgrade to latest Chrome/Edge

<

import { AtmosphericComponent, BitmapTexture2D, Camera3D, Engine3D, HoverCameraController, Object3D, Scene3D, Texture, UIImageGroup, View3D, ViewPanel, makeAloneSprite } from '@orillusion/core';
import * as dat from 'dat.gui';

class Sample_UIImageGroup {
    scene: Scene3D;
    imageGroup: UIImageGroup;

    async run() {
        Engine3D.setting.shadow.autoUpdate = true;
        // initializa engine
        await Engine3D.init();
        // create new scene as root node
        let scene3D: Scene3D = new Scene3D();
        scene3D.addComponent(AtmosphericComponent);
        // create camera
        let cameraObj: Object3D = new Object3D();
        let camera = cameraObj.addComponent(Camera3D);
        // adjust camera view
        camera.perspective(60, Engine3D.aspect, 1, 5000.0);
        // set camera controller
        let controller = cameraObj.addComponent(HoverCameraController);
        controller.setCamera(0, -20, 30);
        // add camera node
        scene3D.addChild(cameraObj);

        let view = new View3D();
        view.scene = scene3D;
        view.camera = camera;
        Engine3D.startRenderView(view);

        this.scene = scene3D;

        await this.createImageGroup();
    }

    async createImageGroup() {
        // enable ui canvas
        let canvas = this.scene.view.enableUICanvas();
        //create UI root
        let panelRoot: Object3D = new Object3D();
        //create panel
        let panel = panelRoot.addComponent(ViewPanel);
        canvas.addChild(panel.object3D);

        let bitmapTexture2D = new BitmapTexture2D();
        bitmapTexture2D.flipY = true;
        await bitmapTexture2D.load('https://cdn.orillusion.com/images/webgpu.png');

        let uiNode = new Object3D();
        panelRoot.addChild(uiNode);
        //create sprite sheet list
        this.imageGroup = this.createSpriteSheets(uiNode, bitmapTexture2D);
        this.createGUI();
    }

    private halfSize = 0;
    createGUI() {
        let GUIHelp = new dat.GUI();
        let quat = this.imageGroup.getQuad(1);
        let f = GUIHelp.addFolder('Position');
        let pos = { x: quat.x, y: quat.y };
        let action = () => this.imageGroup.setXY(1, pos.x, pos.y);
        f.add(pos, 'x', -Engine3D.width / 2, Engine3D.width / 2, 1).onChange(action);
        f.add(pos, 'y', -Engine3D.height / 2, Engine3D.height / 2, 1).onChange(action);
        f.open();

        f = GUIHelp.addFolder('Size');
        let size = { width: quat.width, height: quat.height };
        let action2 = () => this.imageGroup.setSize(1, size.width, size.height);
        f.add(size, 'width', 0, 256, 1).onChange(action2);
        f.add(size, 'height', 0, 256, 1).onChange(action2);
        f.open();
    }

    private createSpriteSheets(root: Object3D, texture: Texture): UIImageGroup {
        let sprite = makeAloneSprite('logo', texture);
        let imgGroup = root.addComponent(UIImageGroup, { count: 2 });
        let size = 128;
        this.halfSize = size * 0.5;
        for (let i = 0; i < 2; i++) {
            imgGroup.setSprite(i, sprite);
            imgGroup.setSize(i, size, size);
            if (i == 1) {
                imgGroup.setXY(1, -this.halfSize, this.halfSize);
            } else {
                imgGroup.setXY(0, -this.halfSize, -this.halfSize);
            }
        }
        return imgGroup;
    }
}

new Sample_UIImageGroup().run();