Migrate from `LegacyColor` to `bevy_color::Color` #12163

alice-i-cecile · 2024-02-27T19:12:10Z

Objective

As part of the migration process we need to a) see the end effect of the migration on user ergonomics b) check for serious perf regressions c) actually migrate the code
To accomplish this, I'm going to attempt to migrate all of the remaining user-facing usages of LegacyColor in one PR, being careful to keep a clean commit history.
Fixes bevy_color migration plan #12056.

Solution

I've chosen to use the polymorphic Color type as our standard user-facing API.

Incidental improvements to ease migration:

added Color::srgba_u8, Color::srgba_from_array and friends
added set_alpha, is_fully_transparent and is_fully_opaque to the Alpha trait
add and immediately deprecate (lol) Color::rgb and friends in favor of more explicit and consistent Color::srgb
standardized on white and black for most example text colors
added vector field traits to LinearRgba: ~~Add, Sub, AddAssign, SubAssign,~~ Mul<f32> and Div<f32>. Multiplications and divisions do not scale alpha. Add and Sub have been cut from this PR.
added LinearRgba and Srgba RED/GREEN/BLUE
added LinearRgba_to_f32_array and LinearRgba::to_u32

Migration Guide

Bevy's color types have changed! Wherever you used a bevy::render::Color, a bevy::color::Color is used instead.

These are quite similar! Both are enums storing a color in a specific color space (or to be more precise, using a specific color model). However, each of the different color models now has its own type.

TODO...

Color::rgba, Color::rgb, Color::rbga_u8, Color::rgb_u8, Color::rgb_from_array are now Color::srgba, Color::srgb, Color::srgba_u8, Color::srgb_u8 and Color::srgb_from_array.
Color::set_a and Color::a is now Color::set_alpha and Color::alpha. These are part of the Alpha trait in bevy_color.
Color::is_fully_transparent is now part of the Alpha trait in bevy_color
Color::r, Color::set_r, Color::with_r and the equivalents for g, b h, s and l have been removed due to causing silent relatively expensive conversions. Convert your Color into the desired color space, perform your operations there, and then convert it back into a polymorphic Color enum.
Color::hex is now Srgba::hex. Call .into or construct a Color::Srgba variant manually to convert it.
WireframeMaterial, ExtractedUiNode, ExtractedDirectionalLight, ExtractedPointLight, ExtractedSpotLight and ExtractedSprite now store a LinearRgba, rather than a polymorphic Color
Color::rgb_linear and Color::rgba_linear are now Color::linear_rgb and Color::linear_rgba
The various CSS color constants are no longer stored directly on Color. Instead, they're defined in the Srgba color space, and accessed via bevy::color::palettes::css. Call .into() on them to convert them into a Color for quick debugging use, and consider using the much prettier tailwind palette for prototyping.
The LIME_GREEN color has been renamed to LIMEGREEN to comply with the standard naming.
Vector field arithmetic operations on Color (add, subtract, multiply and divide by a f32) have been removed. Instead, convert your colors into LinearRgba space, and perform your operations explicitly there. This is particularly relevant when working with emissive or HDR colors, whose color channel values are routinely outside of the ordinary 0 to 1 range.
Color::as_linear_rgba_f32 has been removed. Call LinearRgba::to_f32_array instead, converting if needed.
Color::as_linear_rgba_u32 has been removed. Call LinearRgba::to_u32 instead, converting if needed.
Several other color conversion methods to transform LCH or HSL colors into float arrays or Vec types have been removed. Please reimplement these externally or open a PR to re-add them if you found them particularly useful.
Various methods on Color such as rgb or hsl to convert the color into a specific color space have been removed. Convert into LinearRgba, then to the color space of your choice.
Various implicitly-converting color value methods on Color such as r, g, b or h have been removed. Please convert it into the color space of your choice, then check these properties.
Color no longer implements AsBindGroup. Store a LinearRgba internally instead to avoid conversion costs.

crates/bevy_gizmos/src/arcs.rs

crates/bevy_gizmos/src/arrows.rs

crates/bevy_gizmos/src/aabb.rs

bushrat011899

Looking good so far!

crates/bevy_gizmos/src/gizmos.rs

examples/2d/bounding_2d.rs

