Newsgroups: comp.sys.amiga.advocacy Subject: ***** V39+/WB 3.0 SPECIFICATIONS ***** Summary: V39.b3.spec text from Commodore Message-ID: <1992Aug03.155733.15612@pdnfido.fidonet.org> Date: 3 Aug 92 15:57:33 GMT Organization: The Source for Source Pub Access Unix Lines: 707 Well.. Here it is. I'm sure some of you have seen this already. This is the update file for beta-testers for Workbench 3.0 (V39+ ROMs.) This file was released to betatesters on June 8th. I've had this text file for over a month now and have read it quite carefully. If you feel commodore needs some suggestions, please do us all a favor and leave them at: suggestions@cbmvax.commodore.com NOTE: This is a somewhat technical list on the specifications of the V39 ROMs which will be the ROMs used in the new line of Amigas. This message contains the text from commodore on OS39, the NEXT message contains the text from commodore on the AA Chipset. Please refrain from leaving any sort of flame mail. Remember that I am the POSTER and not the writer of this file. Feel free to leave comments but I will probably not be able to answer many questions. You might be further intrested to know that I also have a beta V39 rom image and the Workbench 3.0 update disk. I AM NOT a pirate, except possibly in this case when it intrests me to know what is going on. Thank you. ------------------ COMMODORE TEXT STARTS HERE -------------------------- V39 Specification ROM and Disk June 8, 1992 rev 1.6 ()) Copyright 1992 Commodore-Amiga, Inc. All Rights Reserved. Proprietary and Confidential. Doc: rev 1.0 Created February 14, 1992 This document contains a description of the modules and programs that have changed for Amiga OS V39. For a low-level function specification please refer to the Autodocs. Overview Graphics o support new AA modes/features o double buffering o Retarget sprite and screen/viewport functions o Palette sharing o Bitmap functions o Interleaved BitMaps o Mode promotion, coercion and selection o RTG compatible RastPort functions. Intuition o Support new AA modes o Double buffering o Support AA graphics functions o Default busy pointer o support interleaved bitmaps o Attached screens (incl. menu lending) o promotion o support new sprites o Gadget help o Tablet support o NewLook menus o Special gadget relativity and GM_LAYOUT method GadTools o Palette enhancement o ListView enhancement o GT_GetGadgetAttrs() function o Support for Intuition's NewLook menus and Gadget Help. o Support for gadgets in requesters o All-new PALETTE_KIND gadget o Many small enhancements BootMenu & Battmem o PAL/NTSC switch o Chip select switch Layers o Use new optimized layers o Layerinfo backfill hook o ClipRect traversal Workbench o Use ILBM as backdrop pattern o WB config notification o Path of file in 'Information' Console o fix console not to lock layers for long o Use Mask bit to speed up rendering. o Misc. enhancements and fixes. Clipboard o fix r/w bug with units above unit 0 Filesystem o New filesystem with directory blocks. Exec: o System specific changes o Memory pools o Memory handler o Procure/Vacate o Timed out alerts o SAD CIA resource o bump priority to 120 DOS o Rearrange strings. Preferences o New Iprefs o New WBPattern editor o New Pointer editor to support AA. o New Palette editor with pen assignments (using the Colorwheel class). o Icontrol changes (promotion) WB Disks o MultiView o Localization of selected programs - DiskSalv - PrepCard - MultiView - misc. new strings in preferences programs - non-concatenated DOS strings. o DiskSalv. Disk-repair program o ColorWheel Class: Set of boopsi classes implementing colorwheel colorselection. o New c: commands to use ASL-file requester and easy-requester from scripts . Appendix A New Workbench-disk programs and libraries and their location on the diskset. Detailed Specifications The following sections describe in more detail the changes and new features in AmigaOS V39 Graphics Specification: Philosophy: The original amiga graphics library exposed many device-dependent details to the application programmer. Because of this, introduction of new graphics devices has been slowed, and application support fo new features has been delayed. To reverse this trend, no features have been added to the new graphics system which cannot be kept for the future. Thus, when newer graphics systems are introduced, system software will need fewer changes, and applications will be ready to automatically use new capabilities. Thus, parameters such as number of bits per pixel, resolution, color palette size, etc are either variable or have been made very large. Low level functionality Graphics copper list generation must be extended to handle loading of >6 bit plane pointers, loading of extended color registers, handling of fetch and scrolling for 32 and 64 bit fetch modes, promotion of interlaced modes to 31khz ("flicker-fixing"), promotion of non-interlaced modes via scan-doubling, and color palette banking. Compatibility The AA chips are register level compatible with the old and ECS chips at boot up time. However, when new AA modes are enabled and displayed, and a game then takes over the screen display without informing the OS of it, some registers may be in incompatible settings. Two approaches will reduce this: (a) old Programs which boot with their own custom boot block (games) will have AA features disabled unless they are specifically asked for. This should ensure transparent compatibility for all bootable games. (b) It will be possible to disable AA features for non-compatible programs. This will be done via the "BootMenu" which is available at system boot time. new options in this menu will allow disabling of AA, disabling of ECS, and switching of PAL and NTSC. Get/Set functions This release of graphics.library will attempt to ease the (future) transition to Retargetable Graphics. New functions are provided to do some operations in a more device-independent manner. This will help when we have to support foreign graphics devices, more than 8 bits per pixel, chunky pixels, and true-color displays. This new calls of "Get/Set" function will allow device independent access to fields in the RastPort structure which were only previosuly manipulable by direct structure access. Color Map functions The color palette in AA is different in a lot of ways from the ECS one: o It has 24 bits per entry, plus one bit to select transparency. o There are 256 entries which is enough for many programs running on the same screen to share the palette. The new color palette functions allow for multiple applications to coordinate their access to the palette. This allows applications to, for instance, dynamically remap pictures to match the color palette of the workbench screen, display animations in windows, etc. All colors are now specified as 32 bit left-justified fractions, and are trunacted based upon the number of bits that the hardware is capable of displaying. Bitmap functions These function exist because the new AA chips have alignment restrictions in high bandwidth modes. Changing InitBitMap and AllocRaster to obey these restrictions appears to be very incompatible. Bitmaps created by AllocRaster with a multiple of 32 or 64 pixels per line will be compatible with high fetch modes (2x or 4x respectively). Incompatible ones will fall back to 1x mode, if 1x mode is capable of displaying the screen. AllocBitMap allocated an entire bitmap structure, and the display memory for it. AllocBitMap allows you to use more than 8 planes, and also allows you to specify another bitmap pointer, thus telling the system to allocate the bitmap to be "like" another bitmap. A bitmap allocated in such a matter may be able to blit to this bitmap faster. Such a bitmap may be stored in a foreign device's local memory. Do not assume anything about the structure of a bitmap allocated in this manner. The size of a bitmap structure is subject to change in future graphics releases. Thus, you should use AllocBitMap/FreeBitMap for your raster allocation. Sprite functions Graphics sprite functions (MoveSprite) will be extended to understand large sprites, selectable sprite pixel resolution, and movement of scan-doubled sprites. Sprite positioning will no longer be rounded down to lo-res pixel resolution. Applications will no longer have to "know" about the hardware-dependent format of sprite data. Miscellaneous Some new features have been added, in order to: o Improve the programming model. o Provide new capabilities to applications o More fully take advantage of AA. Interleaved screens have been added. These use a different layout of the graphics data in order to speed rendering operations and eliminate the annoying "color-flash" problem which is the hallmark of planar (as opposed to "chunky") display architetctures. Double buffering functions have been added. These allow applications to display very smooth, synchronized animation in fully an efficient "intuition-friendly" manner. Support has been added for AA border blanking, sprites in borders, and color palette banking. See also the ScrollRasterBF() function. Some operations have been sped up: RectFill() has been rewritten, WritePixel() uses the CPU (3x speedup) and other optimizations. Some bugs have been fixed. Intuition Specification New Graphics Modes Intuition directly supports the new graphics modes. New Sprite Features Intuition supports the new sprite-resolutions and sizes. This gives the user a fine-grain pointer, which looks a lot better. As well, Intuition goes to great lengths to remain compatible with users of other sprites. Intuition now has a default busy pointer. NewLook Menus and TitleBar By adding three additional pens to the DrawInfo pen-array, Intuition now allows control over the colors used in rendering menus. This will allow the black on white menus with black trim that the Style Guide recommends. As well, the screen title bar is rendered to match. In addition, the Amiga-key and checkmark symbols that appear in the menus are colored accordingly, and are scaled by default to the screen's font. It is possible to use a custom font in a window's menus, and have the checkmark and Amiga-key symbols for that window scaled to that font. It is trivial to write compatible applications that come up optimally under all conditions (including V37). GadTools recognizes and supports NewLook Menus. Double-Buffering in Screens Intuition now supports double-buffering in screens, via the new double-buffering calls in graphics.library. It is possible to have both gadgets and menus (in a borderless backdrop window) on a double-buffered screen. Attached Screens Intuition now supports the concept of attached screens. The {SA_Attach,parent} tag is used for this purpose. First open the parent screen. Then open one or more child screens with this tag. Child screens can be dragged independently of each other and their parent (though never above their parent). Pulling down the parent below its natural top causes the child screens to move as well. Attached screens also depth-arrange as a group, whenever the user does the depth-arranging. Programmatic depth arrangement of the parent does the same. Programmatic depth arrangement of a child moves it alone, but only with respect to the group. Gadget Help and Special Gadget Relativity The gadget structure now has an additional rectangle, which is the bounding box. The HelpControl() function can be used to turn on "Gadget Help" for one or more windows. When Gadget Help is on, passing the mouse over the bounding box of a gadget having the GMORE_GADGETHELP property causes an IDCMP_GADGETHELP message to be sent. IDCMP_GADGETHELP messages are also sent when the mouse is not over the window, or is over the window but not over a help-reporting gadget. There is a GM_HELPTEST method which boopsi gadgets can use to refine their sensitivity area or to delegate the test to member gadgets. Also, GRELxxx gadgets now use the bounding box to erase themselves, so you can now have GREL gadgets whose imagery extends outside of the gadget select box. As well, there is a GM_LAYOUT method which boopsi gadgets can use to do any arbitrary layout within their window. New Tablet Support Intuition defines a new subclass of input-event which should solve tablet handling quite nicely. Tablet drivers now have an easy time knowing what they should be scaling to. In addition, it is now possible for applications to receive extended IntuiMessages that can contain such information as pressure, sub-pixel position, etc. The extra information is extensible to cover things we cannot yet forsee. Custom Image Disable-Rendering For a disabled gadget under V37, Intuition always rendered the dot pattern itself. Under V39, an image can set the IA_SupportsDisable attribute to TRUE, and then Intuition will let it do its own disabled rendering, through the IDS_DISABLED or the (new) IDS_SELECTEDDISABLED image drawing states. This is transparently compatible with V37. Promotion Crudely speaking, promotion is de-interlacing in software. IControl has a "promotion option". This flags instructs Intuition to tell graphics to change the mapping of the default monitor. Database-aware programs will now receive information about the double-NTSC or double-PAL mode when enquiring about the default monitor. Of course, if the user changes the promotion setting after the application is open, not everything it learned from the database will still be true. The new method also means that an application can request to never be promoted by asking for explicit NTSC or explicit PAL, instead of the default monitor. Pen-Sharing Under V39, Graphics supports sharing pens (ObtainPen(), etc.). Intuition now uses and supports the graphics.library pen-sharing scheme. For all screens, pens found in the DrawInfo->dri_Pens are obtained as sharable. For existing public screens, all other pens are allocated as exclusive. For custom screens and aware public screens (those that set the new SA_SharePens tag), all other pens are left unallocated. On the Workbench screen, pens 0-3 are guaranteed to be sharable. Interleaved Screens As graphics.library now supports interleaved bitmaps, Intuition makes this feature available to screen openers via the SA_Interleaved tag. Currently, the Workbench is interleaved by default. Coercion and Inter-Screen-Gap Intuition now relies on graphics.library to figure out coerced screen modes, and the required inter-screen-gap. This allows greater inter-mode compatibility, better coercion results, and compatibility with future monitors. Pens and DrawInfo The new SA_LikeWorkbench tag gives you a screen just like the Workbench. This was basically a consequence of getting pens settable through preferences while keeping NewLook menus on the Workbench screen. When the SA_Pens pen-array is evaluated, pens are masked to the number of available colors. As well, special definitions of pen-number (PEN_C3, PEN_C2, PEN_C1, and PEN_C0) mean the complementary pen numbers of pens 0-3. Preferences now listens to only 8 colors for the bitmap, which Intuition will set as the first four and the last four colors of the Workbench or any "Workbench-like" screen (those having the SA_FullPalette or SA_LikeWorkbench attributes). The way the DrawInfo pens are determined is Intuition picks a default pen-array. Then, any pens you supply with SA_Pens override the defaults, up until the ~0 in your array. If the screen is monochrome or old-look, the default will be the standard two-color pens. If the screen is two or more planes deep, the default will be the standard four-color pens, which now include the new-look menu colors. If the screen has the SA_LikeWorkbench property, the default will be the user's preferred pen-array, changeable through preferences. There is a preferred pen-array for four colors, and one for eight or more colors. Miscellaneous Window Features If a window is not frontmost, but nevertheless is unobscured, then clicking on its depth gadget used to bring it to front, which had no visual effect. It now depth-arranges correctly (i.e. to back). It is now possible to receive an IDCMP_CHANGEWINDOW message when a window is depth-arranged. Size-only zooming (where the window top-left corner is preserved) is now supported. Miscellaneous Screen Features Screens may now be made non-draggable. Screens can be designated as exclusive, meaning they will never share the display with another screen. The SA_BackFill tag can be used to specify a backfill hook for the screen's LayerInfo. Is it now possible to control the SA_Pens or other previously unavailable attributes of the Workbench screen. This will allow things such as light-on-dark text. Screens can have interleaved bitmaps. There are new universal screen movement and depth-arrangement functions. Intuition now supports scrollable 2024/Moniterm screens. Screen depth is always validated. Making a request for a screen too deep causes failure with OSERR_TOODEEP. Miscellaneous The DoGadgetMethodA() function allows you to invoke a method on a gadget, which will then receive a valid GadgetInfo pointer. The boopsi image class "frameiclass" supports the standard border types (eg. bevelled box, string-gadget ridge, "moat", AppWindow icon drop-box). Intuition now notices and repairs damage when boopsi gadgets use ScrollRaster(). (Such damage occurs when the gadget is in a simple-refresh window and part of the scrolled area is obscured). Such gadgets MUST set GMORE_SCROLLRASTER in order to benefit from this magic repair feature. (Note that ScrollWindowRaster() is for applications. Boopsi gadgets ought to use ScrollRaster() or ScrollRasterBF()). Speed Improvements When a window opens active, its border is rendered only once, not twice. This looks better and is faster. EasyRequests and AutoRequests now put their imagery and gadgets directly in their window, instead of also using a requester. This saves memory, and is faster. The rubber-band frame when moving or dragging windows is now drawn faster. Several other speed optimizations were taken. Gadtools specification For V39, work has been done to GadTools to address new Intuition features, to add some important features missing from V37 GadTools, and to fix a few bugs. The key changes are: - A "get gadget attributes" function - Support for Intuition's NewLook menus - Support for Intuition's new Gadget Help feature - Many enhancements to the different kinds of gadget, including a complete re-write of PALETTE_KIND, support for proportional fonts in the slider level display, as well as scalable checkmark and radio button imagery. BootMenu & Battmem: Bootmenu has been enhanced with support for selection of default video mode (PAL or NTSC) and selection of default chipset. Bootmenu will switch between PAL and NTSC when a key on the keyboard is pressed (except certain special purpose keys like SHIFT, ALT etc). Chipselection offers the following choices: - Original [ the original pre ECS chipset] - ECS - Best 'Best' means that the system will boot into the 'AA' on a AA system, ECS on an ECS system etc. Setting can be saved to battmem or used without saving. Support for saving to battmem may be missing from the first releases. Layers specification: The new optimized layers.library is used in V39. Layers has been further enhanced by adding ClipRect traversal and support for Layerinfo backfill hook Workbench specification: Workbench has been updated to support ILBM backdrop patterns. As a further enhancement 'Information' is now asynchronous and shows the complete filename path. Console specification - AA scrolling optimizations - AA change in EOR cursor logic - Fix CMD_CLEAR - Research a command to specify new defaults for ESC[0m. This would allow programs which send ESC[0m not to change the users preferred defaults - a nice thing for many of our programs which run from the Shell, and insist on reseting my preferred SGR settings. - Cursor & highlighting only use colors 0-3 in screens which support color sharing (e.g., WB). Clipboard.device specification: Fix units 1-255 multi R/W handling. Filesystem specification A new filesystem type (option) has been added: Directory Caching. This caches all the information normally returned by ExNext/ExAll in a series of blocks attached to each directory. These blocks normally hold 15 entries; the actual number can range from 3 to 20 for 512-byte blocks. These blocks allow exnext/exall to do drastically less disk access. Roughly, this makes floppies almost as fast as harddisks under 2.04, and harddisks almost as fast as the ramdisk. This is dramatically noticable to users, especially floppy-based users. There is a slowdown in file-creation (about 30% on harddisks), some slowdown on delete and on close of a modified file due to the need to update these caches. Also, validation, if needed, may take slightly longer since it must validate all the directory caches. These caches do add to the ability of disk-repair utilities to rebuild the directory structure of a trashed disk, though, or rebuild trashed fileheader blocks. The code cost is about 2-2.5K. Also, in the process of doing these modifications, several nasty holes from 2.04 (and before) were fixed. These include the multiple-files-of-the-same-name bug, and a bug not seen experimentally where a rename of a file and a delete of the previous file in that hash chain could collide, losing entire strings of files (or in rename versus rename, entire strings of files could be moved to the wrong directory). All modification of directory structures is now locked behind coroutine semaphores, so no holes like this should show up again. Various other bugfixes are being done as required. CIA reource specification: Bump priority to 120 DOS specification: Rearrange strings to avoid using concatenation. Preferences specification: Prefs/Pointer Changes are required for AA sprite support. This includes larger sprites with varying resolutions and number of colors. Another needed change is to support editing of the default busy pointer. Prefs/Palette With 3.0's pen sharing abilities, a different more abstract color model must be available to users. Palette prefs will gain a pen editing ability which will let the user associate arbitrary RGB values to any of Intuition's logical pens. So for example, the user will be able to specify which RGB value should be used for his text, background, window border, etc... Prefs/WBPattern Must learn to deal with more complex patterns. This will be done in a manner similar to the current Sound preferences in that a user can just enter the name of a picture to display as Workbench pattern. Prefs/IControl A few checkboxes need to be added to enable control of Promotion. C/IPrefs Needs to adapt to the new extended Workbench pattern ability. It must load an ILBM file and pass the result on to Workbench. Operations can be done on the graphics before displaying it such as color remapping. Needs to adapt to the new way Workbench expects to hear about changes to Font and Locale preferences. WB disk (tools, utilities etc. ) specification Tools/DiskSalv New program to repair and recover hard drives. Utilities/MultiView This is a object-oriented data viewer that uses the datatypes.library for its object handling. Any type of data file can be viewed using this viewer, as long as class for the data type is available. Objects can be viewed on the Workbench screen, any public screen, or a custom screen (for HAM pictures for example). Classes that will be shipped will be: ANSI - Used to view any text document that Utilities/More could have viewed, including decoding of ANSI escape sequences. ILBM - Used to view Amiga ILBM pictures. Includes the ability to remap a picture to the current palette (uses new graphic functions to obtain pens, plus does simple dithering). AmigaGuide - Used to browse through AmigaGuide documents. This is backwards compatible with the existing AmigaGuide. There have been a number of small enhancements, such as; proportional font support, word wrap, and text attributes (bold, italic, and underline). Storage/Monitors New monitors for AA support Localization Localize the following applications: - DiskSalv - PrepCard - MultiView - misc new strings in updated preferences programs. - new non-concatenated DOS strings. Tools/Commodities/MouseBlanker A new mouse blanking commodity that shuts off the mouse pointer whenever the user types on the keyboard. Tools/Commodities/NumericPad A new commodity emulating numeric keypad. Mainly intended for use on A600 class systems without numeric keypad. Appendix A Workbench 3.0 Disk-changes (layout) program Change C/#? - Misc. bug fixes C/AddDataTypes - New C/IPrefs - pointer, palette, and wbpattern changes C/RequestChoice - New C/RequestFile - New Classes/amigaguide.class - New Classes/ascii.class - New Classes/colorwhell.class - New Classes/floatstring.class - New Classes/ilbm.class - New Classes/picture.class - New Classes/text.class - New Devs/DataTypes/AmigaGuide - New Devs/DataTypes/FTXT - New Devs/DataTypes/ILBM - New Devs/printer.device - HAM-8 support L/FastFileSystem - DCFS version Libs/amigaguide.library - New Libs/datatypes.library - New Libs/iffparse.library - Optimization Locale/Catalogs/#? - Updated translations Prefs/Palette - Color whell Prefs/Pointer - AA support Prefs/WBPattern - WB backdrop support Storage/Monitors/A2024 - 3.0 ROM support Storage/Monitors/DoubleNTSC - New Storage/Monitors/DoublePAL - New System/Format - DCFS support Tools/Commodities/MouseBlanker- New Tools/Commodities/NumericPad - New Tools/DiskSalv - New Tools/HDToolBox - UI overhaul Utilities/More - Make it look like MultiView from the WB Utilities/MultiView - New Newsgroups: comp.sys.amiga.advocacy Subject: ***** AA CHIPSET SPECIFICATIONS ***** Message-ID: <1992Aug03.160026.15724@pdnfido.fidonet.org> Date: 3 Aug 92 16:00:26 GMT Organization: The Source for Source Pub Access Unix Lines: 891 This is the "Ensuring Compatibility with Next Generation Amiga Graphics Hardware" text from Commodore. I'm not sure when they released this but it was probably in the past few days. This message (as well as the last) have ONLY been posted in the comp.sys.amiga.advocacy newsgroup. This 31k text file is mostly a technical reference to programmers on supporting the AA Chipset. It ALSO describes the new graphics modes. I hope this puts rumors to rest and proves once and for all that the AA Chipset IS REAL! --------------- COMMODORE TEXT STARTS HERE -------------------- Ensuring Compatibility with Next Generation Amiga Graphics Hardware Copyright (c) 1991-1992 Commodore International Services Corporation All Rights Reserved. CONFIDENTIAL AND PRELIMINARY NOTE - This document contains a great deal of information to help you remain compatible with and take advantage of V39 and future chips. Please also consult all current readmes and release notes for the latest information on current implementations and features. Do NOT distribute this information. This information may only be discussed in Commodore's closed developer conferences, and only if Commodore opens a topic for discussion. CONFIDENTIAL - The information contained herein is confidential and proprietary. This information is provided under non-disclosure for inhouse use only by registered Amiga developers. PRELIMINARY - The information contained herein is preliminary. WARNING - The information contained herein is subject to change without notice. Commodore specifically does not make any endorsement or representation with respect to use, results, or performance of the information (including without limitations its capabilities, appropriateness, reliability, currentness, or availability). DISCLAIMER - This information is provided "as is" without warranty of any kind, either express or implied. The entire risk as to the use of this information is assumed by the user. In no event will Commodore or its affiliated companies be liable for any damages, direct, incidental, special or consequential, resulting from any defect in the information, even if advised of the possibilities of such damages. Table of Contents Introduction/Purpose New Hardware Features Ensuring Compatibility Known No-Nos Taking Advantage of New Features What to Expect From New Software Table: New Modes Introduction/Purpose The capabilities of the built-in Amiga graphics hardware had not changed significantly between the introduction of the Amiga 1000 in 1985 and the release of the Amiga 3000 in 1990. The ECS chipset and the display enhancer added several new graphics modes and increased the functionality of existing modes -- yet the market demands more. Commodore is working on a graphics chipset which will include many substantial new features. This document explains the features of this next generation Amiga graphics hardware, and ways to ensure application compatibility with these features. Additionally, coding methods are outlined which will allow current software to automatically exploit some of the new features. Finally, so that developers can begin "sketching out" applications that will support the new chipset, a brief overview of some of the relevant planned system software changes is provided. New Hardware Features This is a summary of the new Amiga graphics hardware's features. Enhanced Bandwidth - A 32 bit wide data bus allows doubling of memory bandwidth (to 2x the normal bandwidth) and supports the input of 32 bit wide bitplane and sprite data. Bandwidth may be doubled again (to 4x) by using Fast Page Mode RAM. More Bitplanes - The maximum number of bitplanes has increased to 8 in all resolution modes. This translates to a 256 entry color table for each available mode. Enhanced Dual Playfield Support - Each playfield may now have up to 4 bitplanes. The bank of 16 colors in the 256 color table is independently selectable for each playfield. Larger Palette - Each entry in the color table may now be 25 bits wide (8 bits each for Red, Blue, and Green data -- plus 1 bit for genlock information). This translates to a palette of 16,777,216 colors. Enhanced Sprite Support - Sprite resolution can be set to lores, hires, or super-hires, independent of screen resolution. Attached sprites are now available in all modes. However, some new higher bandwidth modes may only allow one sprite. Odd and even sprites may use their own independent 16 color bank from the 256 color table. Old format sprites may still be 16 bits wide, and new format sprites may be 32 or 64 bits wide. Sprites may now optionally appear in the border region. The horizontal positioning resolution of sprites has increased to 35ns (equivalent to super-hires pixel widths.) Enhanced hardware scrolling support - Two extra bits allow seamless scrolling of up to 64 bit wide bitplanes in all resolutions. The resolution of bitplane scrolling has been increased to 35ns. Hardware scan doubling support - 15khz bitplanes and sprites may now be scan doubled for flicker free display on 31khz monitors, and for enhanced display sharing with 31khz bitplanes. ECS compatibility - New chips will power-up in an ECS compatibility mode, which will allow many older self-booting programs to be run on new machines. Ensuring Compatibility This section covers programming techniques which will help ensure that an application will work as expected when running on systems that use next generation graphics hardware. The most important thing to remember about maintaining compatibility (and this applies to all software-hardware issues) is to never access the hardware directly. As a few developers learned when users tried to run their applications on the Amiga 3000, hardware does change, and the correct way to access it is through the system software. When the hardware is changed, the system software changes with it, and old programs that use the new software have a better chance of running properly. An important issue here is that you should use the current system software. Applications should be written to run under release 2.0 of the operating system, as it will be the basis for all new hardware support, and release 1.3 cannot open the new modes. One of the main reasons that 2.0 will be a minimum requirement is the Display Database. Starting with the ECS chipset, not all machines have all display modes. This will be even more true in the future. The only way to know if a particular mode is available is to check the Display Database. For a detailed explanation of how to properly open a screen using the Display Database information to check for available modes, see the AmigaMail Volume Two articles entitled "An Introduction to V36 Screens and Windows" (page IV-3) and "Opening Screens and Windows on Any Amiga" (Page IV-17). Some of the pertinent details can also be found in the Paris DevCon notes article entitled "Monitors, Modes, and the Display Database." Once a screen has been opened, manipulating that screen should also be handled using system calls. In particular, these manipulations must be handled by the system software: allocation of graphics resources - Use graphics.library palette manipulation - Use graphics.library sprite manipulation - Use graphics.library manipulating icons - use icon.library allocating & changing colormaps & colortables - use graphics.library bitplane allocations - use AllocRaster(), but please refer to the next section for important information about limitations of AllocRaster() which will require a new and different function to be called. Furthermore, these manipulations should be handled by the system software whenever possible: drawing operations - Use graphics.library and intuition.library blitter operations - Use Blt[BitMap, RastPort, etc.] functions & macros (from graphics.library.) REMEMBER -- When using the blitter directly, ALWAYS use the system's WaitBlit() function instead of your own. The system knows about and handles problems with the BLITTER_DONE signal that different revisions of the Agnus chip have. Remember that the internals of system structures are subject to change or extension. For new graphics hardware, structures likely to be extended those associated with ColorMaps, ViewPortExtras, Sprites, and many others. To deal with the "shifting sands" of system structures, developers should use system calls to allocate, create, and manipulate these structures. For example, pre-V39 applications should always use InitBitMap to properly initialize a BitMap structure. Applications that support V39 should use the new AllocBitMap() call to handle both allocation and initialization. Even structures that may not change should still be accessed with system calls, because their contents may be calculated in different ways. If an allocation call is available, use it. If an initialization call is available, use it. See the V39 graphics.doc autodoc for specifications of new functions such as AllocBitMap(). Not all system structures have "Get" and "Set" calls, but developers need to use the ones that do exist. For example, it is better to use "SetAPen(myRastPort,n)" instead of "myRastPort->FgPen=n; SetDrMd()". Many additional Set and Get functions are provided in V39. For upwards compatibility, use always the Set and Get functions when available. A note about hardware -- the new chips will power-up in an ECS compatible state, which will allow a large portion of older, self-booting (read - "games") software to run even though the hardware is hit hard by such code. However, any software which is expects to be run after the operating system has been started will need to be very careful with the hardware. Once again: IF SOFTWARE DEPENDS ON HARDWARE AND THE HARDWARE CHANGES, THEN THE SOFTWARE WILL LIKELY BREAK. It is much better for the software to depend on the system software, which will be made to work with the new hardware. While some efforts are made to allow older hardware-banging code to function with new hardware, not everything can or will be compatible. You have been warned. With this in mind, for those developers who (for whatever reason) absolutely insist on using hardware directly, remember these points. (Paraphrased from the Amiga Hardware Reference Manual) Applications must not write spurious data to, or interpret data from, currently unused bits or addresses. Applications must set undefined bits to zero for writes and ignore them for reads. Play it safe -- when reading, mask out ALL the bits EXCEPT the ones you're actually interested in. Known No-Nos This short list represents some known coding strategies that will cause software to function incorrectly on new hardware. * Incorrect allocation of BitMap planes: This problem surfaces because the new chips have an increased fetch bandwidth. Bitplane data must be properly aligned in CHIP memory for this feature to work. Wrong - for(planenum=0; planenumBytesPerRow: Applications that use the supplied system functions to initialize and allocate BitMaps and their elements should be aware that the value of BitMap->BytesPerRow may be different from the expected value, depending on the bandwidth mode chosen, and the asked-for width of the allocated planes. We should explain why, a bit. First, due to fetch-alignment restrictions, we may need a higher granularity (BytesPerRow a multiple of 4 or 8, instead of just 2 under ECS). Second, BytesPerRow actually means two different things, which have always been identical, but aren't any more when using interleaved bitmaps. BytesPerRow officially means "the number of bytes you have to add to a pointer to a byte of the BitMap to get to the same place one row down". It no longer can be depended on to mean "the number of bytes in this row". For interleaved bitmaps, BytesPerRow is quite a bit larger than the number of bytes in this row. GetBitMapAttr( bm, BMA_WIDTH ) can return the true width in pixels. * Improper checking for PAL vs. NTSC: Software which uses release 2.0 (V36) or greater of the OS should NEVER use GfxBase->DisplayFlags to determine whether the machine is running in PAL or NTSC. GfxBase->DisplayFlags is obsolete and may not accurately reflect the desired mode of the user. WRONG- BOOL IsPAL; IsPAL=(GfxBase->DisplayFlags & PAL) ? TRUE : FALSE; Instead, the modeID of the default public screen (or the default monitor, if the default public screen is set to something other than PAL or NTSC (like VGA)) should be checked. Correct- Bool IsPAL; struct Screen *screen; ULONG modeID = LORES_KEY; struct DisplayInfo displayinfo; if (screen = LockPubScreen(NULL)) { if ((modeID = GetVPModeID(&(screen->ViewPort))) != INVALID_ID) { if (!((modeID & MONITOR_ID_MASK) == NTSC_MONITOR_ID || (modeID & MONITOR_ID_MASK) == PAL_MONITOR_ID)) modeID = LORES_KEY; } UnlockPubScreen(NULL,screen); } if (GetDisplayInfoData(NULL, (UBYTE *) &displayinfo,sizeof(struct DisplayInfo),DTAG_DISP,modeID)) { if (displayinfo.PropertyFlags & DIPF_IS_PAL) IsPAL = TRUE; else IsPAL = FALSE; } 39.82 NOTE: If the display mode of the default public screen is double-PAL, DIPF_IS_PAL is not yet set. This will be fixed. Note that if the display mode of the default public screen is "default", and the machine is PAL, and promotion is on, then the default monitor is double-PAL, and the same applies. Again, we expect to set DIPF_IS_PAL for modes of the double-PAL monitor. * Incorrect assumptions about ColorMaps & ColorTables: Because the color system undergoes significant changes, ColorMaps should always be allocated using GetColorMap(); freed using FreeColorMap(); colors changed using LoadRGB4(), SetRGB4(), or SetRGB4CM(); and colors queried using GetRGB4(). Specifically, the value ColorMap->ColorTable and the structure pointed to by it should never be poked or read directly. Unfortunately, the old IFF sample code does NOT call the proper system functions, and instead reads ColorMap->ColorTable directly - This is incorrect, and code based on the original IFF sample code should be checked and changed. The new IFF code (NewIFF.lzh, latest version available in BIX amiga.cert/com/dev listings, sent to ADSP, sent to Fred Fish) has been updated to never access the ColorMap->ColorTable directly. New V39 functions for getting, setting, and loading color registers are provided. These new functions treat color guns (R, G, B) each as 32-bit values for handling both 8-bit guns and any conceivable future needs. Use these new 32-bit color functions when running under at least V39 for future compatibility. When using 4 or 8-bit R/G/B values, scale your values to 32 bits by duplicating your 8 bit value in all 4 bytes of the 32 bit value. When scaling up a 4 bit value, duplicate it in all nibbles. e.g.: 8-bit red value $1F becomes $1F1F1F1F; 4-bit red value $3 becomes $33333333; Important note about NUMBER OF COLORS: Older IFF code (even earlier newiff code) would not load more than 32 color registers. The new code has been updated to base its upper limit for color loading on the ColorMap->Count of the ViewPort of the destination display. Remove old limitations of 32 registers in your code, and replace by limiting to ColorMap->Count registers. The release 2.0 graphics.library VideoControl() function should be used to get, set, or clear the special features associated with ColorMaps. * Poking Copper lists and/or Copinit: The structure and order of Copper lists will change for all modes, so any program that relies on poking the Copper lists will likely break. Certain programs (especially games) make assumptions about copinit and poke it directly -- These programs will break with the new chips. * Dangerous Bits in display hardware: Beware of poking the following bits - In BPLCON0: bits 0, 4, 5, 6, and 7 In BPLCON2: bits 7, 8, 9 In BPLCON3: bits 0,1,6,7, and bits 9 through 15 * Illegal use of the processor to write to BitPlane and Sprite data registers BitPlane and Sprite data registers should NOT be written to by the processor. The correct way for data to be fed to the chips is by setting up DMA that points to the data in CHIP memory. * Illegal re-use of sprites on the same line Attempting to re-use sprites on the same horizontal line by redefining the sprite data is illegal and unsupported. Sprites may only be re-used vertically -- and then only with at least a one line gap between re-uses. See the "Amiga Hardware Reference Manual" for an example of sprite re-use. * Incorrect allocation of sprite Image Data: Because of the increased fetch bandwidth of the new chips, sprite image data must be properly aligned in CHIP memory. Under 2.0, the best way to allocate this memory is to call the exec.library AllocMem() function. * Forgotten FreeSprite(): Sprites may now have a number of different modes. However, under Intuition, these modes are global to all sprites. If a program gets a sprite in a particular mode, but then does not free it, Intuition (and all intuition based programs, including workbench) are forced to use sprites in the mode of the forgotten sprite. In general, it is good practice to not use sprites other than the pointer when coding software that is meant to be Intuition compatible. Taking Advantage of New Features Obviously, new versions of the system software will take advantage of these new chips. But even without new system software, here are some strategies which should allow code to "automagically" take advantage of some of the new software's features. Previously impossible deeper modes: Properly written software can use the calling syntax of the current graphics.library and intuition.library functions to open the ECS screen modes with larger numbers of bitplanes. These modes are simply deeper bitplane versions of existing modes -- lores 6,7, and 8 bits; hires 5,6,7, and 8 bits; super-hires 3,4,5,6,7, and 8 bits; and VGA 3,4,5,6,7, and 8 bits. Obviously, the Display Database must be checked to see if these modes support the desired number of bitplanes before actually trying to use them. Intuition's screen functions should be used to open these previously impossible screens, but programs cannot rely on Intuition to throw out all "bad" possibilities. For example, V36 Intuition will open an 8 bit lores screen, and the 3 high bits simply go unused. Programs will therefore need to explicitly check the display database to find out what the chips support. 39.82 NOTE: Note that starting with this release, Intuition will fail to open a screen which is "too deep". There is a new SA_ErrorCode value, OSERR_TOODEEP. NOTE: The currently defined Display Database ModeIDs have all been moved to the new include file: graphics/modeid.h and .i Do NOT use homebrew modeid's created by OR'ing together monitors and modes. Use only defined modes or modes listed as available in the display database (see AmigaMail, Devcon code, 2.0 RKM Libraries manual, following example, and new screen mode requester example). Given enough chip RAM, this complete example (release 2.0 or greater) will check the display database entry for a LORES screen and open a screen with the maximum allowable number of bitplanes. On an Amiga with any chipset up to and including ECS, this code will open a 5 bitplane screen. On a machine with the next generation chipset, the screen will be 8 bits deep. The code will then draw one vertical line for each available color, using Intuition's "preferred" palette (which is presumably set by the user using preferences.) /* * maxdepthlores.c */ #include #include #include #include #include #include #include #include #include struct IntuitionBase *IntuitionBase; struct GfxBase *GfxBase; extern struct ExecBase *SysBase; void Quit(char whytext[],UBYTE failcode) { if (IntuitionBase) CloseLibrary((struct Library *) IntuitionBase); if (GfxBase) CloseLibrary((struct Library *) GfxBase); printf("%s\n",whytext); Delay(50*10); exit(failcode); } void main(void) { ULONG modeID = LORES_KEY; DisplayInfoHandle displayhandle; struct DimensionInfo dimensioninfo; UWORD maxdepth, maxcolors; ULONG soerror = NULL,colornum; struct Screen *screen; if ((GfxBase= (struct GfxBase *) OpenLibrary("graphics.library",36))==NULL) Quit("graphics.library is too old RastPort),colornum); Move(&(screen->RastPort),colornum,screen->BarHeight + 2); Draw(&(screen->RastPort),colornum,199); } Delay(50*1*6); CloseScreen(screen); } else { /* * Hmmm. Couldn't open the screen. maybe not * enough CHIP RAM? Maybe not enough chips! ;-) */ switch(soerror) { case OSERR_NOCHIPS: Quit("Bummer! You need new chips dude!",25); break; case OSERR_UNKNOWNMODE: Quit("Bummer! Unknown screen mode.",25); break; case OSERR_NOCHIPMEM: Quit("Not enough CHIP memory.",25); break; case OSERR_NOMEM: Quit("Not enough FAST memory.",25); break; default: printf("soerror=%d\n",soerror); Quit("Screen opening error.",25); break; } Quit("Couldn't open screen.",25); } } Opening on Workbench: One of the easiest ways to help a given program peacefully coexist with new hardware is to allow it to open on the Workbench screen (or on any public screen). Software written in such a way that it can operate on any of 2.0's myriad possible Workbench screens should be robust enough that it can find out from the system any information it might need about the environment, and (if it understands the kind of screen that it's on) use the appropriate graphics.library calls to manipulate it's window. Here's some example code that determines the depth of the default public screen and opens a window on it. If it where a real application, the code now has a good idea of how many colors are available on the screen /* depthawarevisitor.c */ #include #include #include #include #include #include #include #include #include struct IntuitionBase *IntuitionBase; struct GfxBase *GfxBase; extern struct ExecBase *SysBase; void Quit(char whytext[],UBYTE failcode) { if (IntuitionBase) CloseLibrary((struct Library *) IntuitionBase); if (GfxBase) CloseLibrary((struct Library *) GfxBase); printf("%s\n",whytext); Delay(50*10); exit(failcode); } void main(void) { struct Screen *screen; struct DrawInfo *drawinfo; struct Window *window; UWORD depth; if ((GfxBase= (struct GfxBase *) OpenLibrary("graphics.library",36))==NULL) Quit("graphics.library is too old dri_Depth; /* Because Intuition allocates the DrawInfo structure, * we have to tell it when we're done, to get the memory back. */ FreeScreenDrawInfo(screen, drawinfo); /* This next line takes advantage of the stack-based amiga.lib * version of OpenWindowTags. */ if (window = OpenWindowTags(NULL, WA_PubScreen ,screen, WA_Left ,0, WA_Width ,screen->Width, WA_Top ,screen->BarHeight, WA_Height, screen->Height - screen->BarHeight, WA_Flags, WINDOWDRAG|WINDOWDEPTH|WINDOWCLOSE|ACTIVATE|SIMPLE_REFRESH|NOCAREREFRESH, WA_Title ,"Big Visitor", TAG_END)) { /* because we're a visitor, we can unlock the screen as soon * as the window is open */ UnlockPubScreen(NULL,screen); printf("depth=%d\n",depth); /* All our window event handling might go here */ Delay(50*10); /* Of course, some other program might come along * and change the attributes of the screen that we read from * DrawInfo, but that's a mean thing to do to a public screen, * so let's hope it doesn't happen. */ CloseWindow(window); } else UnlockPubScreen(NULL,screen); /* OpenWindow failed, but we still have * to let go of the screen. */ } Direct Hardware Access: So many of the internal mechanisms (especially those dealing with color) are changing, that developers who insist on directly hitting the hardware have no real way of writing software today which will even run with, let alone take advantage of, tomorrow's chips. What to Expect From New OS Software Graphics.library: Graphics.library enhanced to handle the capabilities offered by the new chips. Allocation Issues - New functions to properly initialize and allocate structures (like BitMaps and planes) which can take advantage of the chips' new modes. Color Palette Handling - The new chips will handle color in new and different ways. A number of new software features deal with this new color scheme. "RGB" functions - New versions of the "RGB" functions (Set, Load, Get, etc.) which will handle the structure of the new Color Table. Palette sharing - Shared or exclusive access to colors in the current colormap. Display Database - The functionality of the Display Database increased to provide applications with even more detailed information about available modes. Get and Set Functions - Because of the number of changes and extensions to system structures related to graphics, new functions will allow the safe manipulation of these structures. Sprite Handling - New methods of allocating and generating acceptable sprite image data will be provided. Intuition.library: Intuition enhanced to take advantage of the new graphics abilities. Table 1: New Modes (In Addition to Modes Supported by ECS) Mode Planes Colors Bandwidth (See note 1) ---- ------ ------ ---------------------- LORES (320x200) 6 64 1 7 128 1 8 256 1 8 HAM 256,000+ (see note 2) 1 HIRES (640x200) 5 32 2 6 EHB 64 (see note 3) 2 6 HAM 4096 (see note 4) 2 6 64 2 7 128 2 8 256 2 8 HAM 256,000+ (see note 2) 2 SUPERHIRES (1280x200) 1 2 (see note 5) 1 2 4 (see note 5) 1 3 8 2 4 16 2 5 32 4 6 EHB 64 (see note 3) 4 6 HAM 4096 (see note 4) 4 6 64 4 7 128 4 8 256 4 8 HAM 256,000+ (see note 2) 4 VGA (160,320,640x480 non-int.) 1 2 (see note 5) 1 2 4 (see note 5) 1 3 8 2 4 16 2 5 32 4 6 EHB 64 (see note 3) 4 6 HAM 4096 (see note 4) 4 6 64 4 7 128 4 8 256 4 8 HAM 256,000+ (see note 2) 4 Notes: 1 - The "Bandwidth" number describes the amount of fetch bandwidth required by a particular screen mode. For example, a 5 bit deep VGA screen requires the 4x bandwidth fetch mode while a 1 bit VGA screen requires only the 1x mode.. This translates to the hardware having to move data 4 times faster. To be able to move data at these higher rates, the higher bandwidth modes require data to be properly aligned in CHIP memory that is fast enough to support the bandwidth. Specifically, bandwidth fetch mode factors of 1 require data to be on 16 bit boundaries, factors of 2 require 32 bit boundaries, and factors of 4 require 64 bit boundaries. Restrictions like these are the best reason to use the system allocation functions whenever data is being prepared for the custom hardware. It is not guaranteed that all machines that have the new chipset will also have memory fast enough for the 4x modes. Therefore, the ONLY way to know whether or not the machine will support the mode you want is to check the Display Database. 2 - New 8 bit HAM mode uses the upper 6 bits for 64 24-bit base register colors or as a 6 bit modify value, plus the lower 2 bits for 18 bit hold or modify mode control. This mode could conceivably allow simultaneous display of more than 256,000 colors (up to 16.8 million, presuming a monitor / screenmode with enough pixels.) Please note that while the register planes and control planes are internally reversed in 8 bit HAM (the control bits are the two LSBs instead of the two MSBs), programs using graphics.library and intuition.library will not have to deal with this reversal, as it will be handled automatically for them. 3 - This is like the original EHB mode, but in new resolutions. It uses 5 bits to yield 32 register colors, plus a sixth bit for 32 colors that are 1/2 as bright. 4 - This is like the original 6 bit Ham mode, but in new resolutions. It uses the lower 4 bits for 16 register colors, plus the upper 2 bits for modify mode control. This mode allows simultaneous display of 4096 colors. 5 - These modes are unlike the old VGA and SUPERHIRES modes in that they are not restricted to a nonstandard 64 color palette.