2024/07/29 16:18:40

在线美术教学 API

声网为在线美术场景提供明暗校正和透视校正功能，本文提供相关的 API 参考。

除了在线美术教学相关的 API，你还需要使用 RTC API 来实现实时音视频互动功能。你可以参考 RTC API 文档来了解详细的 RTC API 用法。

信息

明暗校正和透视校正 API 仅存在于声网为在线美术教学解决方案提供的声网 RTC 教育特殊版 SDK 中。声网官网的视频 SDK v4.x 版本尚不支持该功能。你可以提交工单联系我们获取声网 RTC 4.0.0 教育特殊版 SDK。

此外，你还可以参考如下 API 文档，在场景实现中添加相应的功能：

RTM SDK，实现实时消息相关功能
云端录制，为实时音视频和互动白板提供录制功能

明暗校正

enableBrightnessCorrection

C++
virtual int enableBrightnessCorrection(bool enabled, BRIGHTNESS_CORRECTION_MODE mode, VIDEO_SOURCE_TYPE sourceType = VIDEO_SOURCE_CAMERA_PRIMARY) = 0;

开启或关闭本地画面明暗校正。

参数

参数说明

参数	说明
`enabled`	是否开启本地画面明暗校正： `true`：开启。 `false`：不开启。
`mode`	明暗校正模式： `AUTO_MODE(0)`：自动模式，SDK 自动检测亮度，如果检测当前亮度正常，不会启动亮度校正。 `MANUAL_MODE(1)`：手动模式，SDK 启动亮度校正。
`sourceType`	视频源类型： `VIDEO_SOURCE_CAMERA_PRIMARY(0)`：（默认）在第一个摄像头开启或关闭明暗校正。 `VIDEO_SOURCE_CAMERA_SECONDARY(1)`：在第二个摄像头开启或关闭明暗校正。

enabled

是否开启本地画面明暗校正：

true：开启。
false：不开启。

mode

明暗校正模式：

AUTO_MODE(0)：自动模式，SDK 自动检测亮度，如果检测当前亮度正常，不会启动亮度校正。
MANUAL_MODE(1)：手动模式，SDK 启动亮度校正。

sourceType

视频源类型：

VIDEO_SOURCE_CAMERA_PRIMARY(0)：（默认）在第一个摄像头开启或关闭明暗校正。
VIDEO_SOURCE_CAMERA_SECONDARY(1)：在第二个摄像头开启或关闭明暗校正。

返回值

0：方法调用成功。
< 0：方法调用失败。

applyBrightnessCorrectionToRemote

C++
virtual int applyBrightnessCorrectionToRemote(uid_t uid, bool enabled, BRIGHTNESS_CORRECTION_MODE mode) = 0;

开启远端远端用户画面的明暗校正。远端的用户需要在 enableVideo 前先调用 addExtension 和 enableExtension才能成功接收远程开启明暗校正请求。

参数

参数说明

uid 需要开启明暗校正的远端用户 ID。

enabled

是否开启远端用户画面明暗校正：

true：开启
false：不开启

mode

明暗校正模式：

AUTO_MODE(0)：自动模式，SDK 自动检测亮度，如果检测当前亮度正常，不会启动亮度校正。
MANUAL_MODE(1)：手动模式，SDK 启动亮度校正。

返回值

0：方法调用成功。
< 0：方法调用失败。

applyBrightnessCorrectionToRemoteEx

C++
virtual int applyBrightnessCorrectionToRemoteEx(uid_t uid, bool enabled, BRIGHTNESS_CORRECTION_MODE mode, const RtcConnection& connection) = 0;

（适用于多频道）开启对应 Connection 的远端用户画面的明暗校正。远端的用户需要在 enableVideo 前先调用 addExtension 和 enableExtension 才能成功接收远程开启明暗校正请求。

参数

