ref: c2a64e26fac9075f13db54bb4f6dfbe33a122464
dir: /demos/graph/migs.html/
<!doctype html public "-//w3c//dtd html 4.0 transitional//en"> <html> <head> <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> <meta name="GENERATOR" content="Mozilla/4.6 [en] (X11; I; Linux 2.2.9-19mdk i586) [Netscape]"> </head> <body> <center><font size=+2>MiGS Overview</font> <br><font size=+2>A Minimalist Graphics Subsystem</font> <p> <hr WIDTH="100%"></center> <h1> <font size=+0>Introduction</font></h1> <blockquote>This document details the design and implementation of MiGS, the minimalist graphics subsystem used by the FreeType 2 demonstration programs. Its purpose is mainly to help writers of new demo programs, as well as developers who would like port the subsystem to other platforms.</blockquote> <hr WIDTH="100%"> <h1> I - Design goals</h1> <blockquote>MiGS is a tiny graphics subsystem used to demo text rendering through the FreeType library. It was mainly written to provide the abilities to :</blockquote> <ul> <ul> <li> draw a monochrome glyph bitmap to many kinds of target surfaces (i.e. really bitmaps/pixmaps)</li> <li> draw an anti-aliased glyph bitmap, with any level of grays, to many kinds of target surfaces</li> <li> display a simple window on many systems like X11, OS/2 and Windows</li> <li> accept simple events (keypresses and mouse buttons) in this window.</li> <li> to be portable and present a unified API on all running systems</li> </ul> <p><br>MiGS uses system-specific "drivers" in order to perform display and event handling. The blitting functions are not device-specific. MiGS can be built and/or used with no system-specific features, like for example, to generate simple GIF, PNG, TIFF, etc.. images without ever needing to display them.</ul> <h1> <hr WIDTH="100%"></h1> <h1> II - Surfaces, bitmaps and windows</h1> <blockquote>A surface in MiGS models a drawable region where glyph images can be rendered, a surface always contains a bitmap descriptor as well as a few other things that will be described later in this section. <p>Some surfaces can be displayed, they are then either called <i>windowed surfaces</i> or <i>screen surfaces</i> depending on the nature of the <i>device</i> used to display them. Each <i>device</i> is implemented by a very simple <i>driver</i> in the MiGS code. Here are a few example devices that are or could be written to display surfaces : <p>- an X11 device <br>- a Win 32 GDI device <br>- an OS/2 Presentation Manager device <br>- a fullscreen SVGALib device on Linux <br>- a GGI visual device <br>- an OS/2 "Dive" device, or the equivalent Win32 "DirectX" device <p>etc.. <p><b>NOTE: </b>For now, only the X11 device was written and tested.. More devices should come later <p>Before explaining how to create a surface, we need to explain how MiGS manages bitmaps and renders glyph images to them. <h3> 1. Bitmaps :</h3> <blockquote>A bitmap in MiGS features the following things : <ul> <li> a <b><i>width</i></b> in pixels</li> <li> a <b><i>height</i></b> in pixels</li> <li> a <b><i>pixel mode</i></b>, which indicates how the pixels are stored in the surface's buffer</li> <li> a <b><i>pitch</i></b>, whose absolute values is the number of bytes taken by each surface row</li> <li> a <b><i>number</i></b> of valid <b><i>gray</i></b> levels (see below)</li> <li> a <b><i>buffer</i></b>, holding the surface's pixels</li> </ul> <p><br>MiGS uses the <i>"Y downwards"</i> convention, which means that <i>increasing Y</i> coordinates correspond to <i>lower rows</i> of the bitmap. Hence, the coordinate <i>(0,0)</i> always corresponds to the bitmap's <i>top-left pixel</i>. <p>The bitmap's rows can be stored either <i>"downwards"</i> or <i>"upwards"</i> in the pixel buffer. <p>In the first case (<i>downwards</i>), increasing memory addresses in the pixel buffer correspond to lower rows of the bitmap(e.g. PC video modes), and the <b><i>pitch</i></b> should be equal to <b><i>the number of bytes taken by each row</i></b>. The first pixel buffer byte corresponds to the upper row. <p>In the second case (<i>upwards</i>), increasing memory addresses in the pixel buffer correspond to upper rows of the bitmap and the <b><i>pitch</i></b> should be equal to the <b><i>opposite</i></b> of <i>the number of bytes taken by each row</i>. The first pixel buffer byte corresponds to the lower row. <p>In all cases, the <b><i>pitch</i></b> is the <i>increment to be used to go from one bitmap row to the one below it</i>. <p>The supported pixel modes are : <ul> <li> 1-bit monochrome bitmaps. With "0" as the background, and "1" as the foreground.</li> <li> 4-bit color bitmaps, using an arbitrary palette.</li> <li> 8-bit color bitmaps, using an arbitrary palette.</li> <li> 8-bit gray bitmaps, using a given N number of gray levels in the range 0..N-1.</li> <li> 15-bit color bitmaps, also known as RGB555</li> <li> 16-bit color bitmaps, also known as RGB565</li> <li> 24-bit color bitmaps, also known as RGB</li> <li> 32-bit color bitmaps, also known as RGBA (though the A is ignored by MiGS)</li> </ul> The bitmap's <b><i>number of gray levels</i></b> is only relevant for <b><i>8-bit gray bitmaps</i></b>, and indicates the range of gray levels that can be found in the bitmap. If a bitmap as N gray levels, it is said to be <i>N-grayscales</i>, and the pixels within it must all have values between 0, considered as the <i>background</i> color, and N-1, considered as the <i>foreground</i> color. <p>N-grayscale bitmaps are crucial for the rendering of anti-aliased text. <br> </blockquote> <h3> 2. Glyph images :</h3> <blockquote>The glyph images that can be drawn on bitmaps through MiGS are bitmaps themselves, though limited to the following pixel modes : <p><b>1-bit monochrome glyph bitmaps</b> <blockquote>These can be drawn on any kind of bitmap. Note that <i>only the "lit" pixels</i> (i.e. the bits set to 1) are effectively drawn to the target, as opaque blitting isn't supported (remember, it's a minimalist library !)</blockquote> <p><br><b>N-grayscales glyph images </b>(with any value of N >= 2) <blockquote>These can be drawn to <i>all RGB bitmaps</i> (15, 16, 24 & 32 bits/pixel), as well as any other M-grayscales bitmaps. In the latter case, the values of N and M <i>need not be equal</i>, as the library is able to perform automatic conversions <i>on the fly</i>. <p>For example, it is possible to render a 5-grayscales glyph image into a 128-grayscales bitmap. Moreover, it is also possible to render a 17-grayscales glyph image into a 5-grayscales bitmap, even if this will result in <i>a loss of quality</i>. This feature is crucial in order to experiment easily with other anti-aliasing algorithms for FreeType <br> </blockquote> Note that you can <i>only</i> draw <i>monochrome</i> bitmaps to the following pixel modes : monochrome, 4-bit color and 8-bit color.</blockquote> <h3> 3. Windows and Screens:</h3> <blockquote>In order to debug FreeType, displaying a surface in a window or in full-screen mode, is required. MiGS thus makes a difference between <i>simple surfaces</i>, which only contain a bitmap, <i>windowed surfaces</i>, which are used to display their content in a window, and <i>screen surfaces</i>, which are used to display their content in a full-screen mode (SVGAlib, DirectX, GGI or wathever). <p>A few important things must be said about non-simple surfaces. <br> <ul> <li> First, they might contain some system-specific data which is used to manage the display in a window or on the screen. This must be <i>completely hidden</i> to MiGS clients. Indeed, rendering to any kind of surface is achieved through <i>exactly the same function calls</i>.</li> </ul> <ul> <li> Second, they may contain a bitmap whose pixel mode doesn't correspond to the screen's depth used to display it. For example, the surface might contain an 128-grayscale bitmap, while the screen is in RGB24 mode. Some conversion must be performed to display the surface. This can either happen in the system-specific graphics library (e.g. on OS/2, a single Presentation Manager call is used to blit a N-grayscale image to <i>any</i> kind of window) or in the system-specific part of MiGS (e.g. the X11 MiGS driver must convert the surface's bitmap into the appropriate <i>X11 image</i> each time a repaint is requested). Again this must be completely hidden to MiGS clients</li> </ul> Surfaces have also a few fields that are only used when displaying them in Windows : <p><b>a title string</b> <blockquote>This is simply a text string that is displayed on the title bar of the surface's window. It can also appear at the top or bottom of full-screen surfaces if the MiGS driver supports it. The title string can be changed with a call to <tt>grSetTitle</tt>, and is ignored for simple surfaces.</blockquote> <p><br><b>a refresh flag</b> <blockquote>This boolean flag is only used for window surfaces, and some fullscreen ones (depending on the driver implementation). When set, it indicates that each glyph image blit must be displayed immediately. By default, this flag is set to False, which means that demo programs must call the <tt>grRefreshSurface(surface)</tt> function to display the whole contents of a surface one it has been updated. <p>The refresh flag can be set with <tt>grSetSurfaceRefresh(surface,flag)</tt>. Note that a single surface rectangle can be forced to be displayed with a call to <tt>grRefreshRectangle(surface,x,y,w,h)</tt> at any time.</blockquote> </blockquote> <h3> 4. Devices :</h3> <blockquote>As said before, each device is in charge of displaying a surface in a given window or screen. Each device is managed through a very simple driver, described to MiGS through a very simple "grDevice" structure. <p>A grDevice contains, among other things, pointers to the functions used to: <p>- refresh/display a given rectangle of the surface to the window/screen <br>- listen events (key presses and mouse) and send them back to client apps. <br>- for windowed devices, update the title bar. <p>As said before, this is a highly minimalist system.. <br> </blockquote> </blockquote> <hr WIDTH="100%"> <h1> III - Important implementation issues :</h1> <blockquote> <h3> 1. Display surface negociation :</h3> <blockquote>A display surface is created with the function grNewScreenSurface which takes parameters indicating which device should be used, the pixel dimensions of the requested surface, as well as its pixel mode. <p>Because of some device-specific limitations, the resulting surface's properties might not match exactly those requested for the call. Hence, a developper should <b>always take care </b>of reading a new display surface's <b>bitmap</b> descriptor in order to get its <i>real</i> dimensions, pixel mode and eventually number of grays. <p>The function grNewSurface will create a memory surface with the corresponding bitmap. <br>The function grNewBitmapSurface will create a surface from a pre-existing bitmap. This is useful to draw text on loaded images, for example. <p>Any surface (display or not) is destroyed with grDoneSurface.</blockquote> <h3> </h3> <h3> 2. Supporting 8-bit grayscale mode :</h3> <blockquote>It is important, for the debugging of FreeType anti-aliased renderer(s), that <b><i>_all_ devices should support the 8-bit gray mode</i></b>. The number of gray levels can be fixed or negociated as required by implementation-specific issues. <p>As most existing devices do not provide direct support for such a mode, each 8-bit surface must thus contain : <p>- an internal N-grayscale bitmap, used as the target of all glyph drawings <br>- its own device-specific "image", which matches the display depth. <p>Each time the device's "refresh_rect" function is called, it should then : <br>- convert the grayscales within the bitmap's rectangle into the image's buffer and format. <br>- display the corresponding image rectangle. <p>This scheme is used, for example, by the X11 device.</blockquote> </blockquote> </body> </html>