Skip to content

[css-images-4][css-backgrounds-4] Added stripes() function #7029

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 13 commits into from
Nov 5, 2022
Merged
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
tweak/rearrange stripes() text; add sum<1 behavior
  • Loading branch information
tabatkins authored and SebastianZ committed Oct 9, 2022
commit 1f982db53e0386f21f986fa898cca8585d70a562
97 changes: 72 additions & 25 deletions css-images-4/Overview.bs
Original file line number Diff line number Diff line change
Expand Up @@ -1907,36 +1907,83 @@ Color Stop “Fixup”</h4>
1D Image Values: the ''stripes()'' notation {#stripes}
======================================================

The ''stripes()'' function allows to define a number of stripes of
different colors with different widths.

The syntax for ''1d-image'' and ''stripes()'' is defined as:
While most <<image>> values represent a 2-dimensional image,
and <<color>> can be thought of as a "0-dimensional" image
(unvarying in either axis),
there are some contexts where a 1-dimensional image makes sense,
specifying colors along a <dfn export>paint line</dfn>
without defining a <em>direction</em> for the line.
The <<1d-image>> type represents such images.

Some contexts will define how they use the <<1d-image>> as a 1-dimensional value;
for example, in 'border-color',
the given colors paint "outwards" from each side of the border.
When used generically as an <<image>>, a <<1d-image>> is painted identically to a ''linear-gradient(to bottom, ...)''
using the [=paint line=] as its [=gradient line=].

<pre class=prod>
<dfn>&lt;1d-image></dfn> = <<stripes()>>
<dfn>stripes()</dfn> = stripes( [ <<color>> && [ <<length-percentage>> | <<flex>>]? ]# )
</pre>

The function represents a 1-dimensional image generated by a list of colors
and an optional thickness for each of them.

A <<percentage>> or <<flex>> value refers to the total length of the image
in the used context.
The <<percentage>> must be between ''0%'' and ''100%'' inclusive;
any other value is invalid.

If the thickness of a stripe is omitted, it is interpreted as ''1fr''.

If not defined differently by the context the function is used in, the
stripes are painted from top to bottom and tiled horizontally. If the size
of the painting area exceeds the total thickness of the stripes, the
remaining area is painted transparently. I.e. it behaves as if there was an
additional last ''transparent'' stripe. If the size of the painting area
is smaller than the total thickness of the stripes, the stripes are clipped
starting from the last defined color.

The computed value of this function is the [=specified value=] with all
<<color>>s computed '1fr' values removed.

The ''stripes()'' function defines a 1d-image
as a number of colored stripes with different widths.

Each comma-separated entry defines a solid-color stripe,
each placed end-to-end on the [=paint line=] in the order given,
with the specified <<color>> and thickness.
If the thickness is omitted,
it defaults to ''1fr''.

In each entry, a <<percentage>> is relative to the |painting area|
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this is very confusing, the "painting area" is never defined but since it's an area it seems to be 2D. How to resolve a 1D <length-percentage> relatively to a 2D area?

Should this refer to the "length of the paint line" instead?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

and must be between ''0%'' and ''100%'' inclusive
or else the function is invalid.
A <<flex>> is evaluated as a fraction of the |painting area|
relative to the total sum of <<flex>> entries in the function,
after subtracting the thickness of any non-<<flex>> entries
(flooring the subtraction result at zero).
If the sum of <<flex>> values is less than 1fr,
the result of the subtraction is multiplied by the sum's value
before being distributed.

<div class=example>
For example,
''stripes(red 1fr, green 2fr, blue 100px)``
with a |painting area| of ''400px''
will result in a 100px red stripe and 200px green stripe,
giving red 1 share and green 2 shares of the 300px remaining
after subtracting blue's 100px from the 400px total.

On the other hand,
''stripes(red .1fr, green .2fr, blue 100px)``
with a |painting area| of ''400px''
will instead give a 30px red stripe and 60px green stripe,
followed by 100px of blue and then 210px of transparent.
The 300px of leftover space is multiplied by .3,
the value of the sum of the <<flex>> values,
to obtain only 90px,
which is then distributed in the 1:2 ratio
the <<flex>> values would dictate.

(This is similar to how [=flex layout=] deals with small <<flex>> sums on a line,
and ensures smoothly continuous behavior
as the <<flex>> values approach zero.)
</div>


The |painting area| is defined by the context in which the ''stripes()'' function is used.
If used generically as an <<image>>,
the |painting area| is the height of the [=concrete image size=].
Comment on lines +1969 to +1970
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What does "If used generically as an <image>" mean, if <1d-image> is no longer an <image>?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That was just a left-over. I've removed the whole paragraph now as it didn't add any additional information anymore.

Thanks for the hint!

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You removed another used generically as an <<image>>, but not this one.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.


If the sum thickness of the stripes is smaller than the |painting area|,
the [=paint line=] is [=transparent black=] for its remaining length,
as if a final ''transparent'' argument were given.
If the sum thickness is larger,
any stripes or portions thereof that would be past the end of the [=paint line=] have no effect.

The computed value of this function is the [=specified value=]
with all <<color>>s computed
and all <<length-percentage>>s absolutized and computed to the extent possible.

<!--
██████ ████ ████████ ████ ██ ██ ██████
Expand Down