参数	说明
`uid`	需要开启明暗校正的远端用户 ID。
`enabled`	是否开启远端用户画面明暗校正： `true`：开启 `false`：不开启
`mode`	明暗校正模式： `AUTO_MODE(0)`：自动模式，SDK 自动检测亮度，如果检测当前亮度正常，不会启动亮度校正。 `MANUAL_MODE(1)`：手动模式，SDK 启动亮度校正。
`connection`	Connection 信息。详见 `RtcConnection`。

返回值

0：方法调用成功。
< 0：方法调用失败。

透视校正

enableRemoteTrapezoidCorrection

C++
virtual int enableRemoteTrapezoidCorrection(uid_t uid, bool enabled) = 0;

在本地启用或关闭远端用户在本地渲染画面的透视校正。远端用户自身的本地预览不会看到透视校正效果。

参数

参数说明

uid 需要开启明暗校正的远端用户 ID。

enabled

是否开启远端画面透视校正：

true：开启
false：不开启

返回值

0：方法调用成功。
< 0：方法调用失败。

enableRemoteTrapezoidCorrectionEx

C++
virtual int enableRemoteTrapezoidCorrectionEx(uid_t uid, bool enabled, const RtcConnection& connection) = 0;

（适用于多频道）在本地启用或关闭远端用户在本地渲染画面的透视校正。远端用户自身的本地预览不会看到透视校正效果。

参数

参数说明

uid 需要开启明暗校正的远端用户 ID。

enabled

是否开启远端画面透视校正：

true：开启
false：不开启

connection Connection 信息。详见 RtcConnection。

返回值

0：方法调用成功。
< 0：方法调用失败。

enableLocalTrapezoidCorrection

C++
virtual int enableLocalTrapezoidCorrection(bool enabled, VIDEO_SOURCE_TYPE sourceType = VIDEO_SOURCE_CAMERA_PRIMARY) = 0;

开启或关闭本地画面的透视校正。本地设置透视校正后，远端就能看到梯形校正后的画面。

参数

参数说明

参数	说明
`enabled`	是否开启本地画面透视校正： `true`：开启。 `false`：不开启。
`sourceType`	视频源类型： `VIDEO_SOURCE_CAMERA_PRIMARY(0)`：（默认）在第一个摄像头开启或关闭透视校正。 `VIDEO_SOURCE_CAMERA_SECONDARY(1)`：在第二个摄像头开启或关闭透视校正。

enabled

是否开启本地画面透视校正：

true：开启。
false：不开启。

sourceType

视频源类型：

VIDEO_SOURCE_CAMERA_PRIMARY(0)：（默认）在第一个摄像头开启或关闭透视校正。
VIDEO_SOURCE_CAMERA_SECONDARY(1)：在第二个摄像头开启或关闭透视校正。

返回值

0：方法调用成功。
< 0：方法调用失败。

setLocalTrapezoidCorrectionOptions

C++
virtual int setLocalTrapezoidCorrectionOptions(const TrapezoidCorrectionOptions& options, VIDEO_SOURCE_TYPE sourceType = VIDEO_SOURCE_CAMERA_PRIMARY) = 0;

配置本地透视校正选项。

参数

参数说明

options 透视校正配置参数。详见 TrapezoidCorrectionOptions。

参数	说明
`options`	透视校正配置参数。详见 `TrapezoidCorrectionOptions`。
`sourceType`	视频源类型： `VIDEO_SOURCE_CAMERA_PRIMARY(0)`：（默认）在第一个摄像头开启或关闭透视校正。 `VIDEO_SOURCE_CAMERA_SECONDARY(1)`：在第二个摄像头开启或关闭透视校正。

sourceType

视频源类型：

VIDEO_SOURCE_CAMERA_PRIMARY(0)：（默认）在第一个摄像头开启或关闭透视校正。
VIDEO_SOURCE_CAMERA_SECONDARY(1)：在第二个摄像头开启或关闭透视校正。

返回值

0：方法调用成功。
< 0：方法调用失败。

getLocalTrapezoidCorrectionOptions

C++
virtual int getLocalTrapezoidCorrectionOptions(TrapezoidCorrectionOptions& options, VIDEO_SOURCE_TYPE sourceType = VIDEO_SOURCE_CAMERA_PRIMARY) = 0;

