EntityBuilderTexturePositioningRef

A lightweight placeholder for a texture positioning created inside an EntitiesBuilder callback.

The EntitiesBuilder is the high-performance path for creating geometry. When you need to draw hundreds or thousands of edges and faces — like generating a mesh or importing model data — the builder batches everything into a single round-trip to SketchUp, making it dramatically faster than calling operation methods repeatedly.

When you call createTexturePositioning on a builder, it returns this ref immediately. Use it with positionFaceFrontMaterial or positionFaceBackMaterial to map a texture onto a face. This ref is only valid inside the builder callback.

For the best performance, reuse your texture positioning refs if you can. Try to avoid creating them over and over if they aren’t changing.

Texture positioning controls how a material’s texture is draped over geometry — you specify UV mapping pairs that pin texture coordinates to 3D points.

Example

let model = await SketchUpApi.getActiveModel();

// Generate a gradient texture with a canvas
let canvas = document.createElement('canvas');
let ctx = canvas.getContext('2d');
let grad = ctx.createLinearGradient(
  0, 0, canvas.width, canvas.height
);
grad.addColorStop(0, '#f00');
grad.addColorStop(1, '#0f0');
ctx.fillStyle = grad;
ctx.fillRect(0, 0, canvas.width, canvas.height);
let base64 = canvas.toDataURL().split(',')[1];

await model.performOperation(async op => {
  // Create a material with the gradient texture
  const matRef = op.createMaterial('Gradient');
  op.materialSetTextureDataBase64(matRef, base64);

  // The builder callback creates geometry in bulk.
  await op.createBuilder(builder => {
    const corners = [
      [0, 0, 20],
      [100, 0, 20],
      [100, 100, 20],
      [0, 100, 20]
    ];

    const ebFaceRef = builder.faceCreate(corners);

    // createTexturePositioning takes pairs of
    // [modelPoint, uvPoint] that pin model
    // coordinates to UV values. (The 3rd element
    // of the UV array is ignored.) Double the u,v
    // values to get your head around it.
    const ebPosRef =
      builder.createTexturePositioning(
        matRef,
        [
          corners[0], [0, 0, 0],  // left bottom
          corners[1], [1, 0, 0],  // right bottom
          corners[2], [1, 1, 0],  // right top
          corners[3], [0, 1, 0],  // left top
        ],
        undefined // no projection
      );
    builder.positionFaceFrontMaterial(ebFaceRef, ebPosRef);
  })
  .build(model);
}, 'Build face with positioned texture');

See

Properties

index

readonly index: number

Methods

toString()

toString(): string

Returns

string