v2.23.0_upgrade_guide.md

v2.23.0 Upgrade Guide

This article details the instructions and precautions for upgrading the Express Flutter SDK version to v2.23.0.

Changes

In order to facilitate developers to implement the video rendering feature, the ZegoExpressTextureRenderUtils|_blank and ZegoExpressPlatformViewUtils|_blank API modules have been removed since v2.23.0.

Therefore, when upgrading from an old version to v2.23.0, developers need to migrate to the new ZegoExpressCanvasViewUtils|_blank API module to implement the video rendering feature.

The new ZegoExpressCanvasViewUtils|_blank API module can support both External Texture|_blank and PlatformView|_blank rendering methods.

Reason

Express Flutter SDK supports two rendering methods: External Texture|_blank and PlatformView|_blank

Before v2.22.0, the two rendering methods correspond to two sets of APIs. Since Flutter only supports one of the rendering methods on some platforms, developers need to determine which set of APIs the corresponding platform can use.

• External Texture：ZegoExpressTextureRenderUtils|_blank
  • createTextureRenderer|_blank
  • destroyTextureRenderer|_blank
  • updateTextureRendererSize|_blank
• PlatformView：ZegoExpressPlatformViewUtils|_blank
  • createPlatformView|_blank
  • destroyPlatformView|_blank

In order to reduce the cost of use for developers, a new set of API was launched in the v2.22.0 version:

• ZegoExpressCanvasViewUtils|_blank
  • createCanvasView|_blank
  • destroyCanvasView|_blank

This set of APIs removes the difference in the use of the previous two rendering methods, and can support both External Texture|_blank and PlatformView|_blank rendering methods.

• For platforms that support both rendering methods, whether to use PlatformView|_blank or External Texture|_blank will be determined according to the enablePlatformView|_blank parameter when calling createEngineWithProfile|_blank.

• For platforms that only support one of the rendering methods, the only supported rendering method will be used automatically, and the enablePlatformView|_blank parameter will be ignored, that is, the behavior mode of the enablePlatformView|_blank parameter is preference instead of specify.

The v2.23.0 SDK supports macOS and Windows. The rendering methods and platforms supported by the current version are as follows:

Methods\Platforms	Android	iOS	macOS	Windows	Web	Linux
External Texture	✔️	✔️	✔️	✔️	✖	✖
PlatformView	✔️	✔️	✖	✖	✔️	✖

In order to support CanvasView, we refactored the implementation of video rendering function, which improves the performance, but also destroys the original ZegoExpressTextureRenderUtils behavior (view mode abnormal).

For user experience, we decided to delete the ZegoExpressTextureRenderUtils|_blank and ZegoExpressPlatformViewUtils|_blank API modules.

Developers need to migrate to the new ZegoExpressCanvasViewUtils|_blank API module, the specific API changes are as follows:

OLD	NEW
createTextureRenderer	createCanvasView
destroyTextureRenderer	destroyCanvasView
updateTextureRendererSize	No need to call it anymore, the SDK will handle it automatically.
createPlatformView	createCanvasView
destroyPlatformView	destroyCanvasView

Sample

You can refer to the following sample code or the example demo|_blank for migration.

v2.22.0 and earlier

• External 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);
    // Do something like calling [startPreview] or [startPlayingStream]
    // ......
  });
}

void stop() {
  // Do something like calling [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);
      // Do something like calling [startPreview] or [startPlayingStream]
      // ......
    });
  });
}

void stop() {
  // Do something like calling [stopPreview] or [stopPlayingStream]
  // ......
  ZegoExpressEngine.instance.destroyPlatformView(_viewID);
}

v2.23.0

// CanvasView

late int _viewID;
Widget? _viewWidget;

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

void stop() {
  // Do something like calling [stopPreview] or [stopPlayingStream]
  // ......
  ZegoExpressEngine.instance.destroyCanvasView(_viewID);
}