获取本地透视校正配置参数。

参数

参数说明

options [in/out] 透视校正配置参数。详见 TrapezoidCorrectionOptions。对于输出参数而言，如果之前多次设置过透视校正参数，则获取的是之前多次设置的参数集合。

参数	说明
`options`	[in/out] 透视校正配置参数。详见 `TrapezoidCorrectionOptions`。对于输出参数而言，如果之前多次设置过透视校正参数，则获取的是之前多次设置的参数集合。
`sourceType`	视频源类型： `VIDEO_SOURCE_CAMERA_PRIMARY(0)`：（默认）在第一个摄像头开启或关闭透视校正。 `VIDEO_SOURCE_CAMERA_SECONDARY(1)`：在第二个摄像头开启或关闭透视校正。

sourceType

视频源类型：

VIDEO_SOURCE_CAMERA_PRIMARY(0)：（默认）在第一个摄像头开启或关闭透视校正。
VIDEO_SOURCE_CAMERA_SECONDARY(1)：在第二个摄像头开启或关闭透视校正。

返回值

0：方法调用成功。
< 0：方法调用失败。

setRemoteTrapezoidCorrectionOptions

C++
virtual int setRemoteTrapezoidCorrectionOptions(uid_t uid, const TrapezoidCorrectionOptions& options) = 0;

配置远端透视校正选项。

参数

参数	说明
`uid`	远端用户 ID。
`options`	透视校正配置参数。详见 `TrapezoidCorrectionOptions`。

返回值

0：方法调用成功。
< 0：方法调用失败。

setRemoteTrapezoidCorrectionOptionsEx

C++
virtual int setRemoteTrapezoidCorrectionOptionsEx(uid_t uid, const TrapezoidCorrectionOptions& options, const RtcConnection& connection) = 0;

（适用于多频道）配置远端透视校正选项。

参数

参数	说明
`uid`	远端用户 ID。
`options`	透视校正配置参数。详见 `TrapezoidCorrectionOptions`。
`connection`	Connection 信息。详见 `RtcConnection`。

返回值

0：方法调用成功。
< 0：方法调用失败。

getRemoteTrapezoidCorrectionOptions

C++
virtual int getRemoteTrapezoidCorrectionOptions(uid_t uid, TrapezoidCorrectionOptions& options) = 0;

获取远端透视校正配置参数。

参数

参数	说明
`uid`	远端用户 ID。
`options`	[in/out] 透视校正配置参数。详见 `TrapezoidCorrectionOptions`。对于输出参数而言，如果之前多次设置过透视校正参数，则获取的是之前多次设置的参数集合。

返回值

0：方法调用成功。
< 0：方法调用失败。

getRemoteTrapezoidCorrectionOptionsEx

C++
virtual int getRemoteTrapezoidCorrectionOptionsEx(uid_t uid, TrapezoidCorrectionOptions& options, const RtcConnection& connection) = 0;

（适用于多频道）获取远端透视校正配置参数。

参数

参数	说明
`uid`	远端用户 ID。
`options`	[in/out] 透视校正配置参数。详见 `TrapezoidCorrectionOptions`。对于输出参数而言，如果之前多次设置过透视校正参数，则获取的是之前多次设置的参数集合。
`connection`	Connection 信息。详见 `RtcConnection`。

返回值

0：方法调用成功。
< 0：方法调用失败。

applyTrapezoidCorrectionToRemote

C++
virtual int applyTrapezoidCorrectionToRemote(uid_t uid, bool enabled) = 0;

将透视校正参数应用到远端用户在本地的预览画面。

参数

参数说明

uid 远端用户 ID。

enabled

是否将透视校正参数应用到远端用户在本地的预览画面：

true：应用。
false：不应用。

返回值

0：方法调用成功。
< 0：方法调用失败。

applyTrapezoidCorrectionToRemoteEx

