{"record":{"id":"b3b5980ca1a8b5ec","repo":"EllanJiang/GameFramework","slug":"you-must-set-screen-dpi-first","errorCode":null,"errorMessage":"You must set screen DPI first.","messagePattern":"You must set screen DPI first\\.","errorType":"exception","errorClass":"GameFrameworkException","httpStatus":null,"severity":"error","filePath":"GameFramework/Utility/Utility.Converter.cs","lineNumber":52,"sourceCode":"            /// <summary>\n            /// 获取或设置屏幕每英寸点数。\n            /// </summary>\n            public static float ScreenDpi\n            {\n                get;\n                set;\n            }\n\n            /// <summary>\n            /// 将像素转换为厘米。\n            /// </summary>\n            /// <param name=\"pixels\">像素。</param>\n            /// <returns>厘米。</returns>\n            public static float GetCentimetersFromPixels(float pixels)\n            {\n                if (ScreenDpi <= 0)\n                {\n                    throw new GameFrameworkException(\"You must set screen DPI first.\");\n                }\n\n                return InchesToCentimeters * pixels / ScreenDpi;\n            }\n\n            /// <summary>\n            /// 将厘米转换为像素。\n            /// </summary>\n            /// <param name=\"centimeters\">厘米。</param>\n            /// <returns>像素。</returns>\n            public static float GetPixelsFromCentimeters(float centimeters)\n            {\n                if (ScreenDpi <= 0)\n                {\n                    throw new GameFrameworkException(\"You must set screen DPI first.\");\n                }\n\n                return CentimetersToInches * centimeters * ScreenDpi;","sourceCodeStart":34,"sourceCodeEnd":70,"githubUrl":"https://github.com/EllanJiang/GameFramework/blob/d0c010b05167c58e92350449d04864a91ca13fd2/GameFramework/Utility/Utility.Converter.cs#L34-L70","documentation":"Utility.Converter's pixel-to-centimeter conversion divides by the static ScreenDpi property. If ScreenDpi has not been set (or is <= 0), the conversion is meaningless, so GetCentimetersFromPixels throws \"You must set screen DPI first.\"","triggerScenarios":"Calling Utility.GetCentimetersFromPixels(pixels) before setting Utility.ScreenDpi to a positive value.","commonSituations":"Calling conversion helpers during app startup before the DPI bootstrap code runs, or after forgetting to set DPI on a platform where Screen.dpi is unavailable/zero.","solutions":["Set Utility.ScreenDpi = Screen.dpi (or a device-appropriate fallback) at startup.","Guard calls so conversions only happen after DPI initialization.","Fall back to a sensible default DPI (e.g. 96 or 160) when Screen.dpi reports 0."],"exampleFix":"// before\nfloat cm = Utility.GetCentimetersFromPixels(pixels); // DPI not set\n\n// after\nif (Utility.ScreenDpi <= 0)\n{\n    Utility.ScreenDpi = Screen.dpi > 0 ? Screen.dpi : 160f;\n}\nfloat cm = Utility.GetCentimetersFromPixels(pixels);","handlingStrategy":"validation","validationCode":"if (Utility.ScreenDpi <= 0) { Utility.ScreenDpi = Screen.dpi > 0 ? Screen.dpi : 160f; }","typeGuard":null,"tryCatchPattern":"try { float cm = Utility.GetCentimetersFromPixels(px); } catch (GameFrameworkException) { Utility.ScreenDpi = Screen.dpi > 0 ? Screen.dpi : 160f; }","preventionTips":["Set Utility.ScreenDpi in the app's bootstrap/startup code","Provide a fallback DPI because Screen.dpi can be 0 on some devices","Run all DPI conversions after initialization only"],"tags":["unity","initialization","screen-dpi"],"backgroundTag":"missing-required-config","analyzedSha":"d0c010b05167c58e92350449d04864a91ca13fd2","analyzedAt":"2026-09-15T13:37:15.352Z","contentChangedAt":"2026-09-15T13:37:15.352Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}