Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
pod::Prima::gp-problemUser Contributed Perl Documentpod::Prima::gp-problems(3)

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

       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.

       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)

       Dithering
	   Dithering might be not used for line	plotting. (Win9X)

       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 .

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

       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.

       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)

       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)

	   Raster fonts	cannot be synthesized (partly X)

   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.

   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.

	   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. (Win9X,WinNT).  This effect is obviously due that fact
	   that	these platforms	scale the bitmap into a	memory before the
	   plotting takes place.

   Layering
       On win32, layered widgets with pixels assigned zero alpha component,
       will not	receive	mouse events.

Platform-specific peculiarities
   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
   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

perl v5.24.1			  2017-02-27	    pod::Prima::gp-problems(3)

NAME | Introduction | Minimal display capabilities | Inevident issues | Platform-specific peculiarities | Implementation notes | AUTHOR | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=pod::Prima::gp-problems&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help