C++
virtual int applyTrapezoidCorrectionToRemoteEx(uid_t uid, bool enabled, const RtcConnection& connection) = 0;

（适用于多频道）将透视校正参数应用到远端用户在本地的预览画面。

参数

参数说明

uid 远端用户 ID。

enabled

是否将透视校正参数应用到远端用户在本地的预览画面：

true：应用。
false：不应用。

connection Connection 信息。详见 RtcConnection。

返回值

0：方法调用成功。
< 0：方法调用失败。

onTrapezoidAutoCorrectionFinished

C++
virtual void onTrapezoidAutoCorrectionFinished(uid_t uid, TrapezoidAutoCorrectionResult result, int costTime,
      const TrapezoidCorrectionOptions::Point* dragSrcPoints, int dragSrcPointsLen,
      const TrapezoidCorrectionOptions::Point* dragDstPoints, int dragDstPointsLen) {
    (void)uid;
    (void)result;
    (void)costTime;
    (void)dragSrcPoints;
    (void)dragSrcPointsLen;
    (void)dragDstPoints;
    (void)dragDstPointsLen;
  }

自动透视校正完成时触发。

参数

参数	说明
`uid`	开启自动透视校正的远端用户 ID。
`result`	自动透视校正结果： `RESULT_OK(0)`：成功。 `RESULT_FAILED(-1)`：失败。
`costTime`	透视校正花费的时间 (ms)。
`dragSrcPoints`	拖动起始点时的梯形四个顶点坐标。
`dragSrcPointsLen`	`dragSrcPoints` 数组长度。
`dragDstPoints`	拖动结束点时的梯形四个顶点坐标。
`dragDstPointsLen`	`dragDstPoints` 数组长度。

onTrapezoidAutoCorrectionFinished（多频道）

C++
virtual void onTrapezoidAutoCorrectionFinished(const RtcConnection& connection, uid_t uid,
      TrapezoidAutoCorrectionResult result, int costTime,
      const TrapezoidCorrectionOptions::Point* dragSrcPoints, int dragSrcPointsLen,
      const TrapezoidCorrectionOptions::Point* dragDstPoints, int dragDstPointsLen) {
    (void)connection;
    (void)uid;
    (void)result;
    (void)costTime;
    (void)dragSrcPoints;
    (void)dragSrcPointsLen;
    (void)dragDstPoints;
    (void)dragDstPointsLen;
  }

自动透视校正完成时触发。

参数

参数	说明
`uid`	开启自动透视校正的远端用户 ID。
`result`	自动透视校正结果： `RESULT_OK(0)`：成功。 `RESULT_FAILED(-1)`：失败。
`costTime`	透视校正花费的时间 (ms)。
`dragSrcPoints`	拖动起始点时的梯形四个顶点坐标。
`dragSrcPointsLen`	`dragSrcPoints` 数组长度。
`dragDstPoints`	拖动结束点时的梯形四个顶点坐标。
`dragDstPointsLen`	`dragDstPoints` 数组长度。
`connection`	Connection 信息。详见 `RtcConnection`。

数据类型

TrapezoidCorrectionOptions

C++
struct TrapezoidCorrectionOptions {
  enum {
      POINT_ARRAY_LEN = 8,
  };
  struct Point {
    float x;    // value in [0.0 - 1.0]
    float y;    // value in [0.0 - 1.0]
  };


  TrapezoidCorrectionOptions():hasMultiPoints(false){}

  void setDragSrcPoint(Point pt)
  {
    dragSrcPoint = pt;
  }

  void setDragDstPoint(Point pt)
  {
    dragDstPoint = pt;
  }

  void setDragFinished(int finished)
  {
    dragFinished = finished;
  }

  void setDragSrcPoints(Point topLeft, Point bottomLeft, Point topRight, Point bottomRight)
  {
    dragSrcPoints[0] = topLeft.x;
    dragSrcPoints[1] = topLeft.y;
    dragSrcPoints[2] = bottomLeft.x;
    dragSrcPoints[3] = bottomLeft.y;
    dragSrcPoints[4] = topRight.x;
    dragSrcPoints[5] = topRight.y;
    dragSrcPoints[6] = bottomRight.x;
    dragSrcPoints[7] = bottomRight.y;
    hasMultiPoints = true;
  }

