Skip to content

Commit 3ff4b3f

Browse files
mikebmclmikebmcl
committed
Numerous cleanups and changes. Added clip-props.tex. Filled in the other props files. Some cleanups regarding overflows. render_props is now surface_props. Cleanup to make setters in constexpr classes constexpr, but some may still be out there. Removed color_stop_group from color-stop.tex. Still need to obliterate color_stop_group from the brush class and replace it with the new API. Renamed tiling to wrap_mode. Started revising gradients.tex and everything else brush related. Eliminated remaining references to factories (other than the pre-defined colors in rgba_color). Created a new local-tables.tex table, libiotwodtab3e that sets each of the three columns to be a third of the whole. It's used in surface.tex. Renamed render-props.tex to surface-props.tex. Lots of work to do still for brushes. May switch to surfaces since the revisions there are close to done (excluding enums). ALL ENUMS NEED TO BE LOOKED AT AND MODIFIED WHERE NECESSARY.
1 parent 674328e commit 3ff4b3f

23 files changed

+944
-932
lines changed

‎source/brush-type.tex‎

Lines changed: 5 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -4,8 +4,7 @@
44
\rSec1 [brushtype.summary] {\tcode{brush_type} Summary}
55

66
\pnum
7-
The \tcode{brush_type} enum class denotes which brush factory was used
8-
to form a \tcode{brush} object.
7+
The \tcode{brush_type} enum class denotes the type of a \tcode{brush} object.
98

109
\pnum
1110
See Table~\ref{tab:brushtype.meanings} for the meaning of each
@@ -40,15 +39,15 @@
4039
\\ \capsep
4140
\endhead
4241
\tcode{solid_color}
43-
& The \tcode{brush} object was created from a \tcode{solid_color_brush_factory} object.
42+
& The \tcode{brush} object is a solid color brush.
4443
\\
4544
\tcode{surface}
46-
& The \tcode{brush} object was created from a \tcode{surface_brush_factory} object.
45+
& The \tcode{brush} object is a surface brush.
4746
\\
4847
\tcode{linear}
49-
& The \tcode{brush} object was created from a \tcode{linear_brush_factory} object.
48+
& The \tcode{brush} object is a linear gradient brush.
5049
\\
5150
\tcode{radial}
52-
& The \tcode{brush} object was created from a \tcode{radial_brush_factory} object.
51+
& The \tcode{brush} object is a radial gradient brush.
5352
\\
5453
\end{libreqtab2}

‎source/brush.tex‎

Lines changed: 27 additions & 154 deletions
Original file line numberDiff line numberDiff line change
@@ -8,23 +8,20 @@
88
The class \tcode{brush} describes an opaque wrapper for a graphics data graphics resource.
99

1010
\pnum
11-
A \tcode{brush} object shall be usable with any \tcode{surface} or \tcode{surface}-derived object.
11+
A \tcode{brush} object is usable with any \tcode{surface} or \tcode{surface}-derived object.
1212

1313
\pnum
14-
A \tcode{brush} object's graphics data is immutable. It is observable only by the effect that it produces when the brush is used as a Source Brush (\ref{surface.sourcebrush}) or as a Mask Brush (\ref{surface.rendering} and \ref{surface.masking}).
14+
A \tcode{brush} object's graphics data is immutable. It is observable only by the effect that it produces when the brush is used as a Source Brush or as a Mask Brush (\ref{surface.rendering.brushes}).
1515

1616
\pnum
17-
A \tcode{brush} object also has a tiling value of type \tcode{tiling}, a filter value of type \tcode{filter}, and a transformation matrix of type \tcode{matrix_2d}.
17+
A \tcode{brush} object has an immutable \tcode{brush_type} value which indicates which type of brush it is (Table~\ref{tab:brushtype.meanings}).
1818

