export type GridTheme = { /** * - The axis line colors. */ axis: { x: Color; y: Color; z: Color; }; /** * - The major line color. */ major: Color; /** * - The minor line color. */ minor: Color; }; /** * The plane of a {@link Grid} in its node's local space: 'xz', 'xy' or 'yz'. */ export type GridPlane = "xz" | "xy" | "yz"; /** * An anti-aliased reference grid whose levels of lines follow the zoom. It follows the camera and * fades out with distance, or is sized by its node's scale when not {@link Grid#infinite}. It lies * at its node's position and rotation; use {@link Grid#spacing} to size the cells. * * ```javascript * const grid = new Grid(app.graphicsDevice); * entity.addComponent('render', { * meshInstances: grid.meshInstances, * castShadows: false * }); * ``` * * Relevant Engine API examples: * * - [Grid](https://playcanvas.github.io/#/graphics/grid) * * @category Graphics */ export class Grid { /** * Creates a new Grid instance. * * @param {GraphicsDevice} device - The graphics device. * @example * const grid = new Grid(app.graphicsDevice); * grid.spacing = 1; * grid.plane = 'xy'; */ constructor(device: GraphicsDevice); /** * @type {GraphicsDevice} * @private */ private _device; /** * @type {ShaderMaterial} * @private */ private _material; /** * Writes the depth of the lines. * * @type {ShaderMaterial} * @private */ private _depthMaterial; /** * @type {MeshInstance[]} * @private */ private _meshInstances; /** * @type {GridTheme} * @private */ private _theme; /** * @type {GridPlane} * @private */ private _plane; /** * @type {boolean} * @private */ private _showAxes; /** * @type {boolean} * @private */ private _contrast; /** * @type {number} * @private */ private _spacing; /** * @type {number} * @private */ private _subdivisions; /** * @type {number} * @private */ private _majorLineThickness; /** * @type {number} * @private */ private _minorLineThickness; /** * @type {number} * @private */ private _axisLineThickness; /** * CSS pixels to device pixels. * * @type {number} * @private */ private _pixelRatio; /** * @type {Vec2} * @private */ private _fadeRange; /** * @type {boolean} * @private */ private _infinite; /** * @type {number} * @private */ private _depthOffset; /** * @type {boolean} * @private */ private _depthTest; /** * @type {boolean} * @private */ private _depthWrite; /** * @type {boolean} * @private */ private _depthDither; /** * @type {boolean} * @private */ private _visible; /** * @private */ private _updatePixelRatio; /** * Gets the mesh instances to add to a render component or layer: the lines and their depth * pass. They have no node, so set one when adding them to a layer directly. * * @type {MeshInstance[]} */ get meshInstances(): MeshInstance[]; /** * Gets the theme. * * @type {GridTheme} */ get theme(): GridTheme; /** * Sets the theme or part of it. Each color's alpha sets its lines' opacity. * * @param {{ axis?: Partial, major?: Color, minor?: Color }} partial - The * theme to set. * @example * grid.setTheme({ * axis: { x: new Color(1, 0, 0) }, * minor: new Color(0.5, 0.5, 0.5, 0.5) * }); */ setTheme(partial: { axis?: Partial; major?: Color; minor?: Color; }): void; /** * Sets the plane in the node's local space. Defaults to 'xz'. * * @type {GridPlane} */ set plane(value: GridPlane); /** * Gets the plane. * * @type {GridPlane} */ get plane(): GridPlane; /** * Sets whether the lines through the origin use the axis colors. Defaults to true. * * @type {boolean} */ set showAxes(value: boolean); /** * Gets whether the lines through the origin use the axis colors. * * @type {boolean} */ get showAxes(): boolean; /** * Sets whether the lines are black over light parts of the scene and white over dark ones, * instead of their theme colors. Needs the scene color map, see * {@link CameraComponent#requestSceneColorMap}. Defaults to false. * * @type {boolean} */ set contrast(value: boolean); /** * Gets whether the lines contrast with the scene. * * @type {boolean} */ get contrast(): boolean; /** * Sets the cell size the levels are scaled from, in world units. Defaults to 10. * * @type {number} */ set spacing(value: number); /** * Gets the cell size the levels are scaled from. * * @type {number} */ get spacing(): number; /** * Sets how many cells of a level fit across one of the level above, or 1 for a single fixed * level. Defaults to 10. * * @type {number} */ set subdivisions(value: number); /** * Gets how many cells of a level fit across one of the level above. * * @type {number} */ get subdivisions(): number; /** * Sets the major line thickness in CSS pixels. Defaults to 1.5. * * @type {number} */ set majorLineThickness(value: number); /** * Gets the major line thickness in CSS pixels. * * @type {number} */ get majorLineThickness(): number; /** * Sets the minor line thickness in CSS pixels. Defaults to 1. * * @type {number} */ set minorLineThickness(value: number); /** * Gets the minor line thickness in CSS pixels. * * @type {number} */ get minorLineThickness(): number; /** * Sets the axis line thickness in CSS pixels. Defaults to 2. * * @type {number} */ set axisLineThickness(value: number); /** * Gets the axis line thickness in CSS pixels. * * @type {number} */ get axisLineThickness(): number; /** * Sets the distances from the camera where the grid starts and finishes fading out. The end is * kept within 90% of the far clip. Defaults to [400, 1000]. * * @type {Vec2} */ set fadeRange(value: Vec2); /** * Gets the distances from the camera where the grid starts and finishes fading out. * * @type {Vec2} */ get fadeRange(): Vec2; /** * Sets whether the grid has no edge. When false, it is sized by its node's scale along the * plane's axes. Defaults to true. * * @type {boolean} */ set infinite(value: boolean); /** * Gets whether the grid has no edge. * * @type {boolean} */ get infinite(): boolean; /** * Sets the fraction of the camera distance the grid's depth moves toward the camera by, so a * coplanar surface doesn't hide it. Defaults to 0.001. * * @type {number} */ set depthOffset(value: number); /** * Gets the fraction of the camera distance the grid's depth moves toward the camera by. * * @type {number} */ get depthOffset(): number; /** * Sets whether the grid is depth tested against the scene. Defaults to true. * * @type {boolean} */ set depthTest(value: boolean); /** * Gets whether the grid is depth tested against the scene. * * @type {boolean} */ get depthTest(): boolean; /** * Sets whether the lines write depth, hiding transparent meshes and gaussian splats behind * them. Defaults to false. * * @type {boolean} */ set depthWrite(value: boolean); /** * Gets whether the lines write depth. * * @type {boolean} */ get depthWrite(): boolean; /** * Sets whether the written depth is dithered by line coverage, so faint lines partly hide what * is behind them. Suits gaussian splats. Defaults to false. * * @type {boolean} */ set depthDither(value: boolean); /** * Gets whether the written depth is dithered. * * @type {boolean} */ get depthDither(): boolean; /** * Sets whether the grid is visible. Defaults to true. * * @type {boolean} */ set visible(value: boolean); /** * Gets whether the grid is visible. * * @type {boolean} */ get visible(): boolean; /** * Creates a grid material. * * @param {boolean} depth - Whether it writes depth instead of color. * @returns {ShaderMaterial} The material. * @private */ private _createMaterial; /** * Sets a parameter on both materials. * * @param {string} name - The name of the parameter. * @param {number|number[]} value - The value of the parameter. * @private */ private _setParameter; /** * @param {string} name - The name of the parameter. * @param {Color} color - The color. * @private */ private _updateColor; /** * @private */ private _updatePlane; /** * @private */ private _updateLevels; /** * @private */ private _updateThickness; /** * @private */ private _updateFade; /** * @private */ private _updateInfinite; /** * @private */ private _updateVisible; /** * Destroys the mesh instances and materials. Remove the mesh instances from use first. */ destroy(): void; } import { Color } from '../../core/math/color.js'; import { MeshInstance } from '../../scene/mesh-instance.js'; import { Vec2 } from '../../core/math/vec2.js'; import type { GraphicsDevice } from '../../platform/graphics/graphics-device.js';