  void setDragDstPoints(Point topLeft, Point bottomLeft, Point topRight, Point bottomRight)
  {
    dragDstPoints[0] = topLeft.x;
    dragDstPoints[1] = topLeft.y;
    dragDstPoints[2] = bottomLeft.x;
    dragDstPoints[3] = bottomLeft.y;
    dragDstPoints[4] = topRight.x;
    dragDstPoints[5] = topRight.y;
    dragDstPoints[6] = bottomRight.x;
    dragDstPoints[7] = bottomRight.y;
    hasMultiPoints = true;
  }

  void showAssistLine(int show)
  {
    assistLine = show;
  }

  void setAutoCorrect(int autoCorr)
  {
    autoCorrect = autoCorr;
  }

  void setMirror(int mirr)
  {
    mirror = mirr;
  }

  void setResetDragPoints(int reset)
  {
    resetDragPoints = reset;
  }

  Optional<Point> dragSrcPoint;
  Optional<Point> dragDstPoint;
  Optional<int> dragFinished;       //value: 0 or 1
  float dragSrcPoints[POINT_ARRAY_LEN];
  float dragDstPoints[POINT_ARRAY_LEN];
  bool hasMultiPoints; // if true, indicates dragSrcPoints and dragDstPoints have valid values
  Optional<int> assistLine;         //value: 0 or 1
  Optional<int> autoCorrect;        //value: 0 or 1
  Optional<int> mirror;             //value: 0 or 1, only set if not use sdk renderer, such as custom renderer
  Optional<int> resetDragPoints;    //value: 0 or 1
};

透视校正参数配置，包含以下成员：

Point

x：x 坐标，根据屏幕宽度归一化为 [0.0~1.0] 的浮点数。
y：y 坐标，根据屏幕高度归一化为 [0.0~1.0] 的浮点数。

setDragSrcPoint

设置拖动起始点坐标。

参数	说明
`pt`	拖动起始点坐标。详见 `Point`。

setDragDstPoint

设置拖动终止点坐标。

如果同时调用 setDragSrcPoint、setDragDstPoint、setDragFinished 和 setDragSrcPoints、setDragDstPoints，则 setDragSrcPoints、setDragDstPoints 的设置生效。

参数	说明
`pt`	拖动终止点坐标。详见 `Point`。

setDragFinished

设置该次拖动调整是否结束。

参数说明

参数	说明
`finished`	本次拖动调整是否结束： `0`：未结束。 `1`：已结束。

finished

本次拖动调整是否结束：

0：未结束。
1：已结束。

setDragSrcPoints

同时设置 4 个点的拖动起始点坐标。

参数	说明
`topLeft`	左上角拖动起始点坐标。详见 `Point`。
`bottomLeft`	左下角拖动起始点坐标。详见 `Point`。
`topRight`	右上角拖动起始点坐标。详见 `Point`。
`bottomRight`	右下角拖动起始点坐标。详见 `Point`。

setDragDstPoints

同时设置 4 个点的拖动终止点坐标。

参数	说明
`topLeft`	左上角拖动终止点坐标。详见 `Point`。
`bottomLeft`	左下角拖动终止点坐标。详见 `Point`。
`topRight`	右上角拖动终止点坐标。详见 `Point`。
`bottomRight`	右下角拖动终止点坐标。详见 `Point`。

showAssistLine

开启或关闭辅助线。初始值为关闭。

参数说明

参数	说明
`show`	开启或关闭辅助线： `0`：关闭。 `1`：开启。

show

开启或关闭辅助线：

0：关闭。
1：开启。

setAutoCorrect

开启或关闭自动透视校正。初始值为关闭。

参数说明

