Man Linux: Main Page and Category List


       Prima::gp-problems - Problems, questionable or intricate topics in 2-D


       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








       Information services













           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

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

       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 might be not used for line plotting. (Win9X)

       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

           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.

       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.

           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.

       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.

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

       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

           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

       Some ROPs are ambiguous - SRCTRANSPARENT, for example. Some times they
       work, some times they don’t. The particular behavior depends on a video

       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.

       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

       Palettes are not implemented

       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

       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.


       Dmitry Karasik, <>.