1919
\pnum
20-
A \tcode{brush} object has an immutable \tcode{brush_type} observable state data value which indicates which type of brush it is (Table~\ref{tab:brushtype.meanings}).
21-
22-
\pnum
23-
The \tcode{brush} object's graphics data may have less precision than the graphics data of the brush factory object from which it was created.
20+
As a result of technological limitations and considerations, \tcode{brush} object's graphics data can have less precision than the data from which it was created.
2421

2522
\pnum
2623
\enterexample
27-
Several graphics and rendering technologies that are currently widely used store individual color and alpha channel data as 8-bit unsigned normalized integer values while the \tcode{double} type that is used by the \tcode{rgba_color} class for individual color and alpha is often a 64-bit value. It is precisely these situations which the preceding paragraph is intended to address.
24+
Several graphics and rendering technologies that are currently widely used typically store individual color and alpha channel data as 8-bit unsigned normalized integer values while the \tcode{double} type that is used by the \tcode{rgba_color} class for individual color and alpha is often a 64-bit value. As such, it is possible for a loss of precision when transforming the 64-bit channel data of an \tcode{rgba_color} object to the 8-bit channel data that is commonly used internally in such graphics and rendering technologies.
2825
\exitexample
2926

3027
\rSec1 [brush.synopsis] {\tcode{brush} synopsis}
@@ -34,38 +31,20 @@
3431
class brush {
3532
public:
3633
// \ref{brush.cons}, construct/copy/move/destroy:
37-
brush() = delete;
38-
brush(const brush&);
39-
brush& operator=(const brush&);
40-
brush(brush&& other) noexcept;
41-
brush& operator=(brush&& other) noexcept;
42-
43-
brush(const rgba_color& c);
44-
brush(const rgba_color& c, error_code& ec) noexcept;
45-
template <class Allocator>
34+
explicit brush(const rgba_color& c);
35+
template <class InputIterator>
4636
brush(const vector_2d& begin, const vector_2d& end,
47-
const color_stop_group<Allocator>& csg);
48-
template <class Allocator>
37+
InputIterator first, InputIterator last);
4938
brush(const vector_2d& begin, const vector_2d& end,
50-
const color_stop_group<Allocator>& csg, error_code& ec) noexcept;
51-
template <class Allocator>
39+
initializer_list<color_stop> il);
40+
template <class InputIterator>
5241
brush(const circle& start, const circle& end,
53-
const color_stop_group<Allocator>& csg);
54-
template <class Allocator>
42+
InputIterator first, InputIterator last);
5543
brush(const circle& start, const circle& end,
56-
const color_stop_group<Allocator>& csg, error_code& ec) noexcept;
57-
brush(image_surface&& img);
58-
brush(image_surface&& img, error_code& ec) noexcept;
59-
60-
// \ref{brush.modifiers}, modifiers:
61-
void tiling(experimental::io2d::tiling e) noexcept;
62-
void filter(experimental::io2d::filter f) noexcept;
63-
void matrix(const matrix_2d& m) noexcept;
44+
initializer_list<color_stop> il);
45+
explicit brush(image_surface&& img);
6446

6547
// \ref{brush.observers}, observers:
66-
experimental::io2d::tiling tiling() const noexcept;
67-
experimental::io2d::filter filter() const noexcept;
68-
matrix_2d matrix() const noexcept;
6948
brush_type type() const noexcept;
7049
};
7150
} } } }
@@ -85,22 +64,22 @@
8564
\rSec2 [brush.sampling.color] {Sampling from a color brush}
8665

8766
\pnum
88-
When \tcode{b} is a color brush, then when sampling from \tcode{b}, the visual data returned shall always be the visual data equivalent \tcode{rgba_code} which was passed in when \tcode{b} was created, regardless of the point which is to be sampled and regardless of the return values of \tcode{b.tiling()}, \tcode{b.filter()}, and \tcode{b.matrix()}.
67+
When \tcode{b} is a color brush, then when sampling from \tcode{b}, the visual data returned shall always be the visual data equivalent \tcode{rgba_code} which was passed in when \tcode{b} was created, regardless of the point which is to be sampled and regardless of the return values of \tcode{b.wrap_mode()}, \tcode{b.filter()}, and \tcode{b.matrix()}.
8968

