diff --git a/docs/user/AddingDebugKnobs.md b/docs/user/AddingDebugKnobs.md index bcf3f1fcc6..649b9526d8 100644 --- a/docs/user/AddingDebugKnobs.md +++ b/docs/user/AddingDebugKnobs.md @@ -12,12 +12,13 @@ The setting ranges from 0 to 65535 (0x0000 to 0xFFFF), where each bit represents * [Accessing Debug Knobs (dev side)](#accessing-debug-knobs-dev-side) * [Setting Debug Knobs (user side)](#setting-debug-knobs-user-side) * [Bit Manipulation Examples](#bit-manipulation-examples) -3. [Examples](#examples) +3. [Terminology and user communication](#terminology-and-use-communication) +4. [Examples](#examples) * [Example 1: Conditional Debug Logging](#example-1-conditional-debug-logging) * [Example 2: Performance Tuning](#example-2-performance-tuning) * [Example 3: Feature Gating](#example-3-feature-gating) -4. [Best Practices](#best-practices) +5. [Best Practices](#best-practices) --- @@ -77,6 +78,42 @@ To enable specific features, calculate the decimal value by setting the appropri * **Enable bits 0 and 1**: Value = 3 (2^0 + 2^1) * **Enable bit 15**: Value = 32768 (2^15) +## Terminology and user communication + +There are two main confusions when talking about knobs: + +### Whether it's zero-based or one-based + +Sometimes when an user reports: knobs 1 and 2 gets better performance, dev may get confuse whether he means the knobs 1 and 2 literally, or the 1st and 2nd knobs (knobs 0 and 1). + +Debug knobs are **zero-based**, which means: +* The first knob is the knob(0) (or knob0 henceforth), and the last one is the 15 (knob15, likewise) +* You can talk: "knob0 is enabled/disabled", "In this video i was using only knobs 0 and 2", etc. + +### Whether one is talking about the knob itself or about the entire parameter value (which represents all knobs) + +Sometimes when an user reports: knob 3 results, it's unclear whether he's referring to knob setting with value 3 (which means both knob 0 and 1 are enabled), or to knob(3) specifically. +Whenever you're instructing tests or reporting results, be precise about whether one you're talking to avoid confusion: + +* Setting based terminology + +Use the word in PLURAL (knobs), without mentioning which one, to refer to the setting, aka multiple knobs at once: +Examples: +- **knobs=0**: no knobs enabled +- **knobs=1**: knob0 enabled, others disabled +- **knobs=2**: knob1 enabled, others disabled +- **knobs=3**: knobs 0 and 1 enabled, others disabled +... + +* Knob based terminology + +Use the word in SINGULAR (knob), or in plural but referring which ones, when meaning multiple knobs at once: +Examples: +- **knob0**: knob 0 enabled, others disabled +- **knob1**: knob 1 enabled, others disabled +- **knobs 0 and 1**: knobs 0 and 1 enabled, others disabled +... + ## Examples ### Example 1: Conditional Debug Logging diff --git a/src/android/app/src/main/java/org/yuzu/yuzu_emu/features/settings/model/IntSetting.kt b/src/android/app/src/main/java/org/yuzu/yuzu_emu/features/settings/model/IntSetting.kt index be3b2f4a48..ed120827d3 100644 --- a/src/android/app/src/main/java/org/yuzu/yuzu_emu/features/settings/model/IntSetting.kt +++ b/src/android/app/src/main/java/org/yuzu/yuzu_emu/features/settings/model/IntSetting.kt @@ -67,7 +67,6 @@ enum class IntSetting(override val key: String) : AbstractIntSetting { MY_PAGE_APPLET("my_page_applet_mode"), INPUT_OVERLAY_AUTO_HIDE("input_overlay_auto_hide"), OVERLAY_GRID_SIZE("overlay_grid_size"), - DEBUG_KNOBS("debug_knobs"), GPU_LOG_RING_BUFFER_SIZE("gpu_log_ring_buffer_size") ; diff --git a/src/android/app/src/main/java/org/yuzu/yuzu_emu/features/settings/model/ShortSetting.kt b/src/android/app/src/main/java/org/yuzu/yuzu_emu/features/settings/model/ShortSetting.kt index 16eb4ffdd5..57a99e01ad 100644 --- a/src/android/app/src/main/java/org/yuzu/yuzu_emu/features/settings/model/ShortSetting.kt +++ b/src/android/app/src/main/java/org/yuzu/yuzu_emu/features/settings/model/ShortSetting.kt @@ -6,7 +6,8 @@ package org.yuzu.yuzu_emu.features.settings.model import org.yuzu.yuzu_emu.utils.NativeConfig enum class ShortSetting(override val key: String) : AbstractShortSetting { - RENDERER_SPEED_LIMIT("speed_limit"); + RENDERER_SPEED_LIMIT("speed_limit"), + DEBUG_KNOBS("debug_knobs"); override fun getShort(needsGlobal: Boolean): Short = NativeConfig.getShort(key, needsGlobal) diff --git a/src/android/app/src/main/java/org/yuzu/yuzu_emu/features/settings/model/view/SettingsItem.kt b/src/android/app/src/main/java/org/yuzu/yuzu_emu/features/settings/model/view/SettingsItem.kt index 47932c2dd8..33c201e77a 100644 --- a/src/android/app/src/main/java/org/yuzu/yuzu_emu/features/settings/model/view/SettingsItem.kt +++ b/src/android/app/src/main/java/org/yuzu/yuzu_emu/features/settings/model/view/SettingsItem.kt @@ -860,7 +860,7 @@ abstract class SettingsItem( ) put( SpinBoxSetting( - IntSetting.DEBUG_KNOBS, + ShortSetting.DEBUG_KNOBS, titleId = R.string.debug_knobs, descriptionId = R.string.debug_knobs_description, valueHint = R.string.debug_knobs_hint, diff --git a/src/android/app/src/main/java/org/yuzu/yuzu_emu/features/settings/ui/SettingsFragmentPresenter.kt b/src/android/app/src/main/java/org/yuzu/yuzu_emu/features/settings/ui/SettingsFragmentPresenter.kt index e7c2dbf609..f274d09b55 100644 --- a/src/android/app/src/main/java/org/yuzu/yuzu_emu/features/settings/ui/SettingsFragmentPresenter.kt +++ b/src/android/app/src/main/java/org/yuzu/yuzu_emu/features/settings/ui/SettingsFragmentPresenter.kt @@ -1229,7 +1229,7 @@ class SettingsFragmentPresenter( add(HeaderSetting(R.string.general)) - add(IntSetting.DEBUG_KNOBS.key) + add(ShortSetting.DEBUG_KNOBS.key) add(HeaderSetting(R.string.gpu_logging_header)) add(BooleanSetting.GPU_LOGGING_ENABLED.key) diff --git a/src/common/settings.h b/src/common/settings.h index 41f766a5e7..0445475f5c 100644 --- a/src/common/settings.h +++ b/src/common/settings.h @@ -764,7 +764,7 @@ struct Values { 0, 65535, "debug_knobs", - Category::Debugging, + Category::Core, Specialization::Countable, true, true};