# Phytium-PhyRenderDoc

**Repository Path**: phytium_embedded/phytium-phyrenderdoc

## Basic Information

- **Project Name**: Phytium-PhyRenderDoc
- **Description**: PhyRenderDoc 是基于 RenderDoc 开源框架面向 Phytium 平台深度定制的 GPU 图形调试工具。本工具集成了帧捕获、着色器调试、像素历史追溯和管线状态分析等核心功能，支持开发人员在 OpenHarmony（OHOS）设备上通过 EGLHook 劫持截取 GPU 应用，能够有效简化图形应用开发调试流程、提升渲染问题定位效率、加速 GPU 应用的开发验证。
- **Primary Language**: 其他
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 1
- **Created**: 2026-09-23
- **Last Updated**: 2026-09-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# PhyRenderDoc 用户手册 v1.0.0
<center class ='img'>
<img src="./pic/logo.svg" width = 200 height = 200>

<font size=6 face="正方兰亭">PhyRenderDoc</font>
</center>

## 目录

- [1 PhyRenderDoc 介绍](#1-phyrenderdoc-介绍)
  - [1.1 概述](#11-概述)
  - [1.2 PhyRender 集成运行环境](#12-phyrender-集成运行环境)
- [2 快速开始](#2-快速开始)
  - [2.1 下载 PhyRenderDoc 安装包](#21-下载-phyrenderdoc-安装包)
  - [2.2 安装/卸载 PhyRenderDoc](#22-安装卸载-phyrenderdoc)
  - [2.3 如何启动 PhyRenderDoc](#23-如何启动-phyrenderdoc)
  - [2.4 工作主界面介绍](#24-工作主界面介绍)
  - [2.5 PhyRenderDoc 连接 OpenHarmony 设备](#25-phyrenderdoc-连接-openharmony-设备)
  - [2.6 OpenHarmony 真机设备截帧](#26-openharmony-真机设备截帧)
  - [2.7 本地保存截帧](#27-本地保存截帧)
  - [2.8 回放实时截帧](#28-回放实时截帧)
  - [2.9 加载保存本地截帧](#29-加载保存本地截帧)
  - [2.10 OpenHarmony 设备回放截取帧](#210-openharmony-设备回放截取帧)
  - [2.11 开发技巧](#211-开发技巧)

---

## 1 PhyRenderDoc 介绍

### 1.1 概述

- PhyRenderDoc 是基于 RenderDoc 开源框架面向 Phytium 平台深度定制的 GPU 图形调试工具。本工具集成了帧捕获、着色器调试、像素历史追溯和管线状态分析等核心功能，支持开发人员在 OpenHarmony（OHOS）设备上通过 EGLHook 劫持截取 GPU 应用，能够有效简化图形应用开发调试流程、提升渲染问题定位效率、加速 GPU 应用的开发验证。
- PhyRenderDoc 目前支持平台：OpenHarmony（OHOS）设备 + Linux x64 宿主机（qrenderdoc GUI）
- 支持 Ubuntu 20.04/22.04/24.04 等多个发行版本

### 1.2 PhyRender 集成运行环境

- RenderDoc 1.44 — 开源 GPU 调试分析工具，OHOS 适配修改
- Clang 15.0.4 (aarch64-linux-ohosmusl) — OHOS SDK 预置交叉编译链
- OpenHarmony SDK — 提供 graphic_2d、window_manager、hilog 等系统库与头文件
- Qt 5.15.2 — 静态构建，提供图形化调试界面
- Python 3.6+ — 平台支持 + Python 绑定
- SWIG 3.0.12 (RenderDoc 修改版) — 自动生成 Python/C++ 接口绑定
- 内置第三方库 — glslang 16.2.0、lz4 1.9.2、zstd 1.3.5、pugixml 1.9、Scintilla 3.7.2、Catch2

---

## 2 快速开始

### 2.1 下载 PhyRenderDoc 安装包

- 从官方途径下载 PhyRenderDoc 安装包 `phyrenderdoc_1.0_amd64.deb`

### 2.2 安装/卸载 PhyRenderDoc

- **安装 PhyRenderDoc** 通过 `dpkg` 命令方式安装，安装命令和过程如下：

```bash
sudo dpkg -i phyrenderdoc_1.0_amd64.deb
Selecting previously unselected package phyrenderdoc.
(Reading database ... 336687 files and directories currently installed.)
Preparing to unpack phyrenderdoc_1.0_amd64.deb ...
Unpacking phyrenderdoc (1.0) ...
Setting up phyrenderdoc (1.0) ...
Processing triggers for gnome-menus (3.36.0-1ubuntu1) ...
Processing triggers for desktop-file-utils (0.24-1ubuntu3) ...
Processing triggers for mime-support (3.64ubuntu1) ...
Processing triggers for hicolor-icon-theme (0.17-2) ...
Processing triggers for shared-mime-info (1.15-1) ...
```

- 如果依赖缺失，接着运行如下命令自动补全未满足的依赖：

```bash
sudo apt-get install -f
```

- **卸载 PhyRenderDoc** 通过命令方式进行，具体如下：

```bash
sudo dpkg --list | grep phyrender
sudo dpkg -r phyrenderdoc
(Reading database ... 337278 files and directories currently installed.)
Removing phyrenderdoc (1.0) ...
Processing triggers for shared-mime-info (1.15-1) ...
Processing triggers for hicolor-icon-theme (0.17-2) ...
Processing triggers for gnome-menus (3.36.0-1ubuntu1) ...
Processing triggers for desktop-file-utils (0.24-1ubuntu3) ...
Processing triggers for mime-support (3.64ubuntu1) ...
```

### 2.3 如何启动 PhyRenderDoc

可以通过两种方式启动：

- **命令行模式启动**

```bash
phyrenderdoc
MESA-INTEL: warning: Performance support disabled, consider sysctl dev.i915.perf_stream_paranoid=0
```

- **通过应用图标双击启动**

![双击应用图标启动](pic/img01.png)

- **启动过程需要注意点：**

在 Ubuntu 22.04 及其以上版本启动中会弹出如下菜单，这个是正常的。

![Ubuntu 22.04 启动提示](pic/img02.png)

### 2.4 工作主界面介绍

- PhyRenderDoc 基于 RenderDoc 平台开发，界面风格继承自 RenderDoc，启动后的界面如下图所示：

![主界面 1](pic/img03.png)

![主界面 2](pic/img04.png)

### 2.5 PhyRenderDoc 连接 OpenHarmony 设备

- 在 OpenHarmony 设备端通过串口 shell 执行如下命令，开启 hdc 调试模式和 remount 相关操作：

```bash
# 关闭内核日志输出，减少对调试操作的干扰
echo 0 > /proc/sys/kernel/printk
param set persist.hdc.mode tcp
param set persist.hdc.port 5555
param set persist.hdc.mode.tcp enable
param set persist.hdc.root 1
param set const.security.developermode.state true
service_control stop hdcd
service_control start hdcd
mount -o rw,remount /
mount -o rw,remount /vendor
```

- Ubuntu host 通过 hdc 连接上 OpenHarmony 设备端：

```bash
hdc tconn <device_ip>:5555
Connect OK
```

- 验证连接：

```bash
hdc list targets
<device_ip>:5555
```

- **选择设备开始连接**

![选择设备连接](pic/img05.png)

![连接界面 2](pic/img06.png)

![连接界面 3](pic/img07.png)

### 2.6 OpenHarmony 真机设备截帧

按照下图去选择要启动的游戏，这里以 render_service 举例：

- 首先需要打开 Launch Application 窗口，选择需要的服务或者应用

![Launch Application 窗口](pic/img08.png)

![选择应用](pic/img09.png)

- **可能会出现异常**

![连接异常](pic/img10.png)

**点击重新连接下设备即可**

![重新连接设备](pic/img11.png)

- 选择好后点击 Launch，就可以启动程序，下图为启动程序中：

![启动程序中](pic/img12.png)

- 启动成功后 RenderDoc 会弹出一个截帧窗口：

![截帧窗口](pic/img13.png)

- **开始截帧**
  - 设置需要截帧数量
  - 设置是否延迟截帧
  - 设置是否开启循环
  - **并且注意，截帧需要被截取的应用或者服务界面有变动时候才会生效**

![截帧设置](pic/img14.png)

### 2.7 本地保存截帧

- 选取要保存的帧，点击右键选择保存

![右键保存截帧](pic/img15.png)

![保存对话框](pic/img16.png)

### 2.8 回放实时截帧

通过 [2.7](#27-本地保存截帧) 我们截取了帧，我们也可以进行相关回放，具体步骤如下：

- 选取已经截取的帧，点击右键选择

![右键选择回放](pic/img17.png)

![回放界面](pic/img18.png)

- **查看 Event Browser 窗口**

![Event Browser 窗口](pic/img19.png)

- **查看 Texture Viewer 窗口**

![Texture Viewer 窗口](pic/img20.png)

### 2.9 加载保存本地截帧

- 点击 phyrenderdoc 软件 File 选项的 Open Capture

![File -> Open Capture](pic/img21.png)

- 选择需要加载的 rdc 截帧文件

![选择 rdc 文件](pic/img22.png)

![加载完成](pic/img23.png)

### 2.10 OpenHarmony 设备回放截取帧

通过 [2.8](#28-回放实时截帧) 和 [2.9](#29-加载保存本地截帧) 回放的截取帧可以在 OpenHarmony 设备上进行回放，如下：

![设备回放 1](pic/img24.png)

![设备回放 2](pic/img25.png)

### 2.11 开发技巧

更多关于 phyrenderdoc 的使用技巧，可以参阅 [RenderDoc 官方文档](https://renderdoc.org/docs/index.html)。