功能场景

用户在使用云手机时，如果需要正常体验部分横屏应用，需要将云机的画面做旋转。同时，部分应用受重力等传感器影响，需要支持当云机屏幕旋转时，画面旋转，如某些视频应用，在云机横屏时需要支持全屏播放。

功能介绍

Web

云手机 Web SDK 支持的屏幕旋转方法与状态如下：

当 start.rotation 参数设置为 portrait

当 start.rotation 参数为空

Android

当云手机画面以横屏显示时，为确保在本地设备上正常显示，可能需要对拉流画面进行旋转。云手机 SDK 提供了画面旋转功能，以适配横屏应用的显示需求，确保用户获得良好的观看体验。

外部旋转

外部旋转模式中，画面旋转的控制权交由应用层管理。开发者需根据云手机实例的画面方向变化，自主调整本地 Activity 的方向及画面旋转。此模式具备较强的灵活性，允许开发者依据特定的应用需求定制画面旋转逻辑。

操作指引：

1. 在调用 start 接口拉取云手机画面前，配置 PhonePlayConfig 时，使用videoRotationMode参数的默认设置 External，以启用外部旋转模式。

2. 注册 IStreamListener.onRotation 回调监听并处理云手机画面的横竖屏状态。当云手机画面方向和本地 Activity 方向不一致时，首先旋转 Activity 方向以保持本地设备屏幕与云手机屏幕方向一致，然后在 Activity 的 onConfigurationChanged 回调中使用 rotate 方法来旋转画面。

示例代码：

// 旋转 Activity
@Override
public void onRotation(@NonNull RotationState state) {
    switch (state.rotation) {
        case 0:
        case 180:
            activity.setRequestedOrientation(SCREEN_ORIENTATION_SENSOR_PORTRAIT);
            break;
        case 90:
        case 270:
            activity.setRequestedOrientation(SCREEN_ORIENTATION_SENSOR_LANDSCAPE);
            break;
    }
    VePhoneEngine.getInstance().rotate(Rotation.from(state.rotation).orientation);
}

// 旋转画面
public class PhoneActivity {

    @Override
    public void onConfigurationChanged(@NonNull Configuration newConfig) {
        VePhoneEngine.getInstance().rotate(newConfig.orientation);
    }

}

内部旋转

内部旋转模式中，画面的旋转交由 SDK 内部处理，无需额外操作。当云手机实例显示为横屏时，SDK 将自动调整画面方向并进行渲染，确保画面在本地设备上正确显示。

操作指引：

1. 在调用 start 接口拉取云手机画面前，配置 PhonePlayConfig 时，将videoRotationMode参数设置为INTERNAL以启用 SDK 内部旋转模式。

2. 注册 IStreamListener.onRotation 回调，并在回调逻辑中加入对 videoRotationMode 的判断。若 videoRotationMode 为 internal 时，则忽略回调事件，不执行任何操作。

示例代码：

@Override
public void onRotation(@NonNull RotationState state) {
    if(VePhoneEngine.getInstance().getVideoRenderModeManager().getVideoRotationMode() == VideoRotationMode.INTERNAL) {
        return
    }
}

iOS

SDK 只负责横竖屏方向回调，不负责横竖屏的旋转，业务接入时需根据 changedDeviceRotation 回调自行处理。

相关API

Web

详细信息，参考 接口说明。

//设置屏幕 UI 方向旋转
vePhone.rotateScreen(90,true);

//画面旋转（当云机实例画面方向发生变化时，需要配合调用该方法进行坐标旋转）
vePhone.rotate(90);

//坐标旋转（当使用 CSS transform 的 rotate/rotate3d 进行 UI 旋转操作时，需要配合调用该方法进行坐标旋转）
vePhone.rotateCoordinate(90);

//回调监听（各旋转角度对应的返回值，用于客户监听当前画面状态）
vePhone.on('on-screen-ratation', data=>{
    console.log(data);
})

//是否锁定屏幕横竖屏显示（即是否默认开启自动旋转功能，移动端时监听 orientation 进行画面旋转）
start.isScreenLock

Android

详细信息，参考 接口说明。

//旋转画面方向
void rotate(int orientation)

//客户端旋转回调
public interface IStreamListener {
    void onRotation(@NonNull RotationState state);
}

iOS

详细信息，参考 接口说明。

/// 云机“旋转”回调
/// - Parameters:
///   - manager: VePhoneManager 对象
///   - rotation: 旋转度
- (void)phoneManager:(VePhoneManager *)manager changedDeviceRotation:(NSInteger)rotation;

完整示例代码

Web

https://github.com/volcengine/vePhone/blob/main/Quick%20Start/Web/src/features/rotation.js

Android

https://github.com/volcengine/vePhone/blob/main/Quick%20Start/Android/app/src/main/java/com/example/sdkdemo/feature/RotationModeActivity.java

iOS

https://github.com/volcengine/vePhone/tree/main/Quick%20Start/iOS