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 miterLimit
71 fillPattern
73 fillPolyWinding
75 textOpaque
77 clipRect
79 All these properties must be present, however it is not required
81 for them to be changeable. Even if an underlying platform-specific
82 code can only support one mode for a property, it have to follow
83 all obligations for the mode. For example, if platform supports
84 full functionality for black color but limited functionality for
85 the other colors, the wrapping code should not allow color property
86 to be writable then.
87
89 Colors
90 Black and white colors on paletted displays
91 Due the fact that paletted displays employ indexed color
92 representation, 'black' and 'white' indices are not always 0 and
93 2^n-1, so result of raster image operations may look garbled (X).
94 Win32 protects themselves from this condition by forcing white to
95 be the last color in the system palette.
96 Example: if white color on 8-bit display occupies palette index 15
98 then desired masking effect wouldn't work for xoring transparent
99 areas with cl::White.
100 Workaround: Use two special color constants cl::Clear and cl::Set,
102 that represent all zeros and all ones values for bit-sensitive
103 raster operations.
104 Black might be not 0, and white not 0xffffff
106 This inevident issue happens mostly on 15- and 16-bits pixel
107 displays. Internal color representation for the white color on a
108 15-color display ( assuming R,G and B are 5-bits fields) is
109 11111000 11111000 11111000
111 --R----- --G----- --B-----
112 that equals to 0xf8f8f8. (All)
114 Advise: do not check for 'blackness' and 'whiteness' merely by
116 comparing a pixel value.
117 Pixel value coding
119 Status: internal
120 It is not checked how does Prima behave when a pixel value and a
122 platform integer use different bit and/or byte priority (X).
123 Filled shapes
125 Dithering
126 If a non-solid pattern is selected and a background and/or a
127 foreground color cannot be drawn as a solid, the correct rendering
128 requires correspondingly 3 or 4 colors. Some rendering engines
129 (Win9X) fail to produce correct results.
130 Pattern offset
132 For a widget that contains a pattern-filled shape, its picture will
133 be always garbled after scrolling, because it is impossible to
134 provide an algorithm for a correct rendering without a prior
135 knowledge of the widget nature. (All)
136 Workaround: Do not use patterned backgrounds or use
138 "fillPatternOffset" property. Since the same effect is visible on
139 dithered backgrounds, routine check for pure color might be
140 applied.
141 Lines
143 Line caps over patterned styles
144 It is not clear, whether gaps between dashes should be a multiple
145 to a line width or not. For example, lp::DotDot looks almost as a
146 solid line when lineWidth is over 10 if the first (non-multiple)
147 tactic is chosen. From the other hand it is hardly possible to
148 predict the plotting strategy from a high-level code. The problem
149 is related more to Prima design rather than to a platform-specific
150 code. (All)
151 Workaround: use predefined patterns (lp::XXX)
153 Dithering
155 Dithering might be not used for line plotting. (Win9X)
156 Arcs and circles
158 Drawing is dependent in X11 on an X servers - different X servers
159 do different plotting strategies on small (less than 3 pixels)
160 diameters. Current version is adapted best to the latest (2010)
161 Xorg capabilities. See discussion on CPAN bug
162 https://rt.cpan.org/Ticket/Display.html?id=62972 .
163 Miter limiting
165 Change of miter limiting is not supported by X11 by design, it has
166 a constant value of 10.43 there.
167 Fonts
169 Font metric inconsistency
170 A font is loaded by request with one size, but claims another
171 afterwards.(X).
172 Impact: system-dependent font description may not match to Prima's.
174 Advise: do not try to deduce Prima font metrics from system-
176 dependent ones and vice versa.
177 Transparent plotting
179 No internal function for drawing transparent bitmaps (like fonts).
180 Therefore, if a font emulation is desired, special ROPs cannot be
181 reproduced. (Win9X, WinNT)
182 Impact: font emulation is laborsome, primarily because the glyphs
184 have to be plotted by consequential anding and xoring a bitmap.
185 Full spectrum of the raster operations cannot be achieved with this
186 approach.
187 Kerning
189 Prima do not use text kernings, nor encourages underlying platform-
190 specific code to use it - primarily because of its complexity.
191 From the other hand, sometimes glyph position cannot be determined
192 correctly if no information for the text kerning is provided.
193 (Win9X)
194 Text background
196 If a text is drawn with non-CopyPut raster operation, text
197 background is not expected to be mixed with symbols - however this
198 is hardly reachable, so results differs for different platforms.
199 Text background may be only drawn with pure ( non-dithered ) color
201 (Win9X,WinNT) - but this is (arguably) a more correct behavior.
202 Advise: Do not use ::rop2 and text background for special effects
204 Internal platform features
206 Font change notification is not provided. (X)
207 Raster fonts cannot be synthesized (partly X)
209 Raster operations ( ROPs)
211 Background raster operations are not supported (X,Win9X,WinNT) and
212 foreground ROPs have limited number of modes (X). Not all ROPs can be
213 emulated for certain primitives, like fonts, complex shapes, and
214 patterned shapes.
215 It is yet unclear which primitives have to support ROPs, - like
217 FloodFill and SetPixel. Behavior of the current implementation is that
218 they do not.
219 On win32, BlendAlpha call is used to implement ropSrcOver function on
221 32-bit ARGB drawables. It yields results different to the ones yielded
222 by X11/Xrender, that implements the canonic formula by Porter and Duff.
223 Arcs
225 Platforms tend to produce different results for angles outside 0 and
226 2pi. Although Prima assures that correct plotting would be performed
227 for any angle, minor inconsistencies may be noticed. If emulating,
228 note that 2 and 4-pi arcs are not the same - for example, they look
229 differently with rop::Xor.
230 Palettes
232 Static palettes
233 Some displays are unable to change their hardware palette, so
234 detecting 8- or 4- bits display doesn't automatically mean that
235 palette is writable.(X)
236 Widget::palette
238 Widget::palette property is used for explicit declaration of extra
239 color needs for a widget. The request might be satisfacted in
240 different ways, or might not at all. It is advisable not to rely
241 onto platform behavior for the palette operations.
242 Dynamic palette change
244 It is possible (usually on 8-bits displays) for a display to change
245 asynchronously its hardware palette in order to process different
246 color requests. All platforms behave differently.
247 Win9X/WinNT - only one top-level window at a time and its direct
249 children ( not ::clipOwner(0)) can benefit from using
250 Widget::palette. System palette is switched every time as different
251 windows moved to the front.
252 X - Any application can easily ruin system color table. Since this
254 behavior is such by design, no workaround can be applied here.
255 Bitmaps
257 Invalid scaling
258 Scaling is invalid (Win9X) or not supported (X). Common mistake is
259 to not take into an account the fractional pixels that appear when
260 the scaling factor is more than 1. This mistake can be observed in
261 Win9X.
262 Workaround: none
264 Large scale factors
266 Request for drawing a bitmap might fail if large scaling factor is
267 selected. (Win9X,WinNT). This effect is obviously due that fact
268 that these platforms scale the bitmap into a memory before the
269 plotting takes place.
270 Layering
272 On win32, layered widgets with pixels assigned zero alpha component,
273 will not receive mouse events.
274
276 Windows 9X
277 Amount of GDI objects can not exceed some unknown threshold -
278 experiments show that 128 objects is safe enough.
279 No transformations.
281 Color cursor creation routine is broken.
283 Filled shapes are broken.
285 X
287 No transformations
288 No bitmap scaling
290 No font rotation
292 No GetPixel, FloodFill ( along with some other primitives)
294 White is not 2^n-1 on n-bit paletted displays (tested on XFree86).
296 Filled shapes are broken.
298 Color bitmaps cannot be drawn onto mono bitmaps.
300 Miter limit is read-only.
302
304 Win32
305 Plotting speed of DeviceBitmaps is somewhat less on 8-bit displays than
306 Images and Icons. It is because DeviceBitmaps are bound to their
307 original palette, so putting a DeviceBitmap onto different palette
308 drawable employs inefficient algorithms in order to provide correct
309 results.
310 X
312 Image that was first drawn on a paletted Drawable always seen in 8
313 colors if drawn afterwards on a Drawable with the different palette.
314 That is because the image has special cache in display pixel format,
315 but cache refresh on every PutImage call is absolutely inappropriate
316 (although technically possible). It is planned to fix the problem by
317 checking the palette difference for every PutImage invocation. NB -
318 the effect is seen on dynamic color displays only.
319
321 Dmitry Karasik, <dmitry@karasik.eu.org>.
322
324 Prima
325perl v5.34.0 2021-07-22 pod::Prima::gp-problems(3)