简要描述：

初始化游戏显示View兼容模式，用于部分显示异常的设备。

语法

public void initVideoViewLegacy(SurfaceView view)

参数：

参数名	必选	类型	说明
view	是	SurfaceView	游戏显示view

返回值

WhaleCloud 兼容渲染模式接入说明

1. 适用范围

本文档面向接入 cloudgamelibrary 的第三方 Android 应用，说明 WhaleCloud 在兼容渲染模式下的正确使用方式。

WhaleCloud 是 cloudgamelibrary 对外提供的云游戏 SDK。SDK 会根据：

后端下发的 render_strategy.render_type

当前设备是否走硬解

设备机型兼容规则

自动决定当前会话使用：

默认渲染模式：JySurfaceView

兼容渲染模式：SurfaceView

外部应用不要自己判断机型或 render_type，统一以 WhaleCloud.getInstance().isLegcyView() 的结果为准。

注意：接口名 isLegcyView() 为 SDK 现有命名，拼写保持历史兼容。

2. 兼容模式的典型场景

兼容模式主要用于部分机型上 WebRTC 默认渲染链路不稳定，或者后端明确要求走兼容渲染时。

当 isLegcyView() 返回 true 时：

必须使用普通 SurfaceView

必须调用 initVideoViewLegacy(SurfaceView view)

不应再使用 initVideoView(JySurfaceView view)

建议在布局完成、start() 后、onGameBegin() 时同步调用 setGameRect(...)

3. 对外接口

3.1 `sdkLoading(...)`

作用：

初始化 SDK

拉取后端配置

解析本次会话的渲染策略

关键点：

isLegcyView() 依赖 sdkLoading 返回后的配置结果

因此不要在 sdkLoading 成功前决定使用哪个渲染 View

3.2 `isLegcyView()`

作用：

返回当前会话是否需要兼容渲染模式

推荐时机：

在 sdkLoading.onSdkSucc() 之后立即调用

3.3 `initVideoView(JySurfaceView view)`

默认渲染模式使用。

3.4 `initVideoViewLegacy(SurfaceView view)`

兼容渲染模式使用。

3.5 `setGameRect(int x, int y, int width, int height)`

作用：

同步游戏实际显示区域

为触摸、鼠标等输入映射提供正确的画面区域

兼容模式下建议在显示区域变化时持续同步

4. 推荐接入时序

推荐时序如下：

页面布局中同时准备 JySurfaceView 和 SurfaceView

调用 sdkLoading(...)

在 onSdkSucc() 中调用 isLegcyView()

根据结果二选一初始化渲染 View

调用 setDecodeType(...)（如果业务侧需要指定软解/硬解）

调用 start(...)

如果是兼容模式，在以下时机同步 setGameRect(...)

退出页面时调用 stopGame(...)

兼容模式下推荐同步 setGameRect(...) 的时机：

SurfaceView 或其父容器完成布局后

WhaleCloud.start(...) 调用后

JyGameStatusListener.onGameBegin() 中

横竖屏切换、窗口尺寸变化、画面区域变化后

5. 布局示例

建议在同一页面内同时保留两种渲染 View，运行时只显示其中一个。

<FrameLayout
    android:id="@+id/video_container"
    android:layout_width="match_parent"
    android:layout_height="match_parent">

    <com.zjrx.jyengine.JySurfaceView
        android:id="@+id/video_render"
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        android:visibility="gone" />

    <SurfaceView
        android:id="@+id/video_render_legacy"
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        android:visibility="gone" />

</FrameLayout>

6. 接入示例

下面示例展示推荐的最小接入方式。

如果页面布局会变化，建议额外监听渲染 View 的 OnLayoutChangeListener：

7. 常见错误

7.1 在 `sdkLoading()` 前调用 `isLegcyView()`

错误原因：

此时后端下发的 render_type 还没有写入 SDK 配置

后果：

可能误判为默认模式

兼容机型上会绑定错渲染 View

严重时可能表现为建联成功但黑屏

7.2 兼容模式下仍然调用 `initVideoView(JySurfaceView)`

错误原因：

当前会话要求使用 SurfaceView

后果：

视频流已连接，但画面无法正常显示

7.3 兼容模式下没有同步 `setGameRect(...)`

后果：

触摸、鼠标、相对坐标区域可能不准确

窗口变化后画面区域和输入区域可能不一致

7.4 同时初始化两套渲染 View

不推荐：

同一次会话只应初始化当前激活的那一套渲染 View

8. 建议的排查顺序

出现黑屏或兼容模式异常时，建议优先确认以下几点：

sdkLoading.onSdkSucc() 是否成功回调

isLegcyView() 返回值是否符合预期

legacy=true 时是否真的走了 initVideoViewLegacy(SurfaceView)

当前页面上是否只有一个激活渲染 View 可见

SurfaceView 是否已经完成布局并拿到有效宽高

setGameRect(...) 是否在布局完成后被调用

start(...) 是否在渲染 View 初始化之后调用

9. 推荐实践

将渲染模式选择逻辑统一收口到一个方法中，避免页面内多处判断

不要缓存旧会话的 isLegcyView() 结果，每次新会话都以本次 sdkLoading 结果为准

兼容模式优先使用全屏或确定尺寸的 SurfaceView

如果业务有悬浮层、提示层、遥控器层，确保它们不要错误替代渲染 View 本身

初始化-游戏画面设置（兼容模式）

WhaleCloud 兼容渲染模式接入说明#

1. 适用范围#

2. 兼容模式的典型场景#

3. 对外接口#

3.1 sdkLoading(...)#

3.2 isLegcyView()#

3.3 initVideoView(JySurfaceView view)#

3.4 initVideoViewLegacy(SurfaceView view)#

3.5 setGameRect(int x, int y, int width, int height)#

4. 推荐接入时序#

5. 布局示例#

6. 接入示例#

7. 常见错误#

7.1 在 sdkLoading() 前调用 isLegcyView()#

7.2 兼容模式下仍然调用 initVideoView(JySurfaceView)#

7.3 兼容模式下没有同步 setGameRect(...)#

7.4 同时初始化两套渲染 View#

8. 建议的排查顺序#

9. 推荐实践#