[Initialization & Setting] 改进的引擎初始化流程和配置管理

[Demonese]

1、提供获取当前引擎设置的API，允许查询画布分辨率、全屏等设置
2、提供命令行参数接口来配置画布分辨率、全屏等设置

[Demonese]

---@diagnostic disable: missing-return

---@class lstg.SettingManager
local M = {}
lstg.SettingManager = M

--------------------------------------------------------------------------------
--- 配置加载、保存

--- 从配置文件加载并应用配置，若不提供路径，则从默认位置 config.json 加载  
--- 注意：此 API 永远不会从压缩包内加载配置文件  
---@param json_path string
---@return boolean
---@overload fun():boolean
function M.Load(json_path)
end

--- 保存当前配置到配置文件，若不提供路径，则保存到默认位置 config.json  
---@param json_path string
---@return boolean
---@overload fun():boolean
function M.Save(json_path)
end

--- 是否自动保存配置，默认为启用  
--- 注意：此项不保存于配置文件中，每次启动引擎都会重置  
---@param enable boolean
function M.SetAutoSaveEnable(enable)
end

--- 检查自动保存配置是否启用
---@return boolean
function M.GetAutoSaveEnable()
end

--------------------------------------------------------------------------------
--- 渲染

--- 设置当前使用的图形设备（GPU），默认为空字符串（""），代表使用默认设备  
--- 如果切换失败，则使用默认的图形设备  
--- 若字符串为空（""），则使用默认的图形设备
---@param device_name string
---@return boolean
function M.SetTargetGraphicDevice(device_name)
end

--- 获取当前配置的图形设备  
--- 注意：如果要获取当前使用的图形设备的名称，请使用另一个 API，  
--- 此 API 获取的名称是上一次调用 SetGraphicDevice 时传入的值  
---@return string
function M.GetTargetGraphicDevice()
end

--------------------------------------------------------------------------------
--- 画布

--- 修改画布尺寸，默认为 640x480  
---@param width number
---@param height number
---@return boolean
function M.SetCanvasSize(width, height)
end

--- 获取当前画布尺寸
---@return number, number
function M.GetCanvasSize()
end

--------------------------------------------------------------------------------
--- 窗口和交换链

--- 修改目标窗口客户区尺寸，默认为 640x480  
--- 第一次启动时，用来初始化窗口尺寸，并在显示器上居中显示  
--- 如果未启用记忆窗口布局功能，后续每次启动都会如此配置  
---@param width number
---@param height number
---@return boolean
function M.SetTargetWindowSize(width, height)
end

--- 获取当前目标窗口尺寸
---@return number, number
function M.GetTargetWindowSize()
end

--- 是否记住窗口布局，如窗口位置、尺寸、最小化或最大化状态  
--- 如果未启用，每次初始化窗口时使用 SetTargetWindowSize 设置的尺寸  
---@param enable boolean
function M.SetRememberWindowPlacementEnable(enable)
end

---@return boolean
function M.GetRememberWindowPlacementEnable()
end

--- 设置全屏显示，默认为禁用  
--- 默认情况下会挑选离当前窗口最近的显示器全屏  
--- 全屏模式由引擎托管，会自动从多个不同的模式中选择最合适的  
---@param enable boolean
---@return boolean
function M.SetFullScreenEnable(enable)
end

--- 是否处于全屏模式  
--- 注意：如果引擎采用独占全屏进行全屏显示，当用户临时切换到其他程序时，
--- 引擎会临时离开独占全屏，但此 API 仍然会报告为开启，这不是 bug  
---@return boolean
function M.GetFullScreenEnable()
end

--- 设置垂直同步，默认为禁用  
--- 注意：即使禁用垂直同步，也不一定会产生画面撕裂，  
--- 比如画面完全交给桌面窗口管理器（DWM）合成时（会带来负面影响），  
--- 或者系统、驱动、显卡和显示器支持可变刷新率（会带来正面影响）  
---@param enable boolean
---@return boolean
function M.SetVsyncEnable(enable)
end

--- 获取垂直同步开启状态  
---@return boolean
function M.GetVsyncEnable()
end

--- 设置窗口标题，默认为引擎名称和引擎版本号  
---@param text string
function M.SetWindowTitle(text)
end

--- 获取配置的窗口标题  
--- 注意：此 API 获取的是上次 SetWindowTitle 传入的值，并非真实窗口标题
---@return string
function M.GetWindowTitle()
end

--- 设置鼠标在窗口上的显示状态，默认为允许显示  
---@param enable boolean
function M.SetWindowCursorEnable(enable)
end

---@return boolean
function M.GetWindowCursorEnable()
end

--------------------------------------------------------------------------------
--- 更新

--- 设置目标帧率，默认为 60  
--- 警告：严禁设置为小于或等于 0 的值，否则后果自负  
---@param frame_rate number
function M.SetTargetFrameRate(frame_rate)
end

---@return number
function M.GetTargetFrameRate()
end

--------------------------------------------------------------------------------
--- 音频

--- 设置音效通道音量  
---@param volume number
function M.SetSoundEffectChannelVolume(volume)
end

---@return number
function M.GetSoundEffectChannelVolume()
end

--- 设置音乐通道音量  
---@param volume number
function M.SetMusicChannelVolume(volume)
end

---@return number
function M.GetMusicChannelVolume()
end

return M

[Demonese]

命令行参数接口，单项设置

--graphic-device="Intel UHD 770"
--canvas-size=640x480
--fullscreen=false
--vsync=false
--window-title="Hello World"
--window-cursor-enable=false
--target-frame-rate=60
--sound-effect-channel-volume=1.0
--music-channel-volume=1.0

命令行参数接口，指定配置文件

--config-file-path="foo/bar.json"

[Demonese]

关于初次启动流程的窗口配置：

• 在 config 中提供一个 first_time_startup_window_size target_window_size 的信息，第一次启动时通过该信息配置窗口尺寸并自动居中，以后则通过自动保存、加载窗口布局来配置窗口。
• 提供 API SetFirstTimeStartupWindowSize SetTargetWindowSize（暂定）。
• 提供 API ClearSavedWindowPlacement （暂定）用于去除已保存的窗口布局，下次启动时将会以第一次启动的逻辑配置窗口