crates/bevy_gizmos/src/aabb.rs

bushrat011899 · 2024-02-27T22:22:29Z

crates/bevy_gizmos/src/arcs.rs

    ) -> Arc2dBuilder<'_, 'w, 's, T> {
        Arc2dBuilder {
            gizmos: self,
            position,
            direction_angle,
            arc_angle,
            radius,
-            color,
+            color: color.into(),


Might need to do some performance testing to confirm, but we probably need to go back over the various From implementations an annotate them with #[inline]. I'm not sure how good the Rust compiler is at inlining these tiny functions.

Yeah agreed. I want to do perf testing towards the end of this process.

@cart

# Objective As suggested in #12163 by @cart, we should add convenience constructors to `bevy_color::Color` to match the existing API (easing migration pain) and generally improve ergonomics. ## Solution - Add `const fn Color::rgba(red, green, blue, alpha)` and friends, which directly construct the appropriate variant. - Add `const fn Color::rgb(red, green, blue)` and friends, which impute and alpha value of 1.0. - Add `const BLACK, WHITE, NONE` to `Color`. These are stored in `LinearRgba` to reduce pointless conversion costs and inaccuracy. - Changed the default `Color` from `Srgba::WHITE` to the new linear equivalent for the same reason. --------- Co-authored-by: Alice Cecile <[email protected]>

crates/bevy_gizmos/src/gizmos.rs

# Objective - bloom is not working anymore in 3d after #12163 ## Solution - Fix a copy paste mistake and use emissive for the emissive

# Objective - Copy paste error in #12163 ## Solution - Fix it

# Objective - Since #12163 example lightmaps is more dull <img width="1280" alt="Screenshot 2024-03-02 at 23 04 36" src="https://github.com/bevyengine/bevy/assets/8672791/7736f420-b9c5-4870-93f6-b5b992c4768a"> ## Solution - Use a srgba color, as it was before: https://github.com/bevyengine/bevy/blob/b24ab2e9fba5b81aba15da97b6551a4e99aad40c/examples/3d/lightmaps.rs#L39 https://github.com/bevyengine/bevy/blob/b24ab2e9fba5b81aba15da97b6551a4e99aad40c/crates/bevy_render/src/color/mod.rs#L132 <img width="1280" alt="Screenshot 2024-03-02 at 23 05 09" src="https://github.com/bevyengine/bevy/assets/8672791/451187ed-8612-456f-ad25-180d5f774188">

) # Objective - bloom is not working anymore in 3d after bevyengine#12163 ## Solution - Fix a copy paste mistake and use emissive for the emissive

…e#12266) # Objective - Copy paste error in bevyengine#12163 ## Solution - Fix it

# Objective - Since bevyengine#12163 example lightmaps is more dull <img width="1280" alt="Screenshot 2024-03-02 at 23 04 36" src="https://github.com/bevyengine/bevy/assets/8672791/7736f420-b9c5-4870-93f6-b5b992c4768a"> ## Solution - Use a srgba color, as it was before: https://github.com/bevyengine/bevy/blob/b24ab2e9fba5b81aba15da97b6551a4e99aad40c/examples/3d/lightmaps.rs#L39 https://github.com/bevyengine/bevy/blob/b24ab2e9fba5b81aba15da97b6551a4e99aad40c/crates/bevy_render/src/color/mod.rs#L132 <img width="1280" alt="Screenshot 2024-03-02 at 23 05 09" src="https://github.com/bevyengine/bevy/assets/8672791/451187ed-8612-456f-ad25-180d5f774188">

