=head1 NAME
Prima::gp-problems - Problems, questionable or intricate topics in 2-D Graphics
=head1 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.
=head1 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:
=over
=item Minimal capabilities
Distinct black and white colors
Line widths 0 and 1
One monospaced font
Solid fill
rop::Copy and rop::NoOper
=item Plotting primitives
SetPixel,GetPixel
Line,PolyLine,PolyLines
Ellipse,Arc,Chord,Sector
Rectangle
FillPoly
FillEllipse,FillChord,FillSector
TextOut
PutImage,GetImage
=item Information services
GetTextWidth,GetFontMetrics,GetCharacterABCWidths
GetImageBitsLayout
=item 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.
=back
=head1 Inevident issues
=head2 Colors
=over
=item 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 protects 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.
=item 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.
=item 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).
=back
=head2 Filled shapes
=over
=item 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.
=item 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.
=back
=head2 Lines
=over
=item 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)
=item Dithering
Dithering might be not used for line plotting. (Win9X)
=item Arcs and circles
Drawing is dependent in X11 on an X servers - different X servers do different plotting
strategies on small (less than 3 pixels) diameters. Current version is adapted best to the
latest (2010) Xorg capabilities. See discussion on CPAN bug https://rt.cpan.org/Ticket/Display.html?id=62972 .
=back
=head2 Fonts
=over
=item Font metric inconsistency
A font is loaded by request with one size,
but claims another afterwards.(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.
=item Transparent plotting
No internal function for drawing transparent bitmaps (like fonts).
Therefore, if a font emulation is desired, special ROPs cannot be
reproduced. (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.
=item 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)
=item 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
=item Internal platform features
Font change notification is not provided. (X)
Raster fonts cannot be synthesized (partly X)
=back
=head2 Raster operations ( ROPs)
Background raster operations are not supported (X,Win9X,WinNT) and
foreground ROPs have limited number of modes (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.
On win32, BlendAlpha call is used to implement ropSrcOver function on 32-bit
ARGB drawables. It yields results different to the ones yielded by X11/Xrender,
that implements the canonic formula by Porter and Duff.
=head2 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.
=head2 Palettes
=over
=item 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)
=item 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.
=item 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.
X - Any application can easily ruin system color table.
Since this behavior is such by design, no workaround can be
applied here.
=back
=head2 Bitmaps
=over
=item 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
=item Large scale factors
Request for drawing a bitmap might fail
if large scaling factor is selected. (Win9X,WinNT).
This effect is obviously due that fact that these platforms
scale the bitmap into a memory before the plotting takes place.
=back
=head2 Layering
On win32, layered widgets with pixels assigned zero alpha component, will not
receive mouse events.
=head1 Platform-specific peculiarities
=head2 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.
=head2 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.
=head1 Implementation notes
=head2 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.
=head2 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.
=head1 AUTHOR
Dmitry Karasik, E<lt>dmitry@karasik.eu.orgE<gt>.
=head1 SEE ALSO
L<Prima>