How to write demos that work (Version 6) - 13/5/93 ================================================== (or the Amiga Demo Coders Reference Manual) Edited by Comrade J/SAE Co-Editor Carl-Henrik Skårstedt (Asterix/Movement) email:comradej@althera.demon.co.uk IMPORTANT: HowToCode docs are currently in theta state. Do not rely on any information in these documents! Mistakes are almost certain. Please report mistakes to the first email address above. INTRODUCTION ------------ NEW FORMAT - The original text file got too big and unfriendly, so it's now split into lots of little text files and source files in one big friendly .LHA file. Thanks to everyone who mailed me, see if you hassle me enough I *may* listen to what you say! * Please note this is a REPLACEMENT to text files howtocode1.txt through howtocode5.txt. Sysops, please remove these earlier files as they contain many mistakes. Thanks in advance...* Thanks to: Richard Aplin, Matthew Arnold, Andreas Axelsson, Michael Bauer, Nils Liaaen Corneliusen, Walter Dao, David Dustin, Chris Green, Joep Grooten, Grue, Arno Hollosi, Lars Holmgren, Philip Jespersen, Irmen de Jong, Marius Kintel, Christopher Klaus, Mark G Knibbs, Jesper R Larsen, Jacco de Leeuw, Tero Lehtonen, Patrik Lundquist, Jonas Matton, Stanley Merkx, Jesse Michael, Richard Moeskops, John Derek Muir, Karsten Niemeier, Boerge Noest, Mats Olsson, Andrew Patterson, Raymond Penners, Vidar Petursson, Michael Pollard, Vic Ricker, Timo Rossi, Michael Ryffel, Conrade Sanderson, Doz/Shining, Toby Simpson, Darrell Tam, Lehtonen Tero, Magnus Timmerby, Yee Tom, and Michel Vissers for their comments and contributions. Please note that this file is the work of many authors, although the spelling mistakes are all my fault! Introduction ============ This file has grown somewhat from the file uploaded over Christmas 1992. I've been very busy over the last two months, so I'm sorry that I haven't been able to update this sooner. It started as an angry protest after several new demos I downloaded refused to work on my 3000, and has ended up as a sort of general how-to-code type article, with particular emphasis on the Amiga 1200. Now, as many of you may know, Commodore have not released hardware information on the AGA chipset, indeed they have said they will not (as the registers will change in the future). Demo coders may not be too concerned about what is coming in a year or two, but IF YOU ARE WRITING COMMERCIAL SOFTWARE you must be. Chris Green, from Commodore US, asked me to mention the following: "I'd like it if you acknowledged early in your text that it IS possible to do quite exciting demos without poking any hardware registers, and that this can be as interesting as direct hardware access. amiga.physik.unizh.ch has two AGA demos with source code by me, AABoing and TMapdemo. These probably seem pretty lame by normal demo standards as I didn't have time to do any nifty artwork or sound, and each only does one thing. but they do show the POTENTIAL for OS friendly demos." I have seen these demos and they are very neat. Currently you cannot do serious copper tricks with the OS (or can you Chris? I'd love to see some examples if you can...), for example smooth gradiated background copperlists or all that fun messing with bitplane pointers and modulos. But for a lot of things the Kickstart 3.0 graphics.library is capable of lots. If you are in desperate need for some hardware trick that the OS can't handle, let Chris know about it, you never know what might make it into the next OS version! Chris mentions QBlit and QBSBlit, interrupt driven blitter access. These are things that will make games in particular far easier to write under the OS now. Chris also says "Note that if I did a 256 color lores screen using this document, it would run fifty times slower than one created using the OS, as you haven't figured out enhanced fetch modes yet. A Hires 256 color screen wouldn't even work." There are some new additions to the AGA chapter that discuss some of this problem, but if you want maximum performance from an AGA system, use the OS. Remember that on the A1200 chipram has wait-states, while the 32-bit ROM doesn't. So use the ROM routines, some of them run faster than anything you could possibly write (on a A1200 with just 2Mb ram). The only drawback is again documentation. To learn how to code V39 OS programs you need the V39 includes and autodocs, which I'm not allowed to include here a) because I've signed an NDA, and b) because they're massive... Perhaps, in a later release, I'll give some highlights of V39 programming... Get Chris Green's example code, it's a good place to start. Register as a developer with your local Commodore office to get the autodocs and includes, it's relatively inexpensive (£85 per year in the UK) Most demos I've seen use similar startup code to that I was using back in 1988. Hey guys, wake up! The Amiga has changed quite a bit since then. Thanks to everyone who has replied. Any more questions, queries, or "CJ/CH, you got it wrong again!" type mail to the email address below.... What I want: =========== If anyone wants to spend some time writing something on these (especially from a demo coders perspective) I'd be very grateful. I would write some of them myself if I had more time... I'm also looking for an FTP site to use as the official howtocode site. If you are an FTP administrator and can offer us this facility, please email me! o 68881/2 Programming o How to set up an input handler o Reading the new Motorola syntax code And anything else you want to write about. Please feel free to write additions/replacements for anything already here... And of course, if anyone spots a *really* bad bit of code or programming practise, let me know and I'll warn people about it here... (Don't send my old code though :-) I still have not tested the sorting-routines in Vectors.txt, but they should work all right as they are. If you spot VERY ugly things in them, please report... And a final comment: For those of you who wrote about Amazing Tunes II (a demo I wrote 2 years back) wanting to know how to get it to run on a 1Mb chipram machine... Sorry. It doesn't. It probaby breaks *every* rule in this docfile. I speak from experience. I used to be that evil programmer :-) Disassemble the bootblock to see some nightmare code... You can probably patch it if you're clever. It was meant to support 1Mb chipram but it never worked.. If you have 1.5Mb of ram (be it chip, fast or a mixture) it should work though... I had to totally rewrite it recently for The Demo Collection CDROM It now plays 1000 modules (instead of 20), is much more system friendly and works on a (less than) 1Mb chipram CDTV. And you never know, if enough people ask I may do an AGA version, possibly on an Intuition screen... That would be nice! -------------------------------------------------------------------- This text is Copyright (C) 1993 Share and Enjoy, but may be freely distributed in any electronic form. The copyright of contributions quoted from other authors remains with the original author. If you would like to contribute to this file, email me at the address below... If you intend to use part or all of HTC in a Public Domain disk magazine (or similar), please email me first. I *will* give permission freely, but I want to make sure that only the latest versions are published. Please also mention your request to Carl-Henrik, especially if it concerns Vectors.txt since it will be continually updated and debugged for some time from now. The startup code in this article is freeware and may be used by anyone for any purpose. All trademarks and registered names (Workbench, Kickstart, etc) acknowledged. All opinions expressed in this article are my own, and in no way reflect those of anyone else. Please note that many of the programming practices described in this text are ONLY applicable for demo coding, and should not be used for Games and other programming. I didn't write this for fun, I wrote it for you to use! If you want to make a contribution please email it to me: I prefer plain ASCII set to no more than 75 column width, and no tabs if possible (although I can fix text sent to me..) If you strongly disagree with anything I write, or you want to send me some source or demos to test on Amiga 1200/4000 etc, or you have questions about Amiga programming, or suggestions for future articles, or just want to chat about the best way to optimise automatic copperlist generation code (*), then contact me via email at: Please send mail to comradej@althera.demon.co.uk. I CAN NOW REPLY TO MAIL!!! At last, thanks to AmigaElm and some ARexx I can reply to mail! If you sent me a message and haven't got a reply, it's because I lost the message, please mail me again! Sorry about the delays before! I seem to have lost usenet news now, so I haven't read anything from alt.sys.amiga.demos since early January. * - This is a NIGHTMARE. I really feel sorry for the guys who wrote MrgCop(). I will never swear at MrgCop() or RethinkDisplay() again :-)