@ -36,6 +36,35 @@ Pull requests are only to be merged by core developers when properly tested and
- Maintainers are permitted to change namespaces at will.
- Commits within PRs are not required to be namespaced, but it is highly recommended.
## Adding new settings
When adding new settings, use `tr("Setting:")` if the setting is meant to be a field, otherwise use `tr("Setting")` if the setting is meant to be a Yes/No or checkmark type of setting, see [this short style guide](https://learn.microsoft.com/en-us/style-guide/punctuation/colons#in-ui).
- The majority of software must work with the default option selected for such setting. Unless the setting significantly degrades performance.
- Debug settings must never be turned on by default.
- Provide reasonable bounds (for example, a setting controlling the amount of VRAM should never be 0).
- The description of the setting must be short and concise, if the setting "does a lot of things" consider splitting the setting into multiple if possible.
- Try to avoid excessive/redundant explainations "recommended for most users and games" can just be "(recommended)".
- Try to not write "slow/fast" options unless it clearly degrades/increases performance for a given case, as most options may modify behaviour that result in different metrics accross different systems. If for example the option is an "accuracy" option, writing "High" is sufficient to imply "Slow". No need to write "High (Slow)".
Some examples:
- "[...] negatively affecting image quality", "[...] degrading image quality": Same wording but with less filler.
- "[...] this may cause some glitches or crashes in some games", "[...] this may cause soft-crashes": Crashes implies there may be glitches (as crashes are technically a form of a fatal glitch). The entire sentence is structured as "may cause [...] on some games", which is redundant, because "may cause [...] in games" has the same semantic meaning ("may" is a chance that it will occur on "some" given set).
- "FIFO Relaxed is similar to FIFO [...]", "FIFO Relaxed [...]": The name already implies similarity.
- "[...] but may also reduce performance in some cases", "[...] but may degrade performance": Again, "some cases" and "may" implies there is a probability.
- "[...] it can [...] in some cases", "[...] it can [...]": Implied probability.
Before adding a new setting, consider:
- Does the piece of code that the setting pertains to, make a significant difference if it's on/off?
- Can it be auto-detected?
- Does the option behave differently on some platforms?
- Is it a feature specific to a given platform?"
While not a silver bullet, settings are mainly suitable for:
- Core: CPU, memory, input, scheduler, audio, or other base emulator logic.
<stringname="system_archive_not_found">System Archive Not Found</string>
<stringname="system_archive_not_found_message">%s is missing. Please dump your system archives.\nContinuing emulation may result in crashes and bugs.</string>
<stringname="system_archive_not_found_message">%s is missing. Please dump your system archives.\nContinuing emulation may result in crashes.</string>
<stringname="system_archive_general">A system archive</string>
<stringname="fatal_error_message">A fatal error occurred. Check the log for details.\nContinuing emulation may result in crashes and bugs.</string>
<stringname="performance_warning">Turning off this setting will significantly reduce emulation performance! For the best experience, it is recommended that you leave this setting enabled.</string>
<stringname="fatal_error_message">A fatal error occurred. Check the log for details.\nContinuing emulation may result in crashes.</string>
<stringname="performance_warning">Turning off this setting will significantly degrade performance. It's recommended that you leave this setting enabled.</string>
tr("This optimization speeds up memory accesses by the guest program.\nEnabling it causes guest memory reads/writes to be done directly into memory and make use of Host's MMU.\nDisabling this forces all memory accesses to use Software MMU Emulation."));
tr("Enabling causes guest memory operations to be done directly into host memory with an on-demand paging mechanism.\nDisabling this forces all memory accesses to use a slower translation dispatch."));
INSERT(
Settings,
cpuopt_unsafe_unfuse_fma,
tr("Unfuse FMA (improve performance on CPUs without FMA)"),
tr("This option improves speed by reducing accuracy of fused-multiply-add instructions on "
"CPUs without native FMA support."));
tr("Unfuse FMA"),
tr("Prevents materialisation of precise fused-multiply-add instructions."));
INSERT(
Settings,
cpuopt_unsafe_reduce_fp_error,
tr("Faster FRSQRTE and FRECPE"),
tr("This option improves the speed of some approximate floating-point functions by using "
"less accurate native approximations."));
tr("Uses (innacurate but fast) native instructions as opposed to checked ones."));
INSERT(Settings,
cpuopt_unsafe_ignore_standard_fpcr,
tr("Faster ASIMD instructions (32 bits only)"),
tr("This option improves the speed of 32 bits ASIMD floating-point functions by running "
"with incorrect rounding modes."));
tr("Removes checks for FPCR rounding mode on floating-point instructions."));
INSERT(Settings,
cpuopt_unsafe_inaccurate_nan,
tr("Inaccurate NaN handling"),
tr("This option improves speed by removing NaN checking.\nPlease note this also reduces "
"accuracy of certain floating-point instructions."));
tr("Removes checks for NaNs on all floating-point instructions."));
INSERT(Settings,
cpuopt_unsafe_fastmem_check,
tr("Disable address space checks"),
tr("This option improves speed by eliminating a safety check before every memory "
"read/write in guest.\nDisabling it may allow a game to read/write the emulator's "
"memory."));
tr("Removes the safety check before every memory operation in the guest.\n"
"Disabling will allow the guest to read/write all memory."));
INSERT(
Settings,
cpuopt_unsafe_ignore_global_monitor,
tr("Ignore global monitor"),
tr("This option improves speed by relying only on the semantics of cmpxchg to ensure "
tr("This option improves speed by relying on the semantics of CMPXCHG to ensure "
"safety of exclusive access instructions.\nPlease note this may result in deadlocks and "
tr("This option controls how ASTC textures should be decoded.\n"
"CPU: Use the CPU for decoding, slowest but safest method.\n"
"GPU: Use the GPU's compute shaders to decode ASTC textures, recommended for most "
"games and users.\n"
"CPU Asynchronously: Use the CPU to decode ASTC textures as they arrive. Completely "
"eliminates ASTC decoding\nstuttering at the cost of rendering issues while the "
"texture is being decoded."));
"CPU: Use the CPU for decoding.\n"
"GPU: Use the GPU's compute shaders to decode ASTC textures (recommended).\n"
"CPU Asynchronously: Use the CPU to decode ASTC textures on demand. Eliminates"
"ASTC decoding\nstuttering but may present artifacts."));
INSERT(
Settings,
astc_recompression,
tr("ASTC Recompression Method:"),
tr("Almost all desktop and laptop dedicated GPUs lack support for ASTC textures, forcing "
"the emulator to decompress to an intermediate format any card supports, RGBA8.\n"
"This option recompresses RGBA8 to either the BC1 or BC3 format, saving VRAM but "
"negatively affecting image quality."));
tr("Most GPUs lack support for ASTC textures and must decompress to an"
"intermediate format.\n"
"RGBA8: This option recompresses RGBA8 to either BC1 or BC3 format, saving VRAM but "
" degrading image quality."));
INSERT(Settings,
vram_usage_mode,
tr("VRAM Usage Mode:"),
tr("Selects whether the emulator should prefer to conserve memory or make maximum usage of available video memory for performance.\nAggressive mode may severely impact the performance of other applications such as recording software."));
tr("Selects whether the emulator should prefer to conserve memory or make maximum usage of available video memory for performance.\nAggressive mode may impact performance of other applications such as recording software."));
INSERT(Settings,
skip_cpu_inner_invalidation,
tr("Skip CPU Inner Invalidation"),
tr("Skips certain CPU-side cache invalidations during memory updates, reducing CPU usage and "
"improving it's performance. This may cause glitches or crashes on some games."));
tr("Skips certain cache invalidations during memory updates, reducing CPU usage and "
"improving latency. This may cause soft-crashes."));
INSERT(
Settings,
vsync_mode,
tr("VSync Mode:"),
tr("FIFO (VSync) does not drop frames or exhibit tearing but is limited by the screen "
"refresh rate.\nFIFO Relaxed is similar to FIFO but allows tearing as it recovers from "
"a slow down.\nMailbox can have lower latency than FIFO and does not tear but may drop "
"frames.\nImmediate (no synchronization) just presents whatever is available and can "
"refresh rate.\nFIFO Relaxed allows tearing as it recovers from a slow down.\n"
"Mailbox can have lower latency than FIFO and does not tear but may drop "
"frames.\nImmediate (no synchronization) presents whatever is available and can "
tr("Ensures data consistency between compute and memory operations.\nThis option should fix issues in some games, but may also reduce performance in some cases.\nUnreal Engine 4 games often see the most significant changes thereof."));
tr("Ensures data consistency between compute and memory operations.\nThis option fixes issues in games, but may degrade performance.\nUnreal Engine 4 games often see the most significant changes thereof."));
tr("Controls the DMA precision accuracy. Safe precision can fix issues in some games, but it can also impact performance in some cases.\nIf unsure, leave this on Default."));
tr("Controls the DMA precision accuracy. Safe precision fixes issues in some games but may degrade performance."));
INSERT(Settings,
use_asynchronous_shaders,
tr("Use asynchronous shader building (Hack)"),
tr("Enables asynchronous shader compilation, which may reduce shader stutter."));
tr("Controls the number of features that can be used in Extended Dynamic State.\nHigher numbers allow for more features and can increase performance, but may cause issues with some drivers and vendors.\nThe default value may vary depending on your system and hardware capabilities.\nThis value can be changed until stability and a better visual quality are achieved."));
tr("Controls the number of features that can be used in Extended Dynamic State.\nHigher numbers allow for more features and can increase performance, but may cause issues.\nThe default value is per-system."));
INSERT(Settings,
provoking_vertex,
tr("Provoking Vertex"),
tr("Improves lighting and vertex handling in certain games.\n"
tr("Improves lighting and vertex handling in some games.\n"
"Only Vulkan 1.0+ devices support this extension."));