参数	说明
`autoCorr`	开启或关闭自动透视校正： `0`：关闭。关闭之后，你需要手动设置拖动点坐标。 `1`：开启。开启之后，SDK 会自动进行透视校正。你无法手动设置拖动点坐标。

autoCorr

开启或关闭自动透视校正：

0：关闭。关闭之后，你需要手动设置拖动点坐标。
1：开启。开启之后，SDK 会自动进行透视校正。你无法手动设置拖动点坐标。

setMirror

启用或关闭镜像。初始值为关闭。

只有使用自定义渲染功能并且自定义渲染开启水平镜像时，才需要启用镜像参数。

参数说明

参数	说明
`mirr`	开启或关闭镜像： `0`：关闭。 `1`：开启。设置输入的点坐标与实际输入图像是水平镜像。

mirr

开启或关闭镜像：

0：关闭。
1：开启。设置输入的点坐标与实际输入图像是水平镜像。

setResetDragPoints

重置透视校正效果。初始值为不重置。

参数说明

参数	说明
`reset`	是否重置透视校正效果： `0`：不重置透视校正效果。 `1`：重置透视校正效果。重置后，画面恢复为校正前的效果。

reset

是否重置透视校正效果：

0：不重置透视校正效果。
1：重置透视校正效果。重置后，画面恢复为校正前的效果。

明暗校正​

enableBrightnessCorrection​

参数​

返回值​

applyBrightnessCorrectionToRemote​

参数​

返回值​

applyBrightnessCorrectionToRemoteEx​

参数​

返回值​

透视校正​

enableRemoteTrapezoidCorrection​

参数​

返回值​

enableRemoteTrapezoidCorrectionEx​

参数​

返回值​

enableLocalTrapezoidCorrection​

参数​

返回值​

setLocalTrapezoidCorrectionOptions​

参数​

返回值​

getLocalTrapezoidCorrectionOptions​

参数​

返回值​

setRemoteTrapezoidCorrectionOptions​

参数​

返回值​

setRemoteTrapezoidCorrectionOptionsEx​

参数​

返回值​

getRemoteTrapezoidCorrectionOptions​

参数​

返回值​

getRemoteTrapezoidCorrectionOptionsEx​

参数​

返回值​

applyTrapezoidCorrectionToRemote​

参数​

返回值​

applyTrapezoidCorrectionToRemoteEx​

参数​

返回值​

onTrapezoidAutoCorrectionFinished​

参数​

onTrapezoidAutoCorrectionFinished（多频道）​

参数​

数据类型​

TrapezoidCorrectionOptions​

Point​

setDragSrcPoint​

setDragDstPoint​

setDragFinished​

setDragSrcPoints​

setDragDstPoints​

showAssistLine​

setAutoCorrect​

setMirror​

setResetDragPoints​

明暗校正

enableBrightnessCorrection

参数

返回值

applyBrightnessCorrectionToRemote

参数

返回值

applyBrightnessCorrectionToRemoteEx

参数

返回值

透视校正

enableRemoteTrapezoidCorrection

参数

返回值

enableRemoteTrapezoidCorrectionEx

参数

返回值

enableLocalTrapezoidCorrection

参数

返回值

setLocalTrapezoidCorrectionOptions

参数

返回值

getLocalTrapezoidCorrectionOptions

参数

返回值

setRemoteTrapezoidCorrectionOptions

参数

返回值

setRemoteTrapezoidCorrectionOptionsEx

参数

返回值

getRemoteTrapezoidCorrectionOptions

参数

返回值

getRemoteTrapezoidCorrectionOptionsEx

参数

返回值

applyTrapezoidCorrectionToRemote

参数

返回值

applyTrapezoidCorrectionToRemoteEx

参数

返回值

onTrapezoidAutoCorrectionFinished

参数

onTrapezoidAutoCorrectionFinished（多频道）

参数

数据类型

TrapezoidCorrectionOptions

Point

setDragSrcPoint

setDragDstPoint

setDragFinished

setDragSrcPoints

setDragDstPoints

showAssistLine

setAutoCorrect

setMirror

setResetDragPoints