Raptor Gfx

Files in mozilla/gfx/src/os2/
(not yet checked in to mozilla.org cvs)

This is the cross-platform graphics engine, at the same sort of level as the GPI - it includes printing. Here's an approximate mapping, but do read the notes below.

Gfx object	GPI object	Implemented in
nsIRegion	HRGN	nsRegionOS2.cpp
nsIFontMetrics	FONTMETRICS FATTRS	nsFontMetricsOS2.cpp
nsIImage	HBITMAP	nsImageOS2.cpp
nsIDeviceContext	HDC	nsDeviceContextOS2.cpp
nsIRenderingContext (nsIDrawingSurface) nsDrawingSurfaceOS2	HPS	nsRenderingContextOS2.cpp nsDrawingSurfaceOS2.cpp

Device contexts

Device contexts can be obtained for the screen or a printer. Different members of the class are set depending on which it is: eventually, this should be changed.

The device context is the root of the gfx system: you need a DC to create a rendering context. Font resolution and colour management is done on a per-DC basis.

Split up into screenDC and printDC

Colour management

Raptor specifies colours in RGB. The GPI provides three ways of managing this:

1. RGB colour tables (LCOLF_RGB)
2. Indexed colour tables (LCOLF_INDRGB)
3. Palette mananger (LCOLF_PALETTE)

Presentation spaces and painting

There is no exact analogue of HPS. A rendering context (RC) is very much like a presentation space, in that it has methods for drawing lines, setting colours, selecting fonts and so on. The RC also has double-buffering built in: it has two PSs, one in-memory (with associated HDC and HBITMAP) and the other for the device (screen or printer). Each PS is stored in a Drawing Surface, of which there are three types defined and implemented in nsDrawingSurfaceOS2.h and nsDrawingSurfaceOS2.cpp. Note that an RC always has two references to drawing surfaces: when the RC is not in double-buffer mode, those references are to the same (onscreen) drawing surface.

The interface to the drawing surface class is very messy at the moment.

Note that (offscreen) drawing surfaces may outlive the RC which created them and be reused in another RC.

Because logical fonts are managed by PM on a per-PS basis, font information is stored in the drawing surface.

Under OS/2, the positive coordinates run up and to the right. In the rest of the world, including raptor, positive coordinates run down and to the right. This means that, in order to draw anything, we need to know the height of the target object: if the target is a printer, the height of the page; if a screen-PS for a window, the height of that window, and so on. Thus there is a method in nsRenderingContextOS2, GetTargetHeight which does this.

The base nsDrawingSurfaceOS2 class should support the new(ish) nsIDrawingSurface interface. This allows clients to access the bits of the surface directly, and is needed for the new compositor.
Support LockSurface and UnlockSurface methods; this should follow easily from supporting the nsIDrawingSurface interface.
Draw unicode text
Allow for devices which don't have square pixels
Fix GetClipRect method

Images and blending

The guts of the image-processing code lives in libimg. The role of the nsImageOS2 class is to provide a buffer of bits into which libimg can write. There's support for simple transparency too, whereby each image gets two pixmaps, one `real' and a monochrome mask.

In fact HBITMAPs are never created, basically because they are device-dependent: when you ask raptor to print an image, it will use the same nsImageOS2 object. I am also told that GpiDrawBits is more efficient than GpiWCBitBlt.

The nsBlenderOS2 class provides compositing, that is mixing pixmaps together. The guts of this resides in the fairly-XP code in nsBlender.cpp.

Need to support blending of rendering contexts; this should follow easily from supporting the nsIDrawingSurface interface.

Font management

Objects of class nsFont are used to represent platform-independent fonts. They correspond roughly to the FATTRS structure. Objects of the nsFontMetricsOS2 class are built from an nsFont, and are specific to a device (actually to a device class).

An instance of nsFontMetricsOS2 contains both metrics for the font (eg. the max advance in application units) and a thing called the font handle. This is an XP object whose job it is to hold the information necessary to select the font represented by the nsFontMetrics into a drawing surface. On OS/2, this is a FATTRS and a SIZEL to set the size of the font.

Each nsDrawingSurfaceOS2 contains a table of LCIDs keyed by font handle.

There is currently nowhere specified the encoding (codepage) required for the font, so codepage 1004 is always used.

Regions

nsRegionOS2 is a wrapped-up HRGN with one little quirk: coordinate systems. Coordinates are in device units and also in the mozilla coordinate system (see above) -- but there's no way of knowing the height of the target object, and so translation to the OS/2 system is not possible.

So regions are stored in a third coordinate space, which is transformed into OS/2 at the time the native region handle is extracted.

Note that the GetNativeRegion method is unlikely to do what you want.

Printing

Setting up for printing is a bit tortous. Here's how the various classes are supposed to be used:

• Create an nsDeviceContextSpecFactoryOS2
• Call the CreateDeviceContextSpec method in the factory.
  This pops up the select-queue dialog; job properties can be done.
  Eventually we end up with an nsDeviceContextSpecOS2. This is basically a PRQINFO3 structure.
• Call the GetDeviceContextFor method in the (screen) DC which you want the print DC to be compatible with.
  This creates a new DC, which has an HDC and HPS for the chosen printer.
• Use the various printing-specific methods in the new DC to control document and page breaks.
• Create RCs from the print DC and output to the printer.