1pod::Prima::gp-problemsU(s3e)r Contributed Perl Documentaptoido:n:Prima::gp-problems(3)
2
6 Prima::gp-problems - Problems, questionable or intricate topics in 2-D
7 Graphics
8
10 One of the most important goals of the Prima project is portability
11 between different operating systems. Independently to efforts in
12 keeping Prima internal code that it behaves more or less identically on
13 different platforms, it is always possible to write non-portable and
14 platform-dependent code. Here are some guidelines and suggestions for
15 2-D graphics programming.
16
18 A compliant display is expected to have minimal set of capabilities,
19 that programmer can rely upon. Following items are guaranteedly
20 supported by Prima:
21 Minimal capabilities
23 Distinct black and white colors
24 Line widths 0 and 1
26 One monospaced font
28 Solid fill
30 rop::Copy and rop::NoOper
32 Plotting primitives
34 SetPixel,GetPixel
35 Line,PolyLine,PolyLines
37 Ellipse,Arc,Chord,Sector
39 Rectangle
41 FillPoly
43 FillEllipse,FillChord,FillSector
45 TextOut
47 PutImage,GetImage
49 Information services
51 GetTextWidth,GetFontMetrics,GetCharacterABCWidths
52 GetImageBitsLayout
54 Properties
56 color
57 backColor
59 rop
61 backRop
63 lineWidth
65 lineJoin
67 lineStyle
69 fillPattern
71 fillPolyWinding
73 textOpaque
75 clipRect
77 All these properties must be present, however it is not required
79 for them to be changeable. Even if an underlying platform-specific
80 code can only support one mode for a property, it have to follow
81 all obligations for the mode. For example, if platform supports
82 full functionality for black color but limited functionality for
83 the other colors, the wrapping code should not allow color property
84 to be writable then.
85
87 Colors
88 Black and white colors on paletted displays
89 Due the fact that paletted displays employ indexed color
90 representation, 'black' and 'white' indices are not always 0 and
91 2^n-1, so result of raster image operations may look garbled (X).
92 Win32 protects themselves from this condition by forcing white to
93 be the last color in the system palette.
94 Example: if white color on 8-bit display occupies palette index 15
96 then desired masking effect wouldn't work for xoring transparent
97 areas with cl::White.
98 Workaround: Use two special color constants cl::Clear and cl::Set,
100 that represent all zeros and all ones values for bit-sensitive
101 raster operations.
102 Black might be not 0, and white not 0xffffff
104 This inevident issue happens mostly on 15- and 16-bits pixel
105 displays. Internal color representation for the white color on a
106 15-color display ( assuming R,G and B are 5-bits fields) is
107 11111000 11111000 11111000
109 --R----- --G----- --B-----
110 that equals to 0xf8f8f8. (All)
112 Advise: do not check for 'blackness' and 'whiteness' merely by
114 comparing a pixel value.
115 Pixel value coding
117 Status: internal
118 It is not checked how does Prima behave when a pixel value and a
120 platform integer use different bit and/or byte priority (X).
121 Filled shapes
123 Dithering
124 If a non-solid pattern is selected and a background and/or a
125 foreground color cannot be drawn as a solid, the correct rendering
126 requires correspondingly 3 or 4 colors. Some rendering engines
127 (Win9X) fail to produce correct results.
128 Pattern offset
130 For a widget that contains a pattern-filled shape, its picture will
131 be always garbled after scrolling, because it is impossible to
132 provide an algorithm for a correct rendering without a prior
133 knowledge of the widget nature. (All)
134 Workaround: Do not use patterned backgrounds. Since the same
136 effect is visible on dithered backgrounds, routine check for pure
137 color might be applied.
138 Lines
140 Line caps over patterned styles
141 It is not clear, whether gaps between dashes should be a multiple
142 to a line width or not. For example, lp::DotDot looks almost as a
143 solid line when lineWidth is over 10 if the first (non-multiple)
144 tactic is chosen. From the other hand it is hardly possible to
145 predict the plotting strategy from a high-level code. The problem
146 is related more to Prima design rather than to a platform-specific
147 code. (All)
148 Workaround: use predefined patterns (lp::XXX)
150 Dithering
152 Dithering might be not used for line plotting. (Win9X)
153 Arcs and circles
155 Drawing is dependent in X11 on an X servers - different X servers
156 do different plotting strategies on small (less than 3 pixels)
157 diameters. Current version is adapted best to the latest (2010)
158 Xorg capabilities. See discussion on CPAN bug
159 https://rt.cpan.org/Ticket/Display.html?id=62972 .
160 Fonts
162 Font metric inconsistency
163 A font is loaded by request with one size, but claims another
164 afterwards.(X).
165 Impact: system-dependent font description may not match to Prima's.
167 Advise: do not try to deduce Prima font metrics from system-
169 dependent ones and vice versa.
170 Transparent plotting
172 No internal function for drawing transparent bitmaps (like fonts).
173 Therefore, if a font emulation is desired, special ROPs cannot be
174 reproduced. (Win9X, WinNT)
175 Impact: font emulation is laborsome, primarily because the glyphs
177 have to be plotted by consequential anding and xoring a bitmap.
178 Full spectrum of the raster operations cannot be achieved with this
179 approach.
180 Kerning
182 Prima do not use text kernings, nor encourages underlying platform-
183 specific code to use it - primarily because of its complexity.
184 From the other hand, sometimes glyph position cannot be determined
185 correctly if no information for the text kerning is provided.
186 (Win9X)
187 Text background
189 If a text is drawn with non-CopyPut raster operation, text
190 background is not expected to be mixed with symbols - however this
191 is hardly reachable, so results differs for different platforms.
192 Text background may be only drawn with pure ( non-dithered ) color
194 (Win9X,WinNT) - but this is (arguably) a more correct behavior.
195 Advise: Do not use ::rop2 and text background for special effects
197 Internal platform features
199 Font change notification is not provided. (X)
200 Raster fonts cannot be synthesized (partly X)
202 Raster operations ( ROPs)
204 Background raster operations are not supported (X,Win9X,WinNT) and
205 foreground ROPs have limited number of modes (X). Not all ROPs can be
206 emulated for certain primitives, like fonts, complex shapes, and
207 patterned shapes.
208 It is yet unclear which primitives have to support ROPs, - like
210 FloodFill and SetPixel. Behavior of the current implementation is that
211 they do not.
212 On win32, BlendAlpha call is used to implement ropSrcOver function on
214 32-bit ARGB drawables. It yields results different to the ones yielded
215 by X11/Xrender, that implements the canonic formula by Porter and Duff.
216 Arcs
218 Platforms tend to produce different results for angles outside 0 and
219 2pi. Although Prima assures that correct plotting would be performed
220 for any angle, minor inconsistencies may be noticed. If emulating,
221 note that 2 and 4-pi arcs are not the same - for example, they look
222 differently with rop::Xor.
223 Palettes
225 Static palettes
226 Some displays are unable to change their hardware palette, so
227 detecting 8- or 4- bits display doesn't automatically mean that
228 palette is writable.(X)
229 Widget::palette
231 Widget::palette property is used for explicit declaration of extra
232 color needs for a widget. The request might be satisfacted in
233 different ways, or might not at all. It is advisable not to rely
234 onto platform behavior for the palette operations.
235 Dynamic palette change
237 It is possible (usually on 8-bits displays) for a display to change
238 asynchronously its hardware palette in order to process different
239 color requests. All platforms behave differently.
240 Win9X/WinNT - only one top-level window at a time and its direct
242 children ( not ::clipOwner(0)) can benefit from using
243 Widget::palette. System palette is switched every time as different
244 windows moved to the front.
245 X - Any application can easily ruin system color table. Since this
247 behavior is such by design, no workaround can be applied here.
248 Bitmaps
250 Invalid scaling
251 Scaling is invalid (Win9X) or not supported (X). Common mistake is
252 to not take into an account the fractional pixels that appear when
253 the scaling factor is more than 1. This mistake can be observed in
254 Win9X.
255 Workaround: none
257 Large scale factors
259 Request for drawing a bitmap might fail if large scaling factor is
260 selected. (Win9X,WinNT). This effect is obviously due that fact
261 that these platforms scale the bitmap into a memory before the
262 plotting takes place.
263 Layering
265 On win32, layered widgets with pixels assigned zero alpha component,
266 will not receive mouse events.
267
269 Windows 9X
270 Amount of GDI objects can not exceed some unknown threshold -
271 experiments show that 128 objects is safe enough.
272 No transformations.
274 Color cursor creation routine is broken.
276 Filled shapes are broken.
278 X
280 No transformations
281 No bitmap scaling
283 No font rotation
285 No GetPixel, FloodFill ( along with some other primitives)
287 White is not 2^n-1 on n-bit paletted displays (tested on XFree86).
289 Filled shapes are broken.
291 Color bitmaps cannot be drawn onto mono bitmaps.
293
295 Win32
296 Plotting speed of DeviceBitmaps is somewhat less on 8-bit displays than
297 Images and Icons. It is because DeviceBitmaps are bound to their
298 original palette, so putting a DeviceBitmap onto different palette
299 drawable employs inefficient algorithms in order to provide correct
300 results.
301 X
303 Image that was first drawn on a paletted Drawable always seen in 8
304 colors if drawn afterwards on a Drawable with the different palette.
305 That is because the image has special cache in display pixel format,
306 but cache refresh on every PutImage call is absolutely inappropriate
307 (although technically possible). It is planned to fix the problem by
308 checking the palette difference for every PutImage invocation. NB -
309 the effect is seen on dynamic color displays only.
310
312 Dmitry Karasik, <dmitry@karasik.eu.org>.
313
315 Prima
316perl v5.28.1 2019-02-02 pod::Prima::gp-problems(3)