[12163](bevyengine/bevy#12163) bevy_color was created and Color handling has changed. Specifically Color::as_linear_rgba_f32 has been removed. LinearRgba is now its own type that can be accessed via [`linear()`](https://docs.rs/bevy/0.14.0-rc.2/bevy/color/enum.Color.html#method.linear) and then converted.

Addresses Bevy [12163](bevyengine/bevy#12163)

* Update to 0.14.0-rc.2 * [12997](bevyengine/bevy#12997): rename `multi-threaded` to `multi_threaded` * RenderAssets<Image> is now RenderAssets<GpuImage> Implemented in [12827](bevyengine/bevy#12827) * FloatOrd is now in bevy_math implemented in [12732](bevyengine/bevy#12732) * convert Transparent2d::dynamic_offset to extra_index [12889](bevyengine/bevy#12889) Gpu Frustum Culling removed the dynamic_offset of Transparent2d and it became `extra_index` with the special value `PhaseItemExtraIndex::NONE`, which indicates the `None` that was here previously * RenderPhase<Transparent2d> -> ViewSortedRenderPhases<Transparent2d> [12453](https://github.com/StarArawn/bevy_ecs_tilemap/pull/bevyengine/bevy#12453): Render phases are now binned or sorted. Following the changes in the `mesh2d_manual` [example](https://github.com/bevyengine/bevy/blob/ecdd1624f302c5f71aaed95b0984cbbecf8880b7/examples/2d/mesh2d_manual.rs#L357-L358): use the `ViewSortedRenderPhases` resource. * get_sub_app_mut is now an Option in [9202](https://github.com/StarArawn/bevy_ecs_tilemap/pull/bevyengine/bevy/pull/9202) SubApp access has changed * GpuImage::size f32 -> u32 via UVec2 [11698](bevyengine/bevy#11698) changed `GpuImage::size` to `UVec2`. Right above this, `Extent3d` does the same thing, so I'm taking a small leap and assuming can `as`. * GpuMesh::primitive_topology -> key_bits/BaseMeshPipeline [12791](bevyengine/bevy#12791) the `primitive_topology` field on `GpuMesh` was removed in favor of `key_bits` which can be constructed using `BaseMeshPipeline::from_primitive_topology` * RenderChunk2d::prepare requires &mut MeshVertexBufferLayouts now [12216](bevyengine/bevy#12216) introduced an argument `&mut MeshVertexBufferLayouts` to `get_mesh_vertex_buffer_layout`, which bevy_ecs_tilemap calls in `RenderChunk2d::prepare` * into_linear_f32 -> color.0.linear().to_f32_array(), [12163](bevyengine/bevy#12163) bevy_color was created and Color handling has changed. Specifically Color::as_linear_rgba_f32 has been removed. LinearRgba is now its own type that can be accessed via [`linear()`](https://docs.rs/bevy/0.14.0-rc.2/bevy/color/enum.Color.html#method.linear) and then converted. * Must specify type of VisibleEntities when accessing [12582](bevyengine/bevy#12582) divided `VisibleEntities` into separate lists. So now we have to specify which kind of entity we want. I think we want the Mesh here, and I think we can get rid of the `.index` calls on Entity since Entity [already compares bits](https://docs.rs/bevy_ecs/0.14.0-rc.2/src/bevy_ecs/entity/mod.rs.html#173) for optimized codegen purposes. Waiting to do that until the other changes are in though so as to not change functionality until post-upgrade. * app.world access is functions now - [9202](bevyengine/bevy#9202) changed world access to functions. [relevent line](https://github.com/bevyengine/bevy/pull/9202/files#diff-b2fba3a0c86e496085ce7f0e3f1de5960cb754c7d215ed0f087aa556e529f97fR640) - This also surfaced [12655](bevyengine/bevy#12655) which removed `Into<AssetId<T>>` for `Handle<T>`. using a reference or .id() is the solution here. * We don't need `World::cell`, and it doesn't exist anymore In [12551](bevyengine/bevy#12551) `WorldCell` was removed. ...but it turns out we don't need it or its replacement anyway. * examples error out unless this bevy bug is addressed with these features being added bevyengine/bevy#13728 * check_visibility is required for the entity that is renderable As a result of [12582](bevyengine/bevy#12582) `check_visibility` must be implemented for the "renderable" tilemap entities. Doing this is trivial by taking advantage of the existing `check_visibility` type arguments, which accept a [`QF: QueryFilter + 'static`](https://docs.rs/bevy/0.14.0-rc.2/bevy/render/view/fn.check_visibility.html). The same `QueryFilter`` is used when checking `VisibleEntities`. I've chosen `With<TilemapRenderSettings` because presumably if the entity doesn't have a `TilemapRenderSettings` then it will not be rendering, but this could be as sophisticated or simple as we want. For example `WithLight` is currently implemented as ```rust pub type WithLight = Or<(With<PointLight>, With<SpotLight>, With<DirectionalLight>)>; ``` * view.view_proj -> view.clip_from_world [13289](bevyengine/bevy#13489) introduced matrix naming changes, including `view_proj` which becomes `clip_from_world` * color changes to make tests runnable * clippy fix * Update Cargo.toml Co-authored-by: Rob Parrett <[email protected]> * Update Cargo.toml Co-authored-by: Rob Parrett <[email protected]> * final clippy fixes * Update Cargo.toml Co-authored-by: Rob Parrett <[email protected]> * Simplify async loading in ldtk/tiled helpers See Bevy #12550 * remove second allow lint * rc.3 bump * bump version for major release * remove unused features --------- Co-authored-by: Rob Parrett <[email protected]>

Addresses Bevy #12163 (bevyengine/bevy#12163)

Addresses Bevy [12163](bevyengine/bevy#12163)

Addresses Bevy #12163 (bevyengine/bevy#12163)

Alice Cecile added 2 commits February 27, 2024 13:38

Initial port of bevy_gizmos

b684a2a

Use impl Into<Color> args in gizmo builder methods

138e26c

alice-i-cecile added this to the 0.14 milestone Feb 27, 2024

viridia suggested changes Feb 27, 2024

View reviewed changes

crates/bevy_gizmos/src/arcs.rs Outdated Show resolved Hide resolved

crates/bevy_gizmos/src/arrows.rs Outdated Show resolved Hide resolved

crates/bevy_gizmos/src/arrows.rs Outdated Show resolved Hide resolved

cart reviewed Feb 27, 2024

View reviewed changes

crates/bevy_gizmos/src/aabb.rs Outdated Show resolved Hide resolved

bushrat011899 reviewed Feb 27, 2024

View reviewed changes

This was referenced Feb 27, 2024

Add a color_from_index randomized color palette generator #12170

Closed

bevy_color::Color convenience methods #12171

Merged

Alice Cecile added 3 commits February 27, 2024 19:29

Merge remote-tracking branch 'origin/main' into color-externals

fa8ad85

Use new convenience method in aabb.rs

21de265

Fix color constants in gizmo docs tests

e00b6bd

alice-i-cecile force-pushed the color-externals branch from ac56d67 to e00b6bd Compare February 28, 2024 00:43

Remove unused import

c07ec86

viridia approved these changes Feb 28, 2024

View reviewed changes

crates/bevy_gizmos/src/gizmos.rs Show resolved Hide resolved

Alice Cecile added 7 commits February 27, 2024 21:02

Add Color::srgba_u8

d0dedbd

Add Alpha::set_alpha method

9d1f0d5

Port over fog

3829efd

Port over ClearColor

ba58dc9

Add new deprecated Color convenience methods

8bc6c4f

Port wireframes

8e8d237

Port sprites

1df0713

mockersf mentioned this pull request Mar 1, 2024

bloom: use emissive instead of base_color for emissive #12220

Merged

This was referenced Mar 1, 2024

Various examples are incorrectly using GREEN #12225

Closed

Various examples are incorrectly using DARK_GRAY #12226

Closed

github-merge-queue bot pushed a commit that referenced this pull request Mar 1, 2024

bloom: use emissive instead of base_color for emissive (#12220)

4aca55d

# Objective - bloom is not working anymore in 3d after #12163 ## Solution - Fix a copy paste mistake and use emissive for the emissive

This was referenced Mar 2, 2024

fix example lightmaps after color migration #12265

Merged

PBR: use attenuation instead of base_color for attenuation #12266

Merged

github-merge-queue bot pushed a commit that referenced this pull request Mar 2, 2024

PBR: use attenuation instead of base_color for attenuation (#12266)

04ec105

# Objective - Copy paste error in #12163 ## Solution - Fix it

spectria-limina pushed a commit to spectria-limina/bevy that referenced this pull request Mar 9, 2024

PBR: use attenuation instead of base_color for attenuation (bevyengin…

a711b86

…e#12266) # Objective - Copy paste error in bevyengine#12163 ## Solution - Fix it

NthTensor mentioned this pull request Mar 19, 2024

Color maths 4 #12575

Merged

BD103 added the A-Color Color spaces and color math label May 3, 2024

alice-i-cecile removed the M-Needs-Release-Note Work that should be called out in the blog due to impact label May 27, 2024

ChristopherBiscardi mentioned this pull request Jun 7, 2024

Update to 0.14.0 StarArawn/bevy_ecs_tilemap#537

Merged

BD103 mentioned this pull request Jun 8, 2024

Color migration guide bevyengine/bevy-website#1379

Merged

zhaop added a commit to zhaop/bevy_editor_pls that referenced this pull request Jun 24, 2024

Use Color::srgb* instead of Color::rgb*

e1dfa81

Addresses Bevy [12163](bevyengine/bevy#12163)

zhaop added a commit to zhaop/bevy_editor_pls that referenced this pull request Jun 24, 2024

Use Color::srgb* instead of Color::rgb*

76f6f9e

Addresses Bevy [12163](bevyengine/bevy#12163)

zhaop mentioned this pull request Jun 24, 2024

Upgrade to Bevy 0.14.0-rc.* & upgrade egui-gizmo dependency jakobhellermann/bevy_editor_pls#107

Closed

zhaop added a commit to zhaop/bevy_editor_pls that referenced this pull request Jun 25, 2024

Update colors in examples from rgb* -> srgb*

a9e1867

Addresses Bevy [12163](bevyengine/bevy#12163)

zhaop mentioned this pull request Jul 6, 2024

Upgrade to Bevy 0.14 & upgrade egui-gizmo dependency jakobhellermann/bevy_editor_pls#110

Merged

5 tasks

zhaop added a commit to zhaop/transform-gizmo that referenced this pull request Jul 6, 2024

Use RED, LIME, BLUE from bevy::color::palettes::css & Into<Color>

bd36b85

Addresses Bevy #12163 (bevyengine/bevy#12163)

zhaop mentioned this pull request Jul 6, 2024

Upgrade to Bevy 0.14 urholaukkarinen/transform-gizmo#69

Merged

zhaop added a commit to zhaop/transform-gizmo that referenced this pull request Jul 6, 2024

Use RED, LIME, BLUE from bevy::color::palettes::css & Into<Color>

21c4df8

Addresses Bevy #12163 (bevyengine/bevy#12163)

zhaop added a commit to zhaop/bevy_editor_pls that referenced this pull request Jul 7, 2024

Change Color::rgb -> Color::srgb

43e6645

Addresses Bevy #12163 (bevyengine/bevy#12163)

jakobhellermann pushed a commit to jakobhellermann/bevy_editor_pls that referenced this pull request Aug 11, 2024

Use Color::srgb* instead of Color::rgb*

b474d0f

Addresses Bevy [12163](bevyengine/bevy#12163)

jakobhellermann pushed a commit to jakobhellermann/bevy_editor_pls that referenced this pull request Aug 11, 2024

Update colors in examples from rgb* -> srgb*

0306b09

Addresses Bevy [12163](bevyengine/bevy#12163)

jakobhellermann pushed a commit to jakobhellermann/bevy_editor_pls that referenced this pull request Aug 11, 2024

Change Color::rgb -> Color::srgb

cfe9065

Addresses Bevy #12163 (bevyengine/bevy#12163)

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Migrate from `LegacyColor` to `bevy_color::Color` #12163

Migrate from `LegacyColor` to `bevy_color::Color` #12163

alice-i-cecile commented Feb 27, 2024 •

edited

Loading

bushrat011899 left a comment

bushrat011899 Feb 27, 2024

alice-i-cecile Feb 27, 2024

Migrate from LegacyColor to bevy_color::Color #12163

Migrate from LegacyColor to bevy_color::Color #12163

Conversation

alice-i-cecile commented Feb 27, 2024 • edited Loading

Objective

Solution

Migration Guide

bushrat011899 left a comment

Choose a reason for hiding this comment

bushrat011899 Feb 27, 2024

Choose a reason for hiding this comment

alice-i-cecile Feb 27, 2024

Choose a reason for hiding this comment

Migrate from `LegacyColor` to `bevy_color::Color` #12163

Migrate from `LegacyColor` to `bevy_color::Color` #12163

alice-i-cecile commented Feb 27, 2024 •

edited

Loading