System Software Support for New V1.4 Graphics Modes This document presents an overview of the system software interface to the new Amiga display modes. There are detailed specifications of the interface in accompanying autodocs and include files, particularly graphics/displayinfo.h. Interim Compatibility The current design differs markedly from earlier developent designs, in particular the V35 A2024/Viking jumpstart release, and of the V1.4 Alpha 14 release. This design is not source compatible with either of these. We will be adding special purpose code to provide BINARY compatibility with programs written for the A2024/Viking release, however. Display support utilities such as SetMonitor and AddMonitor will also be incompatible. What Are the New Modes? We enjoy several hardware add-ons and enhancements that vastly increase the distinct number of display modes. With these, though, come problems of both technical and in user interface. The new modes arise from these advances: New Denise: We can now generate "superhires" pixels which are twice as fine as our current hires pixels. (We begin referring to pixels by their speed, rather than width, for reasons that will become apparent.) They are approximately 35 nanoseconds long, while hires are 70 ns, and Lores 140ns. In the absence of any other features, this can bring a new mode which nominal dimensions of 1280x400 (NTSC, interlaced), or 1280x512 (PAL, interlaced). When Denise is generating these new fast pixels, chip bus bandwidth limitations dictate that at most two bitplanes are supported, and that with two bitplanes, the chip bus is saturated. The palette for superhires pixels is also restricted to 64 colors. New Agnus: Agnus has been enhanced to support monitor horizontal scan frequencies of 31 KHz, double our familiar 15 KHz (rounded). This provides over 400 non-interlaced horizontal lines in a frame, but requires the use of a monitor capable of multiple scan frequencies ("multi-sync"). This effect speeds up the video beam roughly by a factor of two, which has the side effect of doubling the width of a pixel emitted at a given speed. Thus, for a given Denise mode, pixels are twice as fat, and there are half as many on a given line. The increased scan rate interacts with all of the Denise modes. In particular, we see a mode with both the superhires (35ns) pixels and the double scan rate would generate 640 pixels wide by more than 400 rows, non-interlaced, with up to four colors from a palette of 64. We have named this combination "Productivity Mode," and have chosen 480 rows as the default height, internationally. The support in Agnus is actually more flexible, and gives us the opportunity to explore special-purpose modes, such as displays synchronized to motion picture cameras. A2024: This new device can handle normal Amiga modes (in grayscale), or work in conjunction with special system software to produce a very high resolution display, typically 1008x800 with an NTSC model and 1008x1024 with a PAL model. Selectable PAL/NTSC: The Enhanced Chip Set can be set to behave in NTSC or PAL modes under software control. Its initial default behavior is determined by a jumper or trace on the system motherboard. This has no bearing on productivity mode and other programmable scan operation, but the new system software can support "old-style" displays in either PAL or NTSC. New Mode Specification In V1.3 and earlier software, the mode for a display is determined by (some of) 16 ViewModes bits, specified either in a ViewPort or NewScreen structure. Furthermore, existing programs routinely make interpratations of the given display mode based on bit-by-bit testing of the 16 bit mode field. When one contemplates all the possible new mode combinations and turns an eye to future expansion, there is clearly a need to vastly extend the specification of modes, and to begin separating the *specification* of a mode from its *interpretation.* Furthermore, we want to pay special respect to the fact that modes are grouped by the special monitor operation or even physical device that is required to support various modes. Also, we want to make provision for supporting additional monitors and their modes in the future. The approach we have taken is to introduce a new 32 bit *abstract display mode specification* which we call a "Display ID." The upper half of this specifier is called the "monitor part" and the lower half is informally called the "mode part." There is a correspondence between the monitor part and the different monitors or monitor operating modes, which we call "virtual monitors" or "Monitor Specification." NTSC, PAL, VGA (double-scan rate mode), and A2024 are all differnt virtual monitors supported directly by the 1.4 system software. To guarantee that some display will be available to any program, the system provides a "default monitor" which maps (in V1.4) to either PAL or NTSC, and is represented by a zero value for the upper 16 bits of a valid Display ID. As you will see below, compatibility considerations--especially for IFF files (and their CAMG chunk)--have dictated very careful choices for the bit values which make up the mode part of the 32 bit display IDs. For example, the display ID's corresponding to old (V1.3 and earlier) modes "just happen" to be constructed out of a zero in the monitor part and the old 16 bit ViewModes bits in the lower part (after several extraneous bits such as SPRITES and VP_HIDE are cleared). There are more "coincidences," but steps for compatibility with old programs notwithstanding, there is a new rule: "Programmers shall not interpret display ID's on a bit-by-bit basis." It has been our goal to provide a suitable substitution for the information gleaned by interpreting mode bits, and to make that information more robust (for example, HIRES doesn't mean 640 pixels across when it is accompanied by a doubling of the beam scan rate). Display Info Records ("Mode Handles") Accompanying each display mode, new or old, is a body of data which enables us to set up the display hardware, and to provide the promised information to programmers about each mode. Data records in this database are accessed by searching the database for a record for a given display ID. For performance considerations, we provide a look-up function which given an abstract display ID, returns an abstract "handle" which really a pointer to a private internal data record. The look-up function is named FindDisplayInfo() and is detailed in the accompanying autodocs. This handle is used for queries of the database, and specification of display mode to the low-level graphics routines. It is NEVER to be used as a pointer. We call the private data structure associated with a given display ID a "DisplayInfoRecord" or just "display info." Making Modes Available Even if the monitor (or new chips) to support a given mode are not available, there will be a display info record for all of the "standard" display modes, that is, the modes which we understand and support with the system software for any given release. One of the query operations, below, will identify whether that mode is available, and if not, why not. One can assume that these display infos exist, but when using future modes, the translation of display ID to display info record should be tested for failure. Of course, data corruption might cause our look-up function to fail even when it should not, so the careful programmer will always test the return value of FindDisplayInfo. Dependence on the new chip set is determined by graphics at power up, but the monitor attached to the system cannot be detected and so must be specified by the user through a separate utility, AddMonitor, which we provide. We are working out the most convenient ways to make this specification at startup time and open your initial workbench screen on your new monitor. Binding Names It has proven useful to associate common names with the various display modes. Historically, this basically followed names presented in the Deluxe Paint Screen Format requester. We have made a provision for binding a name to a display mode, so that it will be available via a query. This will be useful in the implementation of a standard "screen format requester." Since the bound names will take up ram at all times, we initially bind few names and implement default names in the screen format requester. The bound names will override the defaults, though, so that until the screen format requester is localized to a non-English language, the modes can be localized by binding foreign language names to the modes. MonitorSpec Structure Associated with each display info record is a MonitorSpec structure, (in a many-to-one mapping). More precisely, there is a MonitorSpec for every *available* display mode. The MonitorSpec is a low-level technical data structure which contains data that the graphics library needs to drive different brand monitors in different modes. It also is the source of some transformation information regarding how different beam scan rates effect pixel height and depth. Most programmers will not encounter the MonitorSpec. If they do, it will probably only be so to associate the MonitorSpec of a non-default monitor with a View structure to run the display in one of the new monitor modes, using the graphics library directly. Querying Display Info As mentioned earlier, there is a query mechanism to get information about a display mode, taking a display info record as a parameter. For run-time efficiency and internal representation considerations, there are several queries, providing information in groups. Each query operation fills in a structure, similar to the GetPrefs() function. The length of the user buffer provided identifies to the query function the amount of storage the user has provided, and the maximum amount of data that can be transferred may depend on the version of the system software. The length in bytes of the data provided is returned by the query function, and may be depended on to be complete for the information defined for a particular system software version. The name of the query function is GetDisplayInfoData. A parameter identifies which group of information is to be returned. We may impose some lower limits on the buffer sizes that may be passed to the queries. Here is a general outline of the query categories, and the information contained. The specifics are documented in the accompanying include file named graphics/displayinfo.h. DisplayInfo: - availability of the mode - resolution/aspect ratio - number of standard sprites - boolean properties, such as interlace, ham, dual playfield, whether standard beam-sync techniques apply, etc. DimensionInfo: - minimum and maximum raster dimensions (which can be scrolled widthin a smaller displayable portion - typical dimensions (such as 640x200) - standard, text, max, and video overscan MonitorInfo: - address of the MonitorSpec - legal and default View positions - screen compatibility criteria (see below) - scan frequency information NameInfo: (optional) - the bound human-readable name of the mode Changing Display Info Values Some of this information is changed in response to user Preference specification. Until further notice, this will reserved as a system activity and use private interface methods. Specification, Screen Interface Opening an Intuition Screen in one of the new modes was planned to be as simple as possible. However, it requires the specification of 32 bits of displayID to request one of the new modes. Therefore, the NewScreen extension mechanism must be used. Unfortunately, there are programs and public data structures which depend on the size of the NewScreen structure. There is now a structure named ExtNewScreen which provides an extension facility, and comes with a warning never to depend on its size remaining constant. An example program, ScreenDemo, will be provided to demonstrate opening screens using the new technique. Old methods of opening the original modes still work, of course. When no 32 bit specifier is provided, Intuition will construct one from the 16 bit ViewModes field by masking the extraneous bits and putting a zero (for "default monitor") in the high word. It then behaves essentially as if the 32 bit ID were specified. OpenScreen pulls some sanity checking tricks to notice if someone is passing the low 16 bits of a new 32 bit display ID, and tries to compensate. This may happen when old IFF readers and players operate on new modes. One unsupported phenomenon that has gained in "popularity" is "flying mode changes" where an illegal program changes a screen's ViewPort.Modes field and call RemakeDisplay(). This is bad. A new entry point will be provided (NOTE: not in alpha 15) to perform a screen mode change. Furthermore (in a gesture of considerable magnanimity) we will attempt to detect and handle the illegal method. (NOTE: not in alpha 15). Dual-playfield screens are poorly initialized by Intuition, but improvement runs a compatibility risk. We will address this by doing exactly the same thing in V1.4 when a DUALPF mode is requested via a 16 bit ViewModes, but will perform a more complete job if the request is made via a 32 bit display ID. (NOTE: not in alpha 15). One general programming area that will need to be learned by complete programmers is "mode-flexible" processing. Today, there is some effort in writing software that runs on PAL and NTSC hardware interchangibly. If you desire to open a screen in the highest resolution mode a user has available, however, you will have many more cases to handle. Therefore, it will become increasingly important to algorithmically lay out a screen for correct, functional, and aesthetic operation. We intend to see that all the information you will need to be mode-flexible is available through the query interface. Specification, ViewPort Interface When working directly with graphics, the interface is based on View and ViewPort structures, rather than Screens. New information must be associated with the ViewPort to specify the new modes, and also with the View, to specify what virtual monitor the whole ViewPort list will be displayed "on." (See the section on Mixed Modes, below). The association of data with the View is made through a new associative data management system which has been added to graphics.library. We have a great deal of new information that we will associate with ViewPorts (regarding new genlock capability) and will be using a different mechanism for ViewPorts, as we now describe. All correctly written programs which associate a ColorMap structure with a ViewPort use the GetColorMap() function to allocate it. We have taken advantage of that to inaugurate the ColorMap structure as the general purpose "black box" extension of the ViewPort data. There is a new generalized interface to this data, named "VideoControl," which allows the setting (and getting) of these data. This mechanism is used to associate a display info record handle (NOTE: not a display ID) with a viewport. Of course, old-style viewports will continue to be supported for the old modes. There is an example program named "ViewPortDemo" which illustrates graphics-direct techniques of initializing and activating a complete display. Relative Aspect Ratio One problem that has been haunting us for a while comes to the fore with the addition of the many new modes: "How does one write resolution independent software?" The answer is probably longer than this entire document, but we provide a simple ingredient in the display info data: a scale transformation from a common coordinate system to each display mode. The informal terminology for this is that we introduce a unit of measurement called 'ticks.' We declare some integral number of ticks per pixel for a given mode, and call that the "Resolution" of a that mode. The plan is for the size of ticks (and hence the number of ticks per pixel for each mode) to satisfy the following criteria: - Ticks are sufficiently small that there will always be at least one tick per pixel on an Amiga display. - Ticks are large enough that one can describe the displayable region of the screen (maximally overscanned) in a signed 16 bit integer. - A screen layout defined in ticks converts to very similar visuals on screens of different modes. Note that the goals of ticks do NOT include: - being smaller than printer coordinates - being able to do any graphics operation in ticks coodinates in 16 bits - being able to describe the largest allowable raster dimensions in 16 bits. - providing a precise conversion to physical screen dimensions, regardless of monitor potentiometer adjustments. - providing exact physical equivalents in the different modes. - being guaranteed to express the width and height of a pixel in any mode as a power of 2. Coexisting Modes Note that each mode is really a pair of specifications of pixel mode and a monitor scan mode. Now, while the Amiga has the great ability to change pixel modes on the fly, it is not typically possible to change the speed of a monitor beam in mid-frame. Therefore, if we simultaneously display screens in different display modes (requiring different scan rates), at least one of the screens will not be displayed correctly. The effect of different scan rates is typically a factor of two distortion in both the width and height; compression in one and stretching in the other. We adopt the rule that the frontmost screen in an Intuition display determines the virtual monitor (i.e., its corresponding MonitorSpec is installed in Intuition's view), and deal with the screens behind in various ways: - "Coerce" screens behind to a different mode designed for the monitor of the frontmost screen. We can do this in a couple of ways, introducing or removing interlace to adjust the vertical dimension, and changing to faster or slower pixels (higher or lower resolution) for the horizontal dimension. The disadvantage of introducing interlace is flicker. The disadvantage of increasing resolution is the lessening of the video bus bandwidth, and possibly the reduction of the number of colors or the palette resolution. We will allow the disabling of these two methods of coercion indepently through Preferences. - Show "mixed modes", complete with distortion. This will always happen if coercion is disabled. The phenomena are better viewed than described. Note that although Intuition must make internal adjustments to its scaling routines to correctly place the mouse relative to the screen, the Resolution is not changed so that all application activity is conducted as if the screen were shown on its "native" monitor. - Exclude simultaneous display. We are only doing this for the special A2024 modes, due to their extreme perversion of the display concept. Exclusion of screens is specified on a per-Monitor basis. Currently, we have two types: complete exclusion, where only one screen may be shown, regardless of type (viz., the A2024 screens), and "mixed" where we will show any other "mixed" screen, possible distorted. Our scheme is extensible to "equivalence classes" of exclusion for future modes, or perhaps as a user preference. We've received a request to open old hires-interlace screens in productivity mode, which is not handled by coercion (unless you place a productivity screen in front of it, dragged down). We'll try to find a way to support this as a Preferences item in a future alpha or beta release, but we cannot make a committment to support it at this time.