{"record":{"id":"297215f45f8e348a","repo":"microg/GmsCore","slug":"transparency-must-be-in-range-0-1","errorCode":null,"errorMessage":"transparency must be in range [0..1]","messagePattern":"transparency must be in range \\[0\\.\\.1\\]","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"play-services-maps/src/main/java/com/google/android/gms/maps/model/GroundOverlayOptions.java","lineNumber":327,"sourceCode":"        if (location != null)\n            throw new IllegalStateException(\"Position already set using position()\");\n        this.bounds = bounds;\n        return this;\n    }\n\n    /**\n     * Specifies the transparency of the ground overlay. The default transparency is {code 0}\n     * (opaque).\n     *\n     * @param transparency a float in the range {@code [0..1]} where {@code 0} means that the\n     *                     ground overlay is opaque and {code 1} means that the ground overlay is\n     *                     transparent\n     * @return this {@link GroundOverlayOptions} object with a new visibility setting.\n     * @throws IllegalArgumentException if the transparency is outside the range [0..1].\n     */\n    public GroundOverlayOptions transparency(float transparency) throws IllegalArgumentException {\n        if (transparency < 0 || transparency > 1)\n            throw new IllegalArgumentException(\"transparency must be in range [0..1]\");\n        this.transparency = transparency;\n        return this;\n    }\n\n    /**\n     * Specifies the visibility for the ground overlay. The default visibility is {@code true}.\n     *\n     * @return this {@link GroundOverlayOptions} object with a new visibility setting.\n     */\n    public GroundOverlayOptions visible(boolean visible) {\n        this.visible = visible;\n        return this;\n    }\n\n    /**\n     * Specifies the ground overlay's zIndex, i.e., the order in which it will be drawn. See the\n     * documentation at the top of this class for more information about zIndex.\n     *","sourceCodeStart":309,"sourceCodeEnd":345,"githubUrl":"https://github.com/microg/GmsCore/blob/157c9d86ac46c195a86c2f15ab55c84036223f95/play-services-maps/src/main/java/com/google/android/gms/maps/model/GroundOverlayOptions.java#L309-L345","documentation":"GroundOverlayOptions.transparency(float) throws IllegalArgumentException when the transparency value is outside the range [0..1]. Transparency is a normalized float: 0 is fully opaque (the default) and 1 is fully invisible. Values such as percentages (0-100) or signed/clamped-escaped floats are rejected.","triggerScenarios":"Calling transparency(50) (percentage instead of fraction), transparency(-0.1f), transparency(1.5f), or passing a computed/interpolated value that drifts outside [0..1].","commonSituations":"Confusing percentage-based opacity (0-100) with the library's 0-1 convention; animating transparency with an easing function that overshoots; storing transparency in config with inconsistent scaling.","solutions":["Convert percentages: if the value is 0-100, divide by 100 before calling transparency().","Clamp into range: transparency = Math.max(0f, Math.min(1f, value));","Remember the semantic is transparency, not opacity — invert if your source value is opacity (1 - opacity)."],"exampleFix":"// before\nfloat pct = 75; // percent opaque\noptions.transparency(pct); // throws\n\n// after\nfloat opacity = 75f / 100f;\noptions.transparency(1f - opacity); // 0.25 transparency, clamped to [0..1]","handlingStrategy":"validation","validationCode":"if (t < 0f || t > 1f) t = Math.max(0f, Math.min(1f, t));","typeGuard":"float clampTransparency(float t) { return Math.max(0f, Math.min(1f, t)); }","tryCatchPattern":"try {\n    options.transparency(value);\n} catch (IllegalArgumentException e) {\n    options.transparency(clampTransparency(value));\n}","preventionTips":["Convert 0-100 percentages to 0-1 fractions before use.","Clamp animated/interpolated values.","Distinguish transparency from opacity and normalize inputs consistently."],"tags":["maps","android","ground-overlay","range-check"],"backgroundTag":"value-out-of-range","analyzedSha":"157c9d86ac46c195a86c2f15ab55c84036223f95","analyzedAt":"2026-09-06T17:27:33.892Z","contentChangedAt":"2026-09-06T17:27:33.892Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}