trusty (3) Prima::gp-problems.3.gz
NAME
Prima::gp-problems - Problems, questionable or intricate topics in 2-D Graphics
Introduction
One of the most important goals of the Prima project is portability between different operating systems.
Independently to efforts in keeping Prima internal code that it behaves more or less identically on
different platforms, it is always possible to write non-portable and platform-dependent code. Here are
some guidelines and suggestions for 2-D graphics programming.
Minimal display capabilities
A compliant display is expected to have minimal set of capabilities, that programmer can rely upon.
Following items are guaranteedly supported by Prima:
Minimal capabilities
Distinct black and white colors
Line widths 0 and 1
One monospaced font
Solid fill
rop::Copy and rop::NoOper
Plotting primitives
SetPixel,GetPixel
Line,PolyLine,PolyLines
Ellipse,Arc,Chord,Sector
Rectangle
FillPoly
FillEllipse,FillChord,FillSector
TextOut
PutImage,GetImage
Information services
GetTextWidth,GetFontMetrics,GetCharacterABCWidths
GetImageBitsLayout
Properties
color
backColor
rop
backRop
lineWidth
lineJoin
lineStyle
fillPattern
fillPolyWinding
textOpaque
clipRect
All these properties must be present, however it is not required for them to be changeable. Even if
an underlying platform-specific code can only support one mode for a property, it have to follow all
obligations for the mode. For example, if platform supports full functionality for black color but
limited functionality for the other colors, the wrapping code should not allow color property to be
writable then.
Inevident issues
Colors
Black and white colors on paletted displays
Due the fact that paletted displays employ indexed color representation, 'black' and 'white' indices
are not always 0 and 2^n-1, so result of raster image operations may look garbled (X). Win32 and
OS/2 protect themselves from this condition by forcing white to be the last color in the system
palette.
Example: if white color on 8-bit display occupies palette index 15 then desired masking effect
wouldn't work for xoring transparent areas with cl::White.
Workaround: Use two special color constants cl::Clear and cl::Set, that represent all zeros and all
ones values for bit-sensitive raster operations.
Black might be not 0, and white not 0xffffff
This inevident issue happens mostly on 15- and 16-bits pixel displays. Internal color representation
for the white color on a 15-color display ( assuming R,G and B are 5-bits fields) is
11111000 11111000 11111000
--R----- --G----- --B-----
that equals to 0xf8f8f8. (All)
Advise: do not check for 'blackness' and 'whiteness' merely by comparing a pixel value.
Pixel value coding
Status: internal
It is not checked how does Prima behave when a pixel value and a platform integer use different bit
and/or byte priority (X).
Filled shapes
Dithering
If a non-solid pattern is selected and a background and/or a foreground color cannot be drawn as a
solid, the correct rendering requires correspondingly 3 or 4 colors. Some rendering engines (Win9X)
fail to produce correct results.
Overfill effect
In complex shapes ( FillPoly, for example) the platform renderer can fill certain areas two or more
times. Whereas the effect is not noticeable with rop::CopyPut, the other raster operations (like
rop::Xor) produce incorrect picture. (OS/2)
NB - has nothing in common with the fill winding rule.
Workaround: Do not use raster operations with complex filled shapes
Pattern offset
For a widget that contains a pattern-filled shape, its picture will be always garbled after
scrolling, because it is impossible to provide an algorithm for a correct rendering without a prior
knowledge of the widget nature. (All)
Workaround: Do not use patterned backgrounds. Since the same effect is visible on dithered
backgrounds, routine check for pure color might be applied.
Lines
Line caps over patterned styles
It is not clear, whether gaps between dashes should be a multiple to a line width or not. For
example, lp::DotDot looks almost as a solid line when lineWidth is over 10 if the first (non-
multiple) tactic is chosen. From the other hand it is hardly possible to predict the plotting
strategy from a high-level code. The problem is related more to Prima design rather than to a
platform-specific code. (All)
Workaround: use predefined patterns (lp::XXX)
Line joins
Joint areas may be drawn two (or more) times - the problem emerges if logical ROP (rop::Xor) is
chosen.(OS/2)
Dithering
Dithering might be not used for line plotting. (Win9X)
Fonts
Font metric inconsistency
A font is loaded by request with one size, but claims another afterwards.(OS/2, X).
Impact: system-dependent font description may not match to Prima's.
Advise: do not try to deduce Prima font metrics from system-dependent ones and vice versa.
Transparent plotting
No internal function for drawing transparent bitmaps (like fonts). Therefore, if a font emulation is
desired, special ROPs cannot be reproduced. (OS/2, Win9X, WinNT)
Impact: font emulation is laborsome, primarily because the glyphs have to be plotted by consequential
anding and xoring a bitmap. Full spectrum of the raster operations cannot be achieved with this
approach.
Kerning
Prima do not use text kernings, nor encourages underlying platform-specific code to use it -
primarily because of its complexity. From the other hand, sometimes glyph position cannot be
determined correctly if no information for the text kerning is provided. (Win9X)
Fractional text position
If the font glyphs have fractional widths, it might be observed that letters may change their
position in a string.
Example: A set of glyphs has width of 8.6 pixels for each symbol. If the string "abcd" is drawn at
position 0, then black part of "d" starts at 25th pixel, but if "cd" is drawn at 17th, as it supposed
to be if the integer arithmetics is used, it starts at 24th pixel. (OS/2)
Solution: Do not rely to Drawable::get_text_width information, because it always returns integer
value, but to Drawable::get_font_abc, which returns real values.
Text background
If a text is drawn with non-CopyPut raster operation, text background is not expected to be mixed
with symbols - however this is hardly reachable, so results differs for different platforms.
Text background may be only drawn with pure ( non-dithered ) color (Win9X,WinNT) - but this is
(arguably) a more correct behavior.
Advise: Do not use ::rop2 and text background for special effects
Internal platform features
Font change notification is not provided. (X, OS/2)
Raster fonts cannot be synthesized (OS/2, partly X)
Raster operations ( ROPs)
Background raster operations are not supported (X,Win9X,WinNT) and foreground ROPs have limited number of
modes (OS/2,X). Not all ROPs can be emulated for certain primitives, like fonts, complex shapes, and
patterned shapes.
It is yet unclear which primitives have to support ROPs, - like FloodFill and SetPixel. Behavior of the
current implementation is that they do not.
Arcs
Platforms tend to produce different results for angles outside 0 and 2pi. Although Prima assures that
correct plotting would be performed for any angle, minor inconsistencies may be noticed. If emulating,
note that 2 and 4-pi arcs are not the same - for example, they look differently with rop::Xor.
Palettes
Static palettes
Some displays are unable to change their hardware palette, so detecting 8- or 4- bits display doesn't
automatically mean that palette is writable.(X)
Widget::palette
Widget::palette property is used for explicit declaration of extra color needs for a widget. The
request might be satisfacted in different ways, or might not at all. It is advisable not to rely onto
platform behavior for the palette operations.
Dynamic palette change
It is possible (usually on 8-bits displays) for a display to change asynchronously its hardware
palette in order to process different color requests. All platforms behave differently.
Win9X/WinNT - only one top-level window at a time and its direct children ( not ::clipOwner(0)) can
benefit from using Widget::palette. System palette is switched every time as different windows moved
to the front.
OS/2 - not implemented, but in principle the same as under win32.
X - Any application can easily ruin system color table. Since this behavior is such by design, no
workaround can be applied here.
Bitmaps
Invalid scaling
Scaling is invalid (Win9X) or not supported (X). Common mistake is to not take into an account the
fractional pixels that appear when the scaling factor is more than 1. This mistake can be observed in
Win9X.
Workaround: none
Large scale factors
Request for drawing a bitmap might fail if large scaling factor is selected. (OS/2,Win9X,WinNT).
This effect is obviously due that fact that these platforms scale the bitmap into a memory before the
plotting takes place.
Platform-specific peculiarities
OS/2
Some ROPs are ambiguous - SRCTRANSPARENT, for example. Some times they work, some times they don't. The
particular behavior depends on a video driver.
Circles cannot be drawn using an even diameter.
Fast GDI operations on HWND_DESKTOP may be delayed, thus GetPixel may return invalid pixel values.
Windows 9X
Amount of GDI objects can not exceed some unknown threshold - experiments show that 128 objects is safe
enough.
No transformations.
Color cursor creation routine is broken.
Filled shapes are broken.
X
No transformations
No bitmap scaling
No font rotation
No GetPixel, FloodFill ( along with some other primitives)
White is not 2^n-1 on n-bit paletted displays (tested on XFree86).
Filled shapes are broken.
Color bitmaps cannot be drawn onto mono bitmaps.
Implementation notes
OS/2
Palettes are not implemented
Win32
Plotting speed of DeviceBitmaps is somewhat less on 8-bit displays than Images and Icons. It is because
DeviceBitmaps are bound to their original palette, so putting a DeviceBitmap onto different palette
drawable employs inefficient algorithms in order to provide correct results.
X
Image that was first drawn on a paletted Drawable always seen in 8 colors if drawn afterwards on a
Drawable with the different palette. That is because the image has special cache in display pixel format,
but cache refresh on every PutImage call is absolutely inappropriate (although technically possible). It
is planned to fix the problem by checking the palette difference for every PutImage invocation. NB - the
effect is seen on dynamic color displays only.
AUTHOR
Dmitry Karasik, <dmitry@karasik.eu.org>.
SEE ALSO
Prima