# 在线音乐教学 API (/zh-CN/api-reference/online-music-teaching/cpp-all-platforms/api/fish-eye)

> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).

声网为在线音乐场景提供鱼眼镜头画面畸变矫正功能，本文提供相关的 API 参考。

除了在线音乐教学相关的 API，你还需要使用 RTC API 来实现实时音视频互动功能。你可以参考 [RTC API](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-api-overview) 文档来了解详细的 RTC API 用法。

:::info[信息]
鱼眼镜头畸变矫正与分离显示 API 仅存在于声网为在线音乐教学解决方案提供的声网 RTC 教育特殊版 SDK 中。声网官网的视频 SDK v4.x 版本尚不支持该功能。你可以[提交工单](https://ticket.shengwang.cn)联系我们获取声网 RTC 4.0.0 教育特殊版 SDK。
:::

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

- [RTM SDK](/zh-CN/api-reference/rtm/cpp/configuration)，实现实时消息相关功能
- [云端录制](/zh-CN/api-reference/api-ref/cloud-recording/acquire)，为实时音视频和互动白板提供录制功能

<a id="enablefishcorrection"></a>
## 方法 [#方法]
### enableFishCorrection [#enablefishcorrection]

```cpp
virtual int enableFishCorrection(bool enabled, const struct FishCorrectionParams &params) = 0;
```

开启或关闭鱼眼镜头画面畸变矫正。

#### 参数 [#参数]

| 参数 | 说明 |
| --- | --- |
| `enabled` | [fish-eye-windows-html-0-1-1 details](#table-slot-fish-eye-windows-html-0-1-1) |
| `params` | 畸变矫正参数。详见 [`FishCorrectionParams`](/zh-CN/api-reference/online-music-teaching/cpp-all-platforms/api/fish-eye#fishcorrectionparams)。 |

<a id="table-slot-fish-eye-windows-html-0-1-1"></a>

**fish-eye-windows-html-0-1-1 details**

是否开启鱼眼镜头画面矫正。

- `YES`：开启鱼眼镜头画面畸变矫正。
- `NO`：关闭鱼眼镜头画面畸变矫正。

#### 返回值 [#返回值]

- 0：方法调用成功。
- &lt; 0：方法调用失败。

<a id="enableVideoMultiRenderer"></a>
### enableVideoMultiRenderer [#enablevideomultirenderer]

```cpp
virtual int enableVideoMultiRenderer(bool enabled) = 0;
```

开启或关闭多渲染功能。

#### 参数 [#参数-1]

| 参数 | 说明 |
| --- | --- |
| `enabled` | [fish-eye-windows-html-1-1-1 details](#table-slot-fish-eye-windows-html-1-1-1) |

<a id="table-slot-fish-eye-windows-html-1-1-1"></a>

**fish-eye-windows-html-1-1-1 details**

是否开启多渲染功能。

- `true`：开启多渲染功能。
- `false`：关闭多渲染功能。

#### 返回值 [#返回值-1]

- 0：方法调用成功。
- &lt; 0：方法调用失败。

<a id="setuplocalvideo"></a>
### setupLocalVideo [#setuplocalvideo]

```cpp
virtual int setupLocalVideo(const VideoCanvas& canvas, VIDEO_VIEW_SETUP_MODE mode) = 0;
```

（多渲染功能）设置本地渲染画面。

#### 参数 [#参数-2]

| 参数 | 说明 |
| --- | --- |
| `canvas` | 视频渲染画布。详见 [`VideoCanvas`](/zh-CN/api-reference/rtc/cpp-all-platforms/class-videocanvas)。 |
| `mode` | 视频渲染模式。详见 [`VideoViewSetupMode`](/zh-CN/api-reference/online-music-teaching/cpp-all-platforms/api/fish-eye#video_view_setup_mode)。 |

#### 返回值 [#返回值-2]

- 0：方法调用成功。
- &lt; 0：方法调用失败。

<a id="setupRemoteVideo"></a>
### setupRemoteVideo [#setupremotevideo]

```cpp
virtual int setupRemoteVideo(const VideoCanvas& canvas, VIDEO_VIEW_SETUP_MODE mode) = 0;
```

（多渲染功能）设置远端渲染画面。

#### 参数 [#参数-3]

| 参数 | 说明 |
| --- | --- |
| `canvas` | 视频渲染画布。详见 [`VideoCanvas`](/zh-CN/api-reference/rtc/cpp-all-platforms/class-videocanvas)。 |
| `mode` | 视频渲染模式。详见 [`VideoViewSetupMode`](/zh-CN/api-reference/online-music-teaching/cpp-all-platforms/api/fish-eye#video_view_setup_mode)。 |

#### 返回值 [#返回值-3]

- 0：方法调用成功。
- &lt; 0：方法调用失败。

<a id="setupremotevideoex"></a>
### setupRemoteVideoEx [#setupremotevideoex]

```cpp
virtual int setupRemoteVideoEx(const VideoCanvas& canvas, VIDEO_VIEW_SETUP_MODE mode, const RtcConnection& connection) = 0;
```

（多频道场景）设置远端渲染画面。

#### 参数 [#参数-4]

| 参数 | 说明 |
| --- | --- |
| `remote` | 视频渲染画布。详见 [`VideoCanvas`](/zh-CN/api-reference/rtc/cpp-all-platforms/class-videocanvas)。 |
| `mode` | 视频渲染模式。详见 [`VideoViewSetupMode`](/zh-CN/api-reference/online-music-teaching/cpp-all-platforms/api/fish-eye#video_view_setup_mode)。 |
| `connection` | Connection 信息。详见 [`RtcConnection`](/zh-CN/api-reference/rtc/cpp-all-platforms/class-rtcconnection)。 |

#### 返回值 [#返回值-4]

- 0：方法调用成功。
- &lt; 0：方法调用失败。

<a id="fishcorrectionparams"></a>
## 数据类型 [#数据类型]
### FishCorrectionParams [#fishcorrectionparams]

```cpp
struct FishCorrectionParams {
  float _x_center;
  float _y_center;
  float _scale_factor;
  float _focal_length;
  float _pol_focal_length;
  float _split_height;
  float _ss[5];
  FishCorrectionParams():_x_center(0.49),
                         _y_center(0.48),
                         _scale_factor(4.5),
                         _focal_length(31),
                         _pol_focal_length(31),
                         _split_height(1.0) {
    _ss[0] = 0.9375;
    _ss[1] = 0.0;
    _ss[2] = -2.9440;
    _ss[3] = 5.7344;
    _ss[4] = -4.4564;
  }
  FishCorrectionParams(float x_center, float y_center, float scale_factor, float focal_length, float pol_focal_length, float split_height, float ss[])
  : _x_center(x_center),
    _y_center(y_center),
    _scale_factor(scale_factor),
    _focal_length(focal_length),
    _pol_focal_length(pol_focal_length),
    _split_height(split_height) {
    if (ss != OPTIONAL_NULLPTR) {
      for (int i = 0; i < 5; i++) {
        _ss[i] = ss[i];
      }
    }
  }
};
```

鱼眼镜头画面畸变校正参数。

#### 参数 [#参数-5]

| 参数 | 说明 |
| --- | --- |
| `_x_center` | 鱼眼图像处理的中心位置 X 坐标。取值范围 [0.4,0.6]。 |
| `_y_center` | 鱼眼图像处理的中心位置 Y 坐标。取值范围 [0.4,0.6]。 |
| `_scale_factor` | 鱼眼镜头成像的区域大小。取值范围 [1,5]。1 为镜头最内圈，5 为镜头最外圈。 |
| `_focal_length` | 镜头焦距。取值范围 [20,40]。 |
| `_pol_focal_length` | 标定鱼眼镜头的参数，通过镜头焦距计算。取值范围 [20,40]。 |
| `_split_height` | 鱼眼校正效果切分高度。取值范围 [0,1]。在切分线以上的画面有鱼眼校正效果，在切分线以下的画面无鱼眼校正效果。 |
| `ss` | 镜头的一组参数，通过多项式拟合得到。不同类型的鱼眼镜头会有不同的值。 |

<a id="videocroparea"></a>
### VideoCropArea [#videocroparea]

```cpp
struct VideoCropArea {

    int xPoint;

    int yPoint;

    int width;

    int height;
    VideoCropArea() : xPoint(0), yPoint(0), width(0), height(0) {}
    VideoCropArea(int x, int y, int w, int h) : xPoint(x), yPoint(y), width(w), height(h) {}
};
```

需要截取的视频画面区域。参数使用屏幕坐标系，原点在屏幕左上角(0, 0)。

#### 参数 [#参数-6]

| 参数 | 说明 |
| --- | --- |
| `xPoint` | 屏幕坐标系中图像左上角顶点的 X 坐标。单位为像素。 |
| `yPoint` | 屏幕坐标系中图像左上角顶点的 Y 坐标。单位为像素。 |
| `width` | 以图像左上角顶点为起始点，截取画面的宽度。单位为像素。 |
| `height` | 以图像左上角顶点为起始点，截取画面的高度。单位为像素。 |

图像的截取方式如下图所示：

![截图方式](https://web-cdn.agora.io/docs-files/1645160493405)

<a id="VIDEO_VIEW_SETUP_MODE"></a>
### VIDEO_VIEW_SETUP_MODE [#video_view_setup_mode]

- `VIDEO_VIEW_SETUP_ADD(1)`：添加指定视图。
- `VIDEO_VIEW_SETUP_REMOVE(2)`：删除指定视图。