Chore/readme input debug polish - #3
Open
keys-cherish wants to merge 3 commits into
Open
Conversation
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
There was a problem hiding this comment.
Pull request overview
This PR adds bilingual (English/Chinese) documentation throughout the C++ and Dart codebase, applies code formatting changes (likely from an auto-formatter like clang-format), and introduces functional improvements: keyboard modifier/text-input forwarding on the Flutter engine surface, an expanded debug panel with backend/renderer/surface info, and removal of legacy Linux/Windows standalone executable targets.
Changes:
- Added keyboard modifier forwarding, Windows VK key mapping, and BMP text input forwarding from Flutter to the engine input pipeline.
- Expanded the in-game debug panel with backend description, present path, and surface/frame size summary.
- Applied bilingual comments and auto-formatter reformatting across C++ and Dart files; removed legacy Linux/Windows standalone build targets from CMakeLists.txt.
Reviewed changes
Copilot reviewed 11 out of 11 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
cpp/core/visual/ogl/krkr_egl_context.h |
Bilingual comments + formatting; IOSurface cleanup logic improvement in Destroy() |
cpp/core/visual/ogl/krkr_egl_context.cpp |
Bilingual comments + formatting; IOSurface resource cleanup before context destruction |
cpp/core/environ/EngineLoop.h |
Bilingual comments + formatting |
cpp/core/environ/EngineLoop.cpp |
Bilingual comments + formatting |
bridge/engine_api/include/engine_options.h |
Bilingual comments + alignment cleanup |
bridge/engine_api/include/engine_api.h |
Bilingual comments + formatting; fixed truncated out_flag parameter name; BOM introduced |
apps/flutter_app/lib/widgets/engine_surface.dart |
Keyboard VK mapping, modifier mask building, text input forwarding, debug accessors |
apps/flutter_app/lib/pages/game_page.dart |
Backend description loading, debug runtime summary, periodic debug panel refresh |
README_EN.md / README.md |
Updated feature tables and added recent updates section |
CMakeLists.txt |
Removed legacy Linux/Windows standalone executable targets |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
You can also share your feedback on Copilot code review. Take the survey.
| @@ -1,10 +1,10 @@ | |||
| #ifndef KRKR2_ENGINE_API_H_ | |||
| #ifndef KRKR2_ENGINE_API_H_ | |||
Comment on lines
1
to
+27
| /** | ||
| * @file krkr_egl_context.h | ||
| * @brief Headless EGL context manager using ANGLE. | ||
| * @brief Headless EGL context manager using | ||
| * ANGLE. | ||
| * @brief 基于 ANGLE 的无窗口 EGL 上下文管理器。 | ||
| * | ||
| * Replaces GLFW window + GLViewImpl with an offscreen | ||
| * EGL Pbuffer surface, providing a pure headless OpenGL ES 2.0 | ||
| * context that works on all platforms via ANGLE: | ||
| * - macOS → Metal backend | ||
| * - Windows → D3D11 backend | ||
| * - Linux → Desktop GL / Vulkan backend | ||
| * - Android → native GLES / Vulkan backend | ||
| * Replaces GLFW | ||
| * window + GLViewImpl with an offscreen | ||
| * EGL Pbuffer surface, providing a | ||
| * pure headless OpenGL ES 2.0 | ||
| * context that works on all platforms via | ||
| * ANGLE: | ||
| * 使用离屏 EGL Pbuffer surface 替代 GLFW window + GLViewImpl， | ||
| * | ||
| * 提供一个纯粹的无窗口 OpenGL ES 2.0 上下文，并通过 ANGLE 适配多平台： | ||
| * - | ||
| * macOS → Metal backend | ||
| * - macOS → Metal 后端 | ||
| * - Windows → D3D11 | ||
| * backend | ||
| * - Windows → D3D11 后端 | ||
| * - Linux → Desktop GL / Vulkan | ||
| * backend | ||
| * - Linux → Desktop GL / Vulkan 后端 | ||
| * - Android → native GLES | ||
| * / Vulkan backend | ||
| * - Android → 原生 GLES / Vulkan 后端 |
Comment on lines
+188
to
466
| * * startup_script_utf8 可为空，此时使用默认启动脚本。 | ||
| */ | ||
| ENGINE_API_EXPORT engine_result_t engine_open_game( | ||
| engine_handle_t handle, const char* game_root_path_utf8, | ||
| const char* startup_script_utf8); | ||
| ENGINE_API_EXPORT engine_result_t | ||
| engine_open_game(engine_handle_t handle, const char *game_root_path_utf8, | ||
| const char *startup_script_utf8); | ||
|
|
||
| /* | ||
| * Starts game opening asynchronously on a background worker. | ||
| * Returns immediately when the startup task is scheduled. | ||
| * | ||
| * 在后台线程异步启动游戏打开流程。 | ||
| * Returns immediately when the startup task | ||
| * is scheduled. | ||
| * 当启动任务排队成功后立即返回。 | ||
| */ | ||
| ENGINE_API_EXPORT engine_result_t engine_open_game_async( | ||
| engine_handle_t handle, const char* game_root_path_utf8, | ||
| const char* startup_script_utf8); | ||
| ENGINE_API_EXPORT engine_result_t | ||
| engine_open_game_async(engine_handle_t handle, const char *game_root_path_utf8, | ||
| const char *startup_script_utf8); | ||
|
|
||
| /* | ||
| * Gets async startup state. | ||
| * out_state must be non-null. | ||
| * 获取异步启动状态。 | ||
| * out_state must be | ||
| * non-null. | ||
| * out_state 不能为空。 | ||
| */ | ||
| ENGINE_API_EXPORT engine_result_t engine_get_startup_state( | ||
| engine_handle_t handle, uint32_t* out_state); | ||
| ENGINE_API_EXPORT engine_result_t | ||
| engine_get_startup_state(engine_handle_t handle, uint32_t *out_state); | ||
|
|
||
| /* | ||
| * Drains startup logs into caller buffer as UTF-8 text. | ||
| * 将启动日志以 | ||
| * UTF-8 文本形式写入调用方缓冲区。 | ||
| * Each log line is terminated by '\n'. | ||
| * | ||
| * 每条日志都以 '\n' 结尾。 | ||
| * Returns bytes written in out_bytes_written. | ||
| * | ||
| * 实际写入字节数通过 out_bytes_written 返回。 | ||
| */ | ||
| ENGINE_API_EXPORT engine_result_t engine_drain_startup_logs( | ||
| engine_handle_t handle, char* out_buffer, uint32_t buffer_size, | ||
| uint32_t* out_bytes_written); | ||
| ENGINE_API_EXPORT engine_result_t | ||
| engine_drain_startup_logs(engine_handle_t handle, char *out_buffer, | ||
| uint32_t buffer_size, uint32_t *out_bytes_written); | ||
|
|
||
| /* | ||
| * Ticks engine main loop once. | ||
| * handle must be non-null. | ||
| * delta_ms is caller-provided elapsed milliseconds. | ||
| * 驱动引擎主循环执行一帧。 | ||
| * handle must be | ||
| * non-null. | ||
| * handle 不能为空。 | ||
| * delta_ms is caller-provided elapsed | ||
| * milliseconds. | ||
| * delta_ms 由调用方提供，表示距离上一帧经过的毫秒数。 | ||
|
|
||
| */ | ||
| ENGINE_API_EXPORT engine_result_t engine_tick(engine_handle_t handle, | ||
| uint32_t delta_ms); | ||
|
|
||
| /* | ||
| * Pauses runtime execution. | ||
| * Idempotent: calling pause on a paused engine returns ENGINE_RESULT_OK. | ||
| * 暂停运行时执行。 | ||
| * Idempotent: calling pause | ||
| * on a paused engine returns ENGINE_RESULT_OK. | ||
| * | ||
| * 幂等：对已暂停引擎重复调用会返回 ENGINE_RESULT_OK。 | ||
| */ | ||
| ENGINE_API_EXPORT engine_result_t engine_pause(engine_handle_t handle); | ||
|
|
||
| /* | ||
| * Resumes runtime execution. | ||
| * Idempotent: calling resume on a running engine returns ENGINE_RESULT_OK. | ||
| * 恢复运行时执行。 | ||
| * Idempotent: calling | ||
| * resume on a running engine returns ENGINE_RESULT_OK. | ||
| * | ||
| * 幂等：对运行中的引擎重复调用会返回 ENGINE_RESULT_OK。 | ||
| */ | ||
| ENGINE_API_EXPORT engine_result_t engine_resume(engine_handle_t handle); | ||
|
|
||
| /* | ||
| * Sets runtime option by UTF-8 key/value pair. | ||
| * 通过 UTF-8 | ||
| * 键值对设置运行时选项。 | ||
| * handle and option must be non-null. | ||
| * handle 和 | ||
| * option 不能为空。 | ||
| */ | ||
| ENGINE_API_EXPORT engine_result_t engine_set_option(engine_handle_t handle, | ||
| const engine_option_t* option); | ||
| ENGINE_API_EXPORT engine_result_t | ||
| engine_set_option(engine_handle_t handle, const engine_option_t *option); | ||
|
|
||
| /* | ||
| * Sets logical render surface size in pixels. | ||
| * 设置逻辑渲染 surface | ||
| * 的像素尺寸。 | ||
| * width and height must be greater than zero. | ||
| * width 和 | ||
| * height 必须大于零。 | ||
| */ | ||
| ENGINE_API_EXPORT engine_result_t engine_set_surface_size(engine_handle_t handle, | ||
| uint32_t width, | ||
| uint32_t height); | ||
| ENGINE_API_EXPORT engine_result_t engine_set_surface_size( | ||
| engine_handle_t handle, uint32_t width, uint32_t height); | ||
|
|
||
| /* | ||
| * Gets current frame descriptor. | ||
| * 获取当前帧描述信息。 | ||
| * | ||
| * out_frame_desc->struct_size must be initialized by caller. | ||
| * | ||
| * 调用方必须先初始化 out_frame_desc->struct_size。 | ||
| */ | ||
| ENGINE_API_EXPORT engine_result_t engine_get_frame_desc( | ||
| engine_handle_t handle, engine_frame_desc_t* out_frame_desc); | ||
| engine_handle_t handle, engine_frame_desc_t *out_frame_desc); | ||
|
|
||
| /* | ||
| * Reads current frame into caller-provided RGBA8888 buffer. | ||
| * out_pixels_size must be >= stride_bytes * height from engine_get_frame_desc. | ||
| * | ||
| * 将当前帧读取到调用方提供的 RGBA8888 缓冲区。 | ||
| * out_pixels_size must be >= | ||
| * stride_bytes * height from engine_get_frame_desc. | ||
| * out_pixels_size | ||
| * 必须大于等于 engine_get_frame_desc 返回的 stride_bytes * height。 | ||
|
|
||
| */ | ||
| ENGINE_API_EXPORT engine_result_t engine_read_frame_rgba( | ||
| engine_handle_t handle, void* out_pixels, size_t out_pixels_size); | ||
| engine_handle_t handle, void *out_pixels, size_t out_pixels_size); | ||
|
|
||
| /* | ||
| * Gets host-native render window handle. | ||
| * On macOS runtime build this is NSWindow*. | ||
| * Returns ENGINE_RESULT_NOT_SUPPORTED on unsupported platforms/builds. | ||
| * 获取宿主平台原生渲染窗口句柄。 | ||
|
|
||
| * * On macOS runtime build this is NSWindow*. | ||
| * 在 macOS 运行时构建中返回 | ||
| * NSWindow*。 | ||
| * Returns ENGINE_RESULT_NOT_SUPPORTED on unsupported | ||
| * platforms/builds. | ||
| * 不支持的平台或构建将返回 ENGINE_RESULT_NOT_SUPPORTED。 | ||
|
|
||
| */ | ||
| ENGINE_API_EXPORT engine_result_t engine_get_host_native_window( | ||
| engine_handle_t handle, void** out_window_handle); | ||
| ENGINE_API_EXPORT engine_result_t | ||
| engine_get_host_native_window(engine_handle_t handle, void **out_window_handle); | ||
|
|
||
| /* | ||
| * Gets host-native render view handle. | ||
| * 获取宿主平台原生渲染视图句柄。 | ||
| * | ||
| * On macOS runtime build this is NSView* (typically the GLFW content view). | ||
| * Returns ENGINE_RESULT_NOT_SUPPORTED on unsupported platforms/builds. | ||
| * | ||
| * 在 macOS 运行时构建中返回 NSView*（通常是 GLFW content view）。 | ||
| * Returns | ||
| * ENGINE_RESULT_NOT_SUPPORTED on unsupported platforms/builds. | ||
| * | ||
| * 不支持的平台或构建将返回 ENGINE_RESULT_NOT_SUPPORTED。 | ||
| */ | ||
| ENGINE_API_EXPORT engine_result_t engine_get_host_native_view( | ||
| engine_handle_t handle, void** out_view_handle); | ||
| ENGINE_API_EXPORT engine_result_t | ||
| engine_get_host_native_view(engine_handle_t handle, void **out_view_handle); | ||
|
|
||
| /* | ||
| * Sends one input event to the runtime. | ||
| * 向运行时发送一条输入事件。 | ||
| * | ||
| * event->struct_size must be initialized by caller. | ||
| * 调用方必须先初始化 | ||
| * event->struct_size。 | ||
| */ | ||
| ENGINE_API_EXPORT engine_result_t engine_send_input(engine_handle_t handle, | ||
| const engine_input_event_t* event); | ||
| ENGINE_API_EXPORT engine_result_t | ||
| engine_send_input(engine_handle_t handle, const engine_input_event_t *event); | ||
|
|
||
| /* | ||
| * Sets an IOSurface as the render target for the engine. | ||
| * When set, engine_tick renders directly to this IOSurface (zero-copy), | ||
| * bypassing the glReadPixels path used by engine_read_frame_rgba. | ||
| * 将 IOSurface | ||
| * 设置为引擎渲染目标。 | ||
| * When set, engine_tick renders directly to this | ||
| * IOSurface (zero-copy), | ||
| * 设置后 engine_tick 会直接渲染到该 | ||
| * IOSurface（零拷贝）， | ||
| * bypassing the glReadPixels path used by | ||
| * engine_read_frame_rgba. | ||
| * 绕过 engine_read_frame_rgba 使用的 glReadPixels | ||
| * 读回路径。 | ||
| * | ||
| * iosurface_id: The IOSurfaceID obtained from | ||
| * IOSurfaceGetID(). | ||
| * iosurface_id：通过 IOSurfaceGetID() 获取的 | ||
| * IOSurfaceID。 | ||
| * Pass 0 to detach and revert to the default | ||
| * Pbuffer mode. | ||
| * 传 0 表示解除绑定并退回默认的 Pbuffer 模式。 | ||
|
|
||
| * * width/height: Dimensions of the IOSurface in pixels. | ||
| * | ||
| * iosurface_id: The IOSurfaceID obtained from IOSurfaceGetID(). | ||
| * Pass 0 to detach and revert to the default Pbuffer mode. | ||
| * width/height: Dimensions of the IOSurface in pixels. | ||
| * width/height：IOSurface 的像素尺寸。 | ||
| * | ||
| * Platform: macOS only. Returns ENGINE_RESULT_NOT_SUPPORTED on other platforms. | ||
| * Platform: macOS only. Returns | ||
| * ENGINE_RESULT_NOT_SUPPORTED on other platforms. | ||
| * 平台限制：仅 macOS | ||
| * 支持；其他平台返回 ENGINE_RESULT_NOT_SUPPORTED。 | ||
| */ | ||
| ENGINE_API_EXPORT engine_result_t engine_set_render_target_iosurface( | ||
| engine_handle_t handle, uint32_t iosurface_id, | ||
| uint32_t width, uint32_t height); | ||
| engine_handle_t handle, uint32_t iosurface_id, uint32_t width, | ||
| uint32_t height); | ||
|
|
||
| /* | ||
| * Sets an Android Surface (from SurfaceTexture) as the render target. | ||
| * When set, engine_tick renders to an EGL WindowSurface created from the | ||
| * 将 | ||
| * Android Surface（来自 SurfaceTexture）设置为渲染目标。 | ||
| * When set, | ||
| * engine_tick renders to an EGL WindowSurface created from the | ||
| * | ||
| * 设置后，engine_tick 会渲染到由 ANativeWindow 创建的 EGL WindowSurface。 | ||
| * | ||
| * ANativeWindow. eglSwapBuffers() delivers frames directly to Flutter's | ||
| * SurfaceTexture (GPU zero-copy). | ||
| * | ||
| * native_window: ANativeWindow* obtained from ANativeWindow_fromSurface(). | ||
| * Pass NULL to detach and revert to the default Pbuffer mode. | ||
| * eglSwapBuffers() 会把帧直接送到 Flutter 的 SurfaceTexture。 | ||
| * SurfaceTexture | ||
| * (GPU zero-copy). | ||
| * 整个路径为 GPU 零拷贝。 | ||
| * | ||
| * native_window: | ||
| * ANativeWindow* obtained from ANativeWindow_fromSurface(). | ||
| * | ||
| * native_window：由 ANativeWindow_fromSurface() 获取的 ANativeWindow*。 | ||
| * | ||
| * Pass NULL to detach and revert to the default Pbuffer mode. | ||
| * 传 NULL | ||
| * 表示解除绑定并退回默认 Pbuffer 模式。 | ||
| * width/height: Dimensions in pixels. | ||
|
|
||
| * * width/height：渲染目标的像素尺寸。 | ||
| * | ||
| * Platform: Android only. Returns ENGINE_RESULT_NOT_SUPPORTED on other platforms. | ||
| * Platform: Android only. Returns | ||
| * ENGINE_RESULT_NOT_SUPPORTED on other platforms. | ||
| * 平台限制：仅 Android | ||
| * 支持；其他平台返回 ENGINE_RESULT_NOT_SUPPORTED。 | ||
| */ | ||
| ENGINE_API_EXPORT engine_result_t engine_set_render_target_surface( | ||
| engine_handle_t handle, void* native_window, | ||
| uint32_t width, uint32_t height); | ||
| ENGINE_API_EXPORT engine_result_t | ||
| engine_set_render_target_surface(engine_handle_t handle, void *native_window, | ||
| uint32_t width, uint32_t height); | ||
|
|
||
| /* | ||
| * Queries whether the last engine_tick produced a new rendered frame. | ||
| * out_ | ||
| * | ||
| * out_ | ||
| * - 0: no new frame since last query | ||
| * 查询最近一次 engine_tick 是否产出了新渲染帧。 | ||
| * | ||
| * out_flag: | ||
| * - 0: no new frame since the previous query | ||
| * - 0：自上一次查询以来没有新帧 | ||
| * - 1: a new frame was rendered | ||
| * - 1：产生了新渲染帧 | ||
| * | ||
| * This is useful in IOSurface mode to know when to call | ||
| * textureFrameAvailable() on the Flutter side. | ||
| * This is mainly used by zero-copy presentation paths such as IOSurface | ||
| * and SurfaceTexture to decide when the host should notify Flutter that a | ||
| * frame is available. | ||
| * 该标记主要供 IOSurface、SurfaceTexture 等零拷贝展示路径使用， | ||
| * 以便宿主侧判断何时通知 Flutter 有新帧可用。 | ||
| */ | ||
| ENGINE_API_EXPORT engine_result_t engine_get_frame_rendered_flag( | ||
| engine_handle_t handle, uint32_t* out_ | ||
| ); | ||
| ENGINE_API_EXPORT engine_result_t | ||
| engine_get_frame_rendered_flag(engine_handle_t handle, uint32_t *out_flag); | ||
|
|
||
| /* | ||
| * Queries the graphics renderer information string. | ||
| * Writes a null-terminated UTF-8 string into out_buffer describing | ||
| * the active graphics backend (e.g. "Metal", "OpenGL ES", "D3D11"). | ||
| * | ||
| * 查询图形渲染器信息字符串。 | ||
| * Writes a null-terminated UTF-8 string into | ||
| * out_buffer describing | ||
| * 将一个以空字符结尾的 UTF-8 字符串写入 out_buffer， | ||
|
|
||
| * * the active graphics backend (e.g. "Metal", "OpenGL ES", "D3D11"). | ||
| * | ||
| * 描述当前激活的图形后端（例如 "Metal"、"OpenGL ES"、"D3D11"）。 | ||
| * | ||
| * | ||
| * out_buffer and buffer_size must be non-null / > 0. | ||
| * If the buffer is too small the string is truncated. | ||
| * Returns ENGINE_RESULT_INVALID_STATE if the runtime is not active. | ||
| * out_buffer 与 | ||
| * buffer_size 必须有效，且 buffer_size > 0。 | ||
| * If the buffer is too small the | ||
| * string is truncated. | ||
| * 如果缓冲区过小，字符串会被截断。 | ||
| * Returns | ||
| * ENGINE_RESULT_INVALID_STATE if the runtime is not active. | ||
| * | ||
| * 若运行时未激活，则返回 ENGINE_RESULT_INVALID_STATE。 | ||
| */ |
3 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
No description provided.