9069
\rSec2 [brush.sampling.linear] {Sampling from a linear gradient brush}
9170

9271
\pnum
93-
When \tcode{b} is a linear gradient brush, then when sampling from \tcode{b}, the visual data returned shall be from the point \tcode{pt} in the rendered linear gradient, where \tcode{pt} is the return value when passing the point to be sampled to \tcode{b.matrix().transform_coords} and the rendered linear gradient is created as specified by \ref{gradients.linear} and \ref{gradients.sampling}, taking into account the value of \tcode{b.tiling()}.
72+
When \tcode{b} is a linear gradient brush, then when sampling from \tcode{b}, the visual data returned shall be from the point \tcode{pt} in the rendered linear gradient, where \tcode{pt} is the return value when passing the point to be sampled to \tcode{b.matrix().transform_coords} and the rendered linear gradient is created as specified by \ref{gradients.linear} and \ref{gradients.sampling}, taking into account the value of \tcode{b.wrap_mode()}.
9473

9574
\rSec2 [brush.sampling.radial] {Sampling from a radial gradient brush}
9675

9776
\pnum
98-
When \tcode{b} is a radial gradient brush, then when sampling from \tcode{b}, the visual data returned shall be from the point \tcode{pt} in the rendered radial gradient, where \tcode{pt} is the return value when passing the point to be sampled to \tcode{b.matrix().transform_coords} and the rendered radial gradient is created as specified by \ref{gradients.radial} and \ref{gradients.sampling}, taking into account the value of \tcode{b.tiling()}.
77+
When \tcode{b} is a radial gradient brush, then when sampling from \tcode{b}, the visual data returned shall be from the point \tcode{pt} in the rendered radial gradient, where \tcode{pt} is the return value when passing the point to be sampled to \tcode{b.matrix().transform_coords} and the rendered radial gradient is created as specified by \ref{gradients.radial} and \ref{gradients.sampling}, taking into account the value of \tcode{b.wrap_mode()}.
9978

10079
\rSec2 [brush.sampling.surface] {Sampling from a surface brush}
10180

10281
\pnum
103-
When \tcode{b} is a surface brush, then when sampling from \tcode{b}, the visual data returned shall be from the point \tcode{pt} in the graphics data of the brush, where \tcode{pt} is the return value when passing the point to be sampled to \tcode{b.matrix().transform_coords}, taking into account the value of \tcode{b.tiling()} and \tcode{b.filter()}.
82+
When \tcode{b} is a surface brush, then when sampling from \tcode{b}, the visual data returned shall be from the point \tcode{pt} in the graphics data of the brush, where \tcode{pt} is the return value when passing the point to be sampled to \tcode{b.matrix().transform_coords}, taking into account the value of \tcode{b.wrap_mode()} and \tcode{b.filter()}.
10483

10584
\rSec1 [brush.cons] {\tcode{brush} constructors and assignment operators}
10685

@@ -121,7 +100,7 @@
121100
The brush's brush type shall be set to the value \tcode{brush_type::solid_color}.
122101

123102
\pnum
124-
The brush's tiling shall be set to the value \tcode{experimental::io2d::tiling::none}.
103+
The brush's wrap mode shall be set to the value \tcode{experimental::io2d::wrap_mode::none}.
125104

126105
\pnum
127106
The brush's filter shall be set to the value \tcode{experimental::io2d::filter::fast}.
@@ -168,7 +147,7 @@
168147
The brush's brush type shall be set to the value \tcode{brush_type::linear}.
169148

170149
\pnum
171-
The brush's tiling shall be set to the value \tcode{experimental::io2d::tiling::none}.
150+
The brush's wrap mode shall be set to the value \tcode{experimental::io2d::wrap_mode::none}.
172151

