Engine API Reference - v2.14.4
    Preparing search index...

    Class Picker

    Picker object used to select mesh instances from screen coordinates. It can also optionally capture depth information to determine world positions of picked points.

    The picker works by rendering mesh instances to an offscreen render target with unique IDs encoded as colors. When queried, it reads back the pixel data to identify which mesh instance was at the specified screen coordinates. If depth picking is enabled, it also captures depth values to compute world positions.

    Main API methods:

    Performance considerations: The picker resolution can be set lower than the screen resolution for better performance, though this reduces picking precision and may miss small objects.

    // Create a picker with depth picking enabled at quarter resolution
    const picker = new pc.Picker(app, canvas.width * 0.25, canvas.height * 0.25, true);

    // In your update loop, prepare the picker
    picker.resize(canvas.width * 0.25, canvas.height * 0.25);
    picker.prepare(camera, scene);

    // Pick mesh instances in an area
    picker.getSelectionAsync(x, y, width, height).then((meshInstances) => {
        meshInstances.forEach((meshInstance) => {
            console.log('Picked:', meshInstance.node.name);
        });
    });

    // Pick world position (requires depth enabled)
    picker.getWorldPointAsync(x, y).then((worldPoint) => {
        if (worldPoint) {
            console.log(worldPoint);
        }
    });
    Index

    Constructors

    constructor

    Properties

    height width

    Methods

    destroy getSelection getSelectionAsync getWorldPointAsync prepare resize

    Constructors

    • Create a new Picker instance.

      Parameters

      • app: AppBase

        The application managing this picker instance.

      • width: number

        The width of the pick buffer in pixels.

      • height: number

        The height of the pick buffer in pixels.

      • Optionaldepth: boolean = false

        Whether to enable depth picking. When enabled, depth information is captured alongside mesh IDs using MRT. Defaults to false.

      Returns Picker

    Properties

    height: number
    width: number

    Methods

    • Return the list of mesh instances selected by the specified rectangle in the previously prepared pick buffer. The rectangle using top-left coordinate system.

      Note: This function is not supported on WebGPU. Use Picker#getSelectionAsync instead. Note: This function is blocks the main thread while reading pixels from GPU memory. It's recommended to use Picker#getSelectionAsync instead.

      Parameters

      • x: number

        The left edge of the rectangle.

      • y: number

        The top edge of the rectangle.

      • Optionalwidth: number = 1

        The width of the rectangle. Defaults to 1.

      • Optionalheight: number = 1

        The height of the rectangle. Defaults to 1.

      Returns MeshInstance[]

      An array of mesh instances that are in the selection.

      // Get the selection at the point (10,20)
      const selection = picker.getSelection(10, 20);

      // Get all models in rectangle with corners at (10,20) and (20,40)
      const selection = picker.getSelection(10, 20, 10, 20);

    • Return the list of mesh instances selected by the specified rectangle in the previously prepared pick buffer. The rectangle uses top-left coordinate system.

      This method is asynchronous and does not block the execution.

      Parameters

      • x: number

        The left edge of the rectangle.

      • y: number

        The top edge of the rectangle.

      • Optionalwidth: number = 1

        The width of the rectangle. Defaults to 1.

      • Optionalheight: number = 1

        The height of the rectangle. Defaults to 1.

      Returns Promise<MeshInstance[]>

      • Promise that resolves with an array of mesh instances that are in the selection.
      // Get the mesh instances at the rectangle with start at (10,20) and size of (5,5)
      picker.getSelectionAsync(10, 20, 5, 5).then((meshInstances) => {
         console.log(meshInstances);
      });

    • Return the world position of the mesh instance picked at the specified screen coordinates.

      Parameters

      • x: number

        The x coordinate of the pixel to pick.

      • y: number

        The y coordinate of the pixel to pick.

      Returns Promise<Vec3 | null>

      Promise that resolves with the world position of the picked point, or null if no depth is available or nothing was picked.

      // Get the world position at screen coordinates (100, 50)
      picker.getWorldPointAsync(100, 50).then((worldPoint) => {
          if (worldPoint) {
              console.log('World position:', worldPoint);
              // Use the world position
          } else {
              console.log('No object at this position');
          }
      });

    • Primes the pick buffer with a rendering of the specified models from the point of view of the supplied camera. Once the pick buffer has been prepared, Picker#getSelection can be called multiple times on the same picker object. Therefore, if the models or camera do not change in any way, Picker#prepare does not need to be called again.

      Parameters

      • camera: CameraComponent

        The camera component used to render the scene.

      • scene: Scene

        The scene containing the pickable mesh instances.

      • Optionallayers: Layer[]

        Layers from which objects will be picked. If not supplied, all layers of the specified camera will be used.

      Returns void

    • Sets the resolution of the pick buffer. The pick buffer resolution does not need to match the resolution of the corresponding frame buffer use for general rendering of the 3D scene. However, the lower the resolution of the pick buffer, the less accurate the selection results returned by Picker#getSelection. On the other hand, smaller pick buffers will yield greater performance, so there is a trade off.

      Parameters

      • width: number

        The width of the pick buffer in pixels.

      • height: number

        The height of the pick buffer in pixels.

      Returns void

    Settings

    Member Visibility

    On This Page

    Constructors
    Properties
    Methods