@masatomakino/threejs-billboard
    Preparing search index...

    Variable ScaleCalculatorConst

    ScaleCalculator: {
        getNonAttenuateScale(
            rendererHeight: number,
            camera: PerspectiveCamera,
        ): number;
    } = ...

    Utility for calculating billboard scale values based on camera and renderer parameters.

    This utility provides methods to achieve pixel-perfect rendering for billboards, particularly when working with Sprite objects that have sizeAttenuation = false. The calculations ensure that billboard pixels map directly to screen pixels regardless of the camera's distance from the billboard.

    The scale calculation is based on the relationship between:

    • Camera's field of view (FOV)
    • Renderer canvas height in pixels
    • Distance from camera to billboard

    For pixel-perfect rendering, the scale factor must compensate for the perspective projection to ensure that one unit in Three.js coordinate space equals one pixel on the screen at a given distance.

    Type declaration

    • getNonAttenuateScale: function

      • Calculates the scale value for Sprite objects with sizeAttenuation = false.

        This method computes the appropriate scale factor to achieve pixel-perfect rendering where the billboard's size on screen matches exactly with the source image's pixel dimensions, regardless of camera distance.

        • The Sprite material must have sizeAttenuation = false
        • The billboard should be positioned at distance 1.0 from the camera for optimal results
        • The camera should be a PerspectiveCamera (OrthographicCamera not supported)

        The scale factor is calculated as: scale = visibleHeight / rendererHeight

        Where visibleHeight is the height of the view frustum at distance 1.0 unit from the camera.

        This method does not consider devicePixelRatio. It calculates the scale based solely on the rendered canvas height and camera settings. If your application uses high-DPI displays with devicePixelRatio > 1, you may need to adjust the calculation separately.

        Parameters

        • rendererHeight: number

          Height of the rendered canvas in pixels (not physical device pixels)

        • camera: PerspectiveCamera

          The perspective camera used for rendering

        Returns number

        Scale factor to apply to the billboard for pixel-perfect rendering

        // Basic usage
        const scale = ScaleCalculator.getNonAttenuateScale(
          renderer.domElement.height,
          camera
        );

        // Apply to billboard
        billboard.imageScale = scale;
        billboard.material.sizeAttenuation = false;

        // For a 64x64 pixel image, the billboard will appear exactly 64x64 pixels on screen

    // Set up pixel-perfect billboard rendering
    const billboard = new Billboard("./texture.png", 1.0);
    const scale = ScaleCalculator.getNonAttenuateScale(renderer.domElement.height, camera);
    billboard.imageScale = scale;
    billboard.material.sizeAttenuation = false; // Required!

    // The billboard will now display at exactly the pixel size of the source image

    Settings

    Member Visibility

    On This Page

    Mathematical BackgroundPrerequisitesScale Factor CalculationImportant Note on Device Pixel Ratio