message: Document breaking changes.
diff: @@ -3,3 +3,55 @@ ignore: true
  ---
  # NextVersion
  +## 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]($frontend) works. The function no longer *returns* a [Pixel.Buffer]($frontend) 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]($frontend) object now supplies complete information about the [Feature]($common) which produced the pixel, including element ID, subcategory ID, and [GeometryClass]($frontend). Previously it could only supply the element ID.
  +* The [Pixel.Selector]($frontend) 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;
  + }`
  