1pod::Prima::gp-problemsU(s3e)r Contributed Perl Documentaptoido:n:Prima::gp-problems(3)
2
3
4

NAME

6       Prima::gp-problems - Problems, questionable or intricate topics in 2-D
7       Graphics
8

Introduction

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

Minimal display capabilities

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
22       Minimal capabilities
23           Distinct black and white colors
24
25           Line widths 0 and 1
26
27           One monospaced font
28
29           Solid fill
30
31           rop::Copy and rop::NoOper
32
33       Plotting primitives
34           SetPixel,GetPixel
35
36           Line,PolyLine,PolyLines
37
38           Ellipse,Arc,Chord,Sector
39
40           Rectangle
41
42           FillPoly
43
44           FillEllipse,FillChord,FillSector
45
46           TextOut
47
48           PutImage,GetImage
49
50       Information services
51           GetTextWidth,GetFontMetrics,GetCharacterABCWidths
52
53           GetImageBitsLayout
54
55       Properties
56           color
57
58           backColor
59
60           rop
61
62           backRop
63
64           lineWidth
65
66           lineJoin
67
68           lineStyle
69
70           miterLimit
71
72           fillPattern
73
74           fillPolyWinding
75
76           textOpaque
77
78           clipRect
79
80           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

Inevident issues

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
97           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
101           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
105       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
110            11111000 11111000 11111000
111            --R----- --G----- --B-----
112
113           that equals to 0xf8f8f8. (All)
114
115           Advise: do not check for 'blackness' and 'whiteness' merely by
116           comparing a pixel value.
117
118       Pixel value coding
119           Status: internal
120
121           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
124   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
131       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
137           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
142   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
152           Workaround: use predefined patterns (lp::XXX)
153
154       Dithering
155           Dithering might be not used for line plotting. (Win9X)
156
157       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
164       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
168   Fonts
169       Font metric inconsistency
170           A font is loaded by request with one size, but claims another
171           afterwards.(X).
172
173           Impact: system-dependent font description may not match to Prima's.
174
175           Advise: do not try to deduce Prima font metrics from system-
176           dependent ones and vice versa.
177
178       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
183           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
188       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
195       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
200           Text background may be only drawn with pure ( non-dithered ) color
201           (Win9X,WinNT) - but this is (arguably) a more correct behavior.
202
203           Advise: Do not use ::rop2 and text background for special effects
204
205       Internal platform features
206           Font change notification is not provided. (X)
207
208           Raster fonts cannot be synthesized (partly X)
209
210   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
216       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
220       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
224   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
231   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
237       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
243       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
248           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
253           X - Any application can easily ruin system color table.  Since this
254           behavior is such by design, no workaround can be applied here.
255
256   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
263           Workaround: none
264
265       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
271   Layering
272       On win32, layered widgets with pixels assigned zero alpha component,
273       will not receive mouse events.
274

Platform-specific peculiarities

276   Windows 9X
277       Amount of GDI objects can not exceed some unknown threshold -
278       experiments show that 128 objects is safe enough.
279
280       No transformations.
281
282       Color cursor creation routine is broken.
283
284       Filled shapes are broken.
285
286   X
287       No transformations
288
289       No bitmap scaling
290
291       No font rotation
292
293       No GetPixel, FloodFill ( along with some other primitives)
294
295       White is not 2^n-1 on n-bit paletted displays (tested on XFree86).
296
297       Filled shapes are broken.
298
299       Color bitmaps cannot be drawn onto mono bitmaps.
300
301       Miter limit is read-only.
302

Implementation notes

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
311   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

AUTHOR

321       Dmitry Karasik, <dmitry@karasik.eu.org>.
322

SEE ALSO

324       Prima
325
326
327
328perl v5.32.0                      2020-07-28        pod::Prima::gp-problems(3)
Impressum