0.171.0 Change Notes

Breaking changes to DisplayStyles

The JSON representation of DisplayStyle and DisplayStyleState expressed by the DisplayStyleProps interface did not match the actual persistent JSON representation. Additionally, DisplayStyle provided no API for querying or modifying most of its settings.

To address these problems the following changes were made:

• DisplayStyleSettingsProps and DisplayStyle3dSettingsProps were added to document the persistent JSON representation of a DisplayStyle's settings.
• Various JSON types used by DisplayStyleSettingsProps were moved from imodeljs-frontend to imodeljs-common; and new ones were added.
• DisplayStyleProps and DisplayStyle3dProps were modified to reflect the persistent JSON representation: specifically, the presence of a jsonProperties.styles object to store the settings.
• DisplayStyleSettings and DisplayStyle3dSettings classes were added to provide access to all of the settings and to keep the JSON properties in sync with modifications to those settings.
• A DisplayStyleSettings member was added to DisplayStyle and DisplayStyleState.

Breaking changes to Viewport.readPixels

The display system underwent several performance optimizations targeted at increasing framerate and reducing memory consumption. These changes produced significant improvements in both of these metrics, but unfortunately necessitated a change to the way that Viewport.readPixels works. The function no longer returns a Pixel.Buffer object; instead it accepts a callback function to receive the pixel buffer. Once the callback returns, the data in the pixel buffer becomes invalid - so storing a reference to the buffer and attempting to use it outside of the callback will produce unexpected results.

These changes also enable some enhancements and simplications to the readPixels function:

• A Pixel.Data object now supplies complete information about the Feature which produced the pixel, including element ID, subcategory ID, and GeometryClass. Previously it could only supply the element ID.
• The Pixel.Selector enumeration has been simplified to allow the caller to request the geometry and distance fraction of each pixel, the feature of each pixel, or both.

As an example of how to adjust your code in response to these changes, consider the following example:

` /** Returns true if the specified element ID is drawn within the specified rectangular region of the viewport */ function isElementInRect(elementId: Id64String, vp: Viewport, rect: ViewRect): Id64String { const pixels: Pixel.Buffer = vp.readPixels(rect, Pixel.Selector.ElementId); if (undefined === pixels) return false;

for (let x = rect.left; x < rect.right; x++) {
  for (let y = rect.top; y < rect.bottom; y++) {
    const pixel: Pixel.Data = pixels.getPixel(x, y);
    if (undefined !== pixel.elementId && pixel.elementId === elementId)
      return true;
  }
}

return false;

}`

This function would be rewritten using a callback as follows:

` /** Returns true if the specified element ID is drawn within the specified rectangular region of the viewport */ function isElementInRect(elementId: Id64String, vp: Viewport, rect: ViewRect): Id64String { let isInRect = false; vp.readPixels(rect, Pixel.Selector.Feature, (pixels?: Pixel.Buffer) => { if (undefined === pixels) return;

  for (let x = rect.left; x < rect.right; x++) {
    for (let y = rect.top; y < rect.bottom; y++) {
      const pixel: Pixel.Data = pixels.getPixel(x, y);
      if (undefined !== pixel.elementId && pixel.elementId === elementId) {
        isInRect = true;
        return;
      }
    }
  }
});

return isInRect;

}`

Breaking changes to IModelClient

To be consistent with imodeljs code style, IModelClient methods have been changed to properties and start with lower case letter.

For example, querying Versions with an IModelHubClient object client should be changed from client.Versions().get(alctx, token, imodelId) to client.versions.get(alctx, token, imodelId).

Last Updated: 13 June, 2024