173152
\pnum
174153
The brush's filter shall be set to the value \tcode{experimental::io2d::filter::fast}.
@@ -196,55 +175,34 @@
196175

197176
\indexlibrary{\idxcode{brush}!constructor}
198177
\begin{itemdecl}
199-
template <class Allocator>
178+
template <class InputIterator>
200179
brush(const circle& start, const circle& end,
201-
const color_stop_group<Allocator>& csg);
202-
template <class Allocator>
203-
brush(const circle& start, const circle& end,
204-
const color_stop_group<Allocator>& csg, error_code& ec) noexcept;
180+
InputIterator first, InputIterator last);
205181
\end{itemdecl}
206182
\begin{itemdescr}
207183
\pnum
208184
\effects
209185
Constructs an object of type \tcode{brush}.
210186

211187
\pnum
212-
The brush shall be a radial gradient brush.
188+
The brush is a radial gradient brush.
213189

214190
\pnum
215-
The brush's brush type shall be set to the value \tcode{brush_type::radial}.
216191

217192
\pnum
218-
The brush's tiling shall be set to the value \tcode{experimental::io2d::tiling::none}.
219-
220-
\pnum
221-
The brush's filter shall be set to the value \tcode{experimental::io2d::filter::fast}.
222-
223-
\pnum
224-
The brush's transformation matrix shall be set to the value \tcode{matrix_2d::init_identity()}.
193+
The brush's brush type is \tcode{brush_type::radial}.
225194

226195
\pnum
227196
The graphics data of the brush is nominally as specified the introductory paragraphs of \ref{gradients} and in \ref{gradients.radial}. Its color stops shall be the values contained in \tcode{csg}. However because the graphics data is not directly observable, it is \unspecnorm what data is stored and how it is stored, provided that the results of sampling from the brush are the same as if the brush's graphics data was stored as specified in the introductory paragraphs of \ref{gradients} and in \ref{gradients.radial}.
228197

229198
\pnum
230199
\remarks
231200
Sampling from this brush shall produce the results specified in \ref{brush.sampling.radial}.
232-
233-
\pnum
234-
\throws
235-
As specified in Error reporting (\ref{\iotwod.err.report}).
236-
237-
\pnum
238-
\errors
239-
\tcode{errc::not_enough_memory} if there was a failure to allocate memory.
240-
241-
\tcode{io2d_error::invalid_status} if there was a failure to allocate a resource other than memory.
242201
\end{itemdescr}
243202

244203
\indexlibrary{\idxcode{brush}!constructor}
245204
\begin{itemdecl}
246-
brush(image_surface&& img);
247-
brush(image_surface&& img, error_code& ec) noexcept;
205+
explicit brush(image_surface&& img);
248206
\end{itemdecl}
249207
\begin{itemdescr}
250208
\pnum
@@ -253,110 +211,25 @@
253211
Constructs an object of type \tcode{brush}.
254212

255213
\pnum
256-
The brush shall be a surface brush.
257-
258-
\pnum
259-
The brush's brush type shall be set to the value \tcode{brush_type::surface}.
214+
The brush is a surface brush.
260215

261216
\pnum
262-
The brush's tiling shall be set to the value \tcode{experimental::io2d::tiling::none}.
217+
The brush's brush type is \tcode{brush_type::surface}.
263218

264219
\pnum
265-
The brush's filter shall be set to the value \tcode{experimental::io2d::filter::good}.
266-
267-
\pnum
268-
The brush's transformation matrix shall be set to the value \tcode{matrix_2d::init_identity()}.
220+
The graphics data of the brush is nominally the same as the graphics data of the \underlyingimagesurface of \tcode{img}. However because the graphics data is not directly observable, it is \unspecnorm what data is stored and how it is stored.
269221

270222
\pnum
271223
The graphics data of the brush shall be the \underlyingimagesurface of \tcode{img}.
272224

