three-wideline/dist/index.d.ts

A three js line implementation

/// <reference types="react" />

import { Color } from 'three';
import { ColorRepresentation } from 'three';
import { Euler } from '@react-three/fiber';
import { EventHandlers } from '@react-three/fiber/dist/declarations/src/core/events';
import { GroupProps } from '@react-three/fiber';
import { ShaderMaterialProps } from '@react-three/fiber';
import { Vector2 } from 'three';
import { Vector3 } from 'three';
import { Vector3 as Vector3_2 } from '@react-three/fiber';

/**
 * @internal
 * Create a simple mesh geometry consists of two triangles.
 * It look like a box or reactangle.
 */
export declare const boxGeometry: () => IGeometry;

/**
 * @public
 * Line cap representation.
 */
export declare type Caps = (typeof CapsList)[number];

/**
 * @public
 * Line cap representation.
 */
export declare const CapsList: readonly ["Butt", "Round", "Square", "Top"];

/**
 * @public
 * Generate a Zig-Zag line.
 * First points is left top.
 * The last point is right bottom for even count,
 * or right top for odd count.
 * @param count - How many points the line will have, must \>= 2.
 * @param width - The width of the virtual box the line are generated.
 * @param height - The height of the virtual box the line are generated.
 * @returns The coordinates of the line.
 */
export declare function generatePointsInterleaved(count: number, width?: number, height?: number): number[];

/**
 * @public
 * Appearing of the line, mainly width and color.
 */
export declare interface IAttribute {
    /** The main color of the line */
    color?: ColorRepresentation;
    /** Show some inner parts with an alternative color, e.g. miter, bevel ... */
    offals?: ColorRepresentation;
    /** The with of the line */
    width?: number;
}

/**
 * @public
 * Custom element definition
 */
export declare interface ICustom {
    /** How it appear */
    scheme: IScheme;
    /** The user defined geometry */
    geometry: IGeometry;
}

/**
 * @public
 * Geometry definition on excatly one line part, which can be a line segment,
 * or for example a cap or join.
 */
export declare interface IGeometry {
    /** Position (x,y) list */
    positions: number[][];
    /** Cell definition, the vertices of the geometry */
    cells: number[][];
}

/**
 * @public
 * Scheme/Attribute of a shader segment.
 */
export declare interface IScheme {
    /** Color */
    color?: Color;
    /** Opacity */
    opacity?: number;
    /** Width */
    width?: number;
}

/**
 * @internal
 * Collection of geometry and its shader.
 */
export declare interface ISchemeGeometry {
    vertices: IVertices[];
    shader: ShaderMaterialProps[][];
}

/** @internal Index array of vertices */
export declare interface IVertices {
    /** position array */
    position: number[][];
    /** Index array */
    index: number[][];
    /** Line limitations */
    limited?: Where;
}

/**
 * @public
 * Line properties.
 */
export declare interface IWidelineProps {
    /** The shape of the line, some points. */
    points: Shape | Shape[];
    /** The line attribute, use an array to draw multiple lines with same geometry. */
    attr: IAttribute | IAttribute[];
    /** Line opacity, is less than 1, the line is transparent. Optimized shader are used in that case. */
    opacity?: number;
    /** Which joins are used */
    join?: Joins;
    /** The start cap of the line */
    capsStart?: Caps | IGeometry;
    /** The end cap of the line */
    capsEnd?: Caps | IGeometry;
    /** A user defined custom element for any segment of the line @beta */
    custom?: ICustom[];
    /** Line local position. */
    position?: Vector3_2;
    /** Line scale */
    scale?: Vector3_2;
    /** Line rotation */
    rotation?: Euler;
    /** disable raycast options, could be useful for busy scenes to optimize cpu footprint (tons of lines) */
    noRaycast?: boolean;
    /** show for debugging purpose the bounding sphere of the line */
    boundingSphere?: {
        color: ColorRepresentation;
        opacity: number;
    };
    /** some core event handler like onClick() */
    events?: EventHandlers;
}

/**
 * @public
 * Line join representation.
 */
export declare type Joins = (typeof JoinsList)[number];

/**
 * @public
 * Line join representation.
 */
export declare const JoinsList: readonly ["None", "Bevel", "Miter", "Round"];

/**
 * @public
 * Display the three-wideline logo as line drawn by itself.
 *
 * @param props - all possible three js group properties
 */
export declare function Logo(props?: GroupProps): JSX.Element;

/**
 * @internal
 * Geometry of the round cap
 */
export declare const roundCapGeometry: (resolution: number) => IGeometry;

/**
 * @internal
 * Contains line scheme geometry creator.
 * This is a toolset to create the needed meshs for a whole line representation.
 */
export declare class Scheme {
    private data;
    transparency: boolean;
    /** @internal Access to the created geometry and shader */
    getScheme(): ISchemeGeometry;
    /** @internal Reset memory, can be used instead creating new instance */
    reset(): void;
    /**
     * Create simple line segments.
     * A list of meshes like rectangles.
     * At the joins, the rectangles are overlapped.
     */
    simple: (props: IScheme[]) => void;
    /**
     * Create advanced line segments. Instead rectangles trapezoids created.
     * At the joins, these meshes are not overlapped.
     * Strips are used to draw transparent lines.
     */
    strip: (props: IScheme[]) => void;
    /** draw all strips except first element */
    private stripMain;
    /** draw only the first strip element */
    private strip1st;
    /** Add custom meshes */
    custom: (props: IScheme, geometry: IGeometry) => void;
    /** Add bevil joins. */
    bevel: (props: IScheme[]) => void;
    /** Add miter joins. */
    miter: (props: IScheme[]) => void;
    /** Add a cap to the line */
    addCap: (props: IScheme[], geometry: IGeometry | undefined, where: Where) => void;
    /** Add a round join */
    roundJoin: (props: IScheme[], resolution: number) => void;
    /** Append a geometry to the result */
    private addGeometry;
    /** create shader uniform */
    private sprops;
    /** add a list of shaders with its uniforms */
    private addUniforms;
}

/**
 * @public
 * Shape point definition.
 */
export declare type Shape = Vector3[] | Vector2[] | number[];

/**
 * @internal
 * Geometry of the square cap
 */
export declare const squareCapGeometry: () => IGeometry;

/**
 * @internal
 * Geometry of the top cap
 */
export declare const topCapGeometry: () => IGeometry;

/** @internal Create vertices only at start or end of the line */
export declare type Where = "Start" | "End";

/**
 * @public
 * Displayed a 2D-Line as indexed mesh, whereby the mesh consists of the determined line options.
 * A geometry is calculated which are drawn by several vertex shader.
 *
 * @example Line between 2 points with default attributes (white, width=1).
 * ```
 * <Wideline points={[-1, -1, 1, 1]} attr={{}} />
 * ```
 *
 * @example Line between 3 points (red, width=0.2, round join).
 * ```
 * <Wideline points={[-1, -1, 0, 1, 1, -1]} attr={{ color: "red", width: 0.2 }} join="Round" />
 * ```
 */
export declare function Wideline(props: IWidelineProps): JSX.Element;

export { }