Upgrade Guide to Version 2.23.0 and Above

This document introduces the instructions and precautions for upgrading the Express Flutter platform SDK to version 2.23.0 and above.

Change Description

To facilitate the use of rendering functionality, starting from version 2.23.0, it has been decided to remove the ZegoExpressTextureRenderUtils and ZegoExpressPlatformViewUtils interfaces.

Therefore, when upgrading from an old version to 2.23.0 or above, developers need to migrate to the new ZegoExpressCanvasViewUtils interface to use rendering functionality.

The ZegoExpressCanvasViewUtils interface supports both Texture and PlatformView rendering methods.

Reason for Changes

The Express SDK supports two rendering methods: Texture and PlatformView. Before version 2.22.0, these two rendering methods corresponded to two separate APIs. Since some Flutter platforms only support one of the rendering methods, developers need to determine which API can be used on the corresponding platform:

• Texture: ZegoExpressTextureRenderUtils

  • createTextureRenderer
  • destroyTextureRenderer
  • updateTextureRendererSize

• PlatformView: ZegoExpressPlatformViewUtils

  • createPlatformView
  • destroyPlatformView

To reduce the cost of use, a brand new API was introduced in version 2.22.0:

• ZegoExpressCanvasViewUtils
  • createCanvasView
  • destroyCanvasView

This API shields the differences in usage between the previous two rendering methods and supports both Texture and PlatformView rendering methods.

• For platforms that support both rendering methods, the decision to use PlatformView or Texture is based on the enablePlatformView parameter when calling createEngineWithProfile.

• For platforms that only support one rendering method, the only supported rendering method will be used automatically. In this case, the enablePlatformView parameter is invalid, meaning the behavior mode of the enablePlatformView parameter is preference rather than specification.

Starting from SDK version 2.23.0 and above, macOS and Windows are officially supported. The rendering methods and platform support for version 2.23.0 and above are as follows:

Version 2.23.0 and above refactored the video rendering functionality to support CanvasView, improving performance and smoothness, but also broke the original behavior of ZegoExpressTextureRenderUtils (view mode abnormality).

To avoid this change affecting user experience, it has been decided to remove the aforementioned ZegoExpressTextureRenderUtils and ZegoExpressPlatformViewUtils interfaces.

Developers need to migrate to the new ZegoExpressCanvasViewUtils interface. The specific interface changes are as follows:

Sample Code

You can refer to the following sample code for interface changes, or refer to the latest Demo for interface changes.

Before Version 2.23.0

• Texture

// TextureRenderer

late int _viewID;
Widget? _viewWidget;

void start() {
  ZegoExpressEngine.instance.createTextureRenderer(width, height).then((viewID) {
    _viewID = viewID;
    setState(() {
      _viewWidget = Texture(textureId: viewID)
    });
    ZegoCanvas canvas = ZegoCanvas.view(viewID);
    // Call [startPreview] or [startPlayingStream] interface
    // ......
  });
}

void stop() {
  // Call [stopPreview] or [stopPlayingStream]
  // ......
  ZegoExpressEngine.instance.destroyTextureRenderer(_viewID);
}

// TextureRenderer

late int _viewID;
Widget? _viewWidget;

void start() {
  ZegoExpressEngine.instance.createTextureRenderer(width, height).then((viewID) {
    _viewID = viewID;
    setState(() {
      _viewWidget = Texture(textureId: viewID)
    });
    ZegoCanvas canvas = ZegoCanvas.view(viewID);
    // Call [startPreview] or [startPlayingStream] interface
    // ......
  });
}

void stop() {
  // Call [stopPreview] or [stopPlayingStream]
  // ......
  ZegoExpressEngine.instance.destroyTextureRenderer(_viewID);
}

• PlatformView

// PlatformView

late int _viewID;
Widget? _viewWidget;

void start() {
  setState(() {
    _viewWidget = ZegoExpressEngine.instance.createPlatformView((viewID) {
      _viewID = viewID;
      ZegoCanvas canvas = ZegoCanvas.view(viewID);
      // Call [startPreview] or [startPlayingStream]
      // ......
    });
  });
}

void stop() {
  // Call [stopPreview] or [stopPlayingStream]
  // ......
  ZegoExpressEngine.instance.destroyPlatformView(_viewID);
}

// PlatformView

late int _viewID;
Widget? _viewWidget;

void start() {
  setState(() {
    _viewWidget = ZegoExpressEngine.instance.createPlatformView((viewID) {
      _viewID = viewID;
      ZegoCanvas canvas = ZegoCanvas.view(viewID);
      // Call [startPreview] or [startPlayingStream]
      // ......
    });
  });
}

void stop() {
  // Call [stopPreview] or [stopPlayingStream]
  // ......
  ZegoExpressEngine.instance.destroyPlatformView(_viewID);
}

Version 2.23.0 and Above

// CanvasView

late int _viewID;
Widget? _viewWidget;

void start() {
  ZegoExpressEngine.instance.createCanvasView((viewID) {
    _viewID = viewID;
    // Call [startPreview] or [startPlayingStream]
    // ......
  }).then((widget) {
    setState(() {
      _viewWidget = widget;
    });
  });
}

void stop() {
  // Call [stopPreview] or [stopPlayingStream]
  // ......
  ZegoExpressEngine.instance.destroyCanvasView(_viewID);
}

// CanvasView

late int _viewID;
Widget? _viewWidget;

void start() {
  ZegoExpressEngine.instance.createCanvasView((viewID) {
    _viewID = viewID;
    // Call [startPreview] or [startPlayingStream]
    // ......
  }).then((widget) {
    setState(() {
      _viewWidget = widget;
    });
  });
}

void stop() {
  // Call [stopPreview] or [stopPlayingStream]
  // ......
  ZegoExpressEngine.instance.destroyCanvasView(_viewID);
}