273225
\pnum
274226
\remarks
275227
Sampling from this brush shall produce the results specified in \ref{brush.sampling.surface}.
276-
277-
\pnum
278-
\throws
279-
As specified in Error reporting (\ref{\iotwod.err.report}).
280-
281-
\pnum
282-
\errors
283-
\tcode{errc::not_enough_memory} if there was a failure to allocate memory.
284-
285-
\tcode{io2d_error::invalid_status} if there was a failure to allocate a resource other than memory.
286-
\end{itemdescr}
287-
288-
\rSec1 [brush.modifiers]{\tcode{brush} modifiers}
289-
290-
\indexlibrary{\idxcode{brush}!\idxcode{tiling}}
291-
\indexlibrary{\idxcode{tiling}!\idxcode{brush}}
292-
\begin{itemdecl}
293-
void tiling(experimental::io2d::tiling e) noexcept;
294-
\end{itemdecl}
295-
\begin{itemdescr}
296-
\pnum
297-
\effects
298-
The brush's tiling shall be set to the value of \tcode{e}.
299-
\end{itemdescr}
300-
301-
\indexlibrary{\idxcode{brush}!\idxcode{filter}}
302-
\indexlibrary{\idxcode{filter}!\idxcode{brush}}
303-
\begin{itemdecl}
304-
void filter(experimental::io2d::filter f) noexcept;
305-
\end{itemdecl}
306-
\begin{itemdescr}
307-
\pnum
308-
\effects
309-
The brush's filter shall be set to the value \tcode{f}.
310-
\end{itemdescr}
311-
312-
\indexlibrary{\idxcode{brush}!\idxcode{matrix}}
313-
\indexlibrary{\idxcode{matrix}!\idxcode{brush}}
314-
\begin{itemdecl}
315-
void matrix(const matrix_2d& m) noexcept;
316-
\end{itemdecl}
317-
\begin{itemdescr}
318-
\pnum
319-
\effects
320-
The brush's transformation matrix shall be set to the value \tcode{m}.
321228
\end{itemdescr}
322229

323230
\rSec1 [brush.observers]{\tcode{brush} observers}
324231

325-
\indexlibrary{\idxcode{brush}!\idxcode{tiling}}
326-
\indexlibrary{\idxcode{tiling}!\idxcode{brush}}
327-
\begin{itemdecl}
328-
experimental::io2d::tiling tiling() const noexcept;
329-
\end{itemdecl}
330-
\begin{itemdescr}
331-
\pnum
332-
\returns
333-
The value of brush's tiling.
334-
\end{itemdescr}
335-
336-
\indexlibrary{\idxcode{brush}!\idxcode{filter}}
337-
\indexlibrary{\idxcode{filter}!\idxcode{brush}}
338-
\begin{itemdecl}
339-
experimental::io2d::filter filter() const noexcept;
340-
\end{itemdecl}
341-
\begin{itemdescr}
342-
\pnum
343-
\returns
344-
The value of the brush's filter.
345-
\end{itemdescr}
346-
347-
\indexlibrary{\idxcode{brush}!\idxcode{matrix}}
348-
\indexlibrary{\idxcode{matrix}!\idxcode{brush}}
349-
\begin{itemdecl}
350-
matrix_2d matrix() const noexcept;
351-
\end{itemdecl}
352-
\begin{itemdescr}
353-
\pnum
354-
\returns
355-
The value of the brush's transformation matrix.
356-
\end{itemdescr}
357-
358232
\indexlibrary{\idxcode{brush}!\idxcode{type}}
359-
\indexlibrary{\idxcode{type}!\idxcode{brush}}
360233
\begin{itemdecl}
361234
brush_type type() const noexcept;
362235
\end{itemdecl}

‎source/brushes.tex‎

Lines changed: 27 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
\rSec0 [brushes] {Brushes}
44

55
\pnum
6-
Brushes serve as sources of visual data for composing operations.
6+
Brushes contain visual data and serve as sources of visual data for rendering and composing operations.
77

88
There are four types of brushes:
99
\begin{itemize}
@@ -14,33 +14,49 @@
1414
\end{itemize}
1515

1616
\pnum
17-
A brush has its own coordinate space (\ref{surface.coordinatespaces}), which is by default the standard coordinate space. It is controlled by a \tcode{matrix_2d} value.
17+
Once a brush is created, its visual data is immutable.
1818

1919
\pnum
20-
It possesses a \tcode{filter} value and a \tcode{tiling} value, which combine to determine the visual data value returned when a composing operation samples a brush.
20+
\enternote
21+
While copy and move operations along with a swap operation can change the visual data that a brush contains, the visual data itself is not modified.
22+
\exitnote
2123

2224
\pnum
23-
The \tcode{filter} value determines the value returned by a brush when a composing operation samples a brush. When the visual data of the brush is a pixmap and the point the composing operation requests does not directly correspond to the exact coordinate of a pixel within the pixmap, the \tcode{filter} value is used to determine the value of the visual data that is returned. If the visual data of the brush is not a pixmap, the \tcode{filter} value is irrelevant.
25+
A brush is used either as a Source Brush or a Mask Brush (\ref{surface.brushes}).
2426

2527
\pnum
26-
The \tcode{tiling} value controls what happens when a composing operation needs to sample from a point that is outside of the bounds of the brush.
28+
When a brush is used in a rendering and composing operation, a \tcode{brush_props} object or \tcode{mask_props} object can modify the result of sampling the brush.
2729

2830
%\pnum
29-
%Excluding brushes created using a \tcode{solid_color_brush_factory} object, brushes produce very different composing operation results depending on the values of their mutable state.
31+
%A brush has its own coordinate space.
32+
%
33+
%\pnum
34+
%If it is being used as a Source Brush, it is the Brush Coordinate Space (\ref{surface.coordinatespaces}).
35+
%
36+
%\pnum
37+
%If it is being used as a Mask Brush, it is the Mask Coordinate Space (\ref{surface.coordinatespaces}).
38+
%
39+
%\pnum
40+
%It possesses a \tcode{filter} value and a \tcode{wrap_mode} value, which combine to determine the visual data value returned when a composing operation samples a brush.
41+
%
42+
%\pnum
43+
%The \tcode{filter} value determines the value returned by a brush when a composing operation samples a brush. When the visual data of the brush is a pixmap and the point the composing operation requests does not directly correspond to the exact coordinate of a pixel within the pixmap, the \tcode{filter} value is used to determine the value of the visual data that is returned. If the visual data of the brush is not a pixmap, the \tcode{filter} value is irrelevant.
44+
%
45+
%\pnum
46+
%The \tcode{wrap_mode} value controls what happens when a composing operation needs to sample from a point that is outside of the bounds of the brush.
3047
%
31-
3248
\pnum
33-
Color brushes produce the same sampling result regardless of their coordinate space, \tcode{filter}, and \tcode{tiling}. They are unbounded and as such always produce the \tcode{rgba_color} value they were created with when sampled from, regardless of the requested point.
49+
Solid color brushes are unbounded and as such always produce the same visual data when sampled from, regardless of the requested point.
3450

3551
\pnum
36-
Linear gradient and radial gradient brushes share similarities with each other that are not shared by the other types of brushes. This is discussed in more detail below (\ref{gradients}).
52+
Linear gradient and radial gradient brushes share similarities with each other that are not shared by the other types of brushes. This is discussed in more detail elsewhere (\ref{gradients}).
3753

3854
\pnum
39-
Surface brushes take an \tcode{image_surface} object and use it as the source of the brush's visual data.
55+
Surface brushes are constructed from an \tcode{image_surface} object. Their visual data is a pixmap, which has implications on sampling from the brush that are not present in the other brush types.
4056

4157
\addtocounter{SectionDepthBase}{1}
4258
\input{gradients}
43-
\input{tiling}
59+
\input{wrap-mode}
4460
\input{filter}
4561
\input{brush-type}
4662
\input{color-stop}

0 commit comments

Comments
 (0)