WINUAE Demo Toolchain 5

Put together by Hannibal/Lemon. 

***************************************
WHAT?
A single setup that has EVERYTHING you need for WinUAE development. A Full toolchain for pixeling, tracking and coding. Just add creativity and hard work.
Running examples for bootblocks and single-file demos, with ship-quality system-friendly startup code that works with all Amiga platforms.
Everything should be freeware or redistributable shareware.
10 seconds to build and launch in the emulator 

***************************************
WHY?
When I started getting back into amiga programming, there was no complete package and just lots of loose bits there are. I wanted to set it up once and for all, and share it out. So here it is - a one-stop shop for amiga demo making (and game making, for that matter).
I also know from  my professional life that a lot of people are too lazy to set up good workflows for themselves - in many cases because they have never seen how easy and fast it can be. I knew I could do a one-click, 10-second build and run solution.
I was originally planning to make a giant surprise return demo, which is why I made the previous releases under the name XXXXX. However after years of life getting in the way, I realize that I just don't have the free time to make a demo to live up to my ambitions. Instead, I've been having fun tweaking this setup, so it's time to share it out.

My own contributions to this toolchain are public domain. Use at your own risk. I believe all the code included has fairly liberal licenses, but you should read those licenses if you make tweaks to them. The only exception is CopyToAdf. CopyToAdf uses AdfLib which is GPL, therefore CopyToAdf is infested with GPL as well.


***************************************
WHAT DOES IT INCLUDE?
In General:
	command-line WinUAE launchers for all common Amiga configs for single-file single-disk, and double-disk demos.
		WinUAE launchers support both AmigaForever and regular ROM formats, and the built-in AROS rom.
	WinFellow launcher for single-disk and double-disk demos
	Dual harddrive setup - all tools and temp files on dh0, all art and sound files on dh1
	Most commands and tools have .bat files stored in the root of the package, to make it easy to get started.
Music:
	one-click WinUAE launchers for Protracker (2.3d, 3.15 and 3.62), OctaMED, Future Composer, AHX, and TFMX (TFMX requires separate download)
	one-click launcher for protracker on win32 
	one-click WinUAE launcher for DeliTracker player
	command line bat-file for wav-to-raw conversion
	PT-01 and PT-02 sample disks
Art:
	one-click launcher for Grafx2
Code:
	one-click build-and-run example for both bootblock and single-file demos
		single-file demo example can use music players for protracker,tfmx,OctaMED, Future Composer, and AHX, and shows how to convert and use attached sprites, copperbars, proportional width fonts, and half-brite images
		bootblock demo includes a packer and reports spare size 
	command line bat-file for Mod-to-p61 conversion (so you can have one-click builds on PC even if you use The Player)
	one-click WinUAE launcher for P61Con (so you can hand convert a file) and Titanics Cruncher.
	command line image converter (KingCon), supporting images, fonts (monospace and proportional), animations, per-line palette conversion, and copper bars. Supports batch conversion
		including some sample art
	Visual Studio 2013 solution setup - single click to build, single click to launch
	Debug and Release builds.
	Visual Studio syntax highlighting (Linguist)
	command line tool (CopyToAdf) to create empty ADF, write tracks, write bootblocks
	command line tool (shallow) to prettify 68k assembler code
	sine generator
	Shrinkler
	How2Code documentation
	
	
***************************************
HOW DO I INSTALL IT?
1. Unpack all files into a folder

2. run ExampleBootblock\BuildAndRunBBAros.bat or ExampleDemo\BuildAndRunDemo.bat (non-Aros versions are set to run in a500 mode instead). 

3. if this doesn't launch the test bootblock/example demo then maybe something is messing up WinUAE's settings. You may have used WinUAE before, and that may have put some info in your registry. In that case, run DestroyOldUAESettings.bat, and try again

4. Get hold of the kickstart roms (1.3, 2.04, 3.0 and 3.1-a4000) and workbench 3.1 (without these step, you can only run AROS). http://www.amigaforever.com/ is the easiest (and the legal) way to get them

5. Run Toolchain\AdfView\setup.exe - this will allow you to open ADF files in windows as if they are just subfolders.

6. copy kickstart roms (either kick??.rom or the AF roms+rom.key from the AF DVD's \Amiga Files\Shared\rom) into the WinUAE folder. Without them, you can't run ConvertModToP61 and many of the tools.

7. Use AdfLIB to crack open the workbench 3.1 and copy the c and libs folders on top of the dh0\c and dh0\libs folders. Without this step, many tools may not work. For example the P61 converter (needed for mod player) will not launch.


***************************************
TO JUST LAUNCH STUFF
1. run startdelitracker.bat to listen to music. Protip - download music for your DH1 folders. modland.org has many old demo songs.
2. to launch a standalone demo, use the command line format runXXX.bat ExeName (use any of the 11 winuae/winfellow permutations). It will automatically copy the file over to the temp drive before launching
3. to launch a single disk demo, use runXXX.bat diskimagename.adf/dms 
4. to launch a dual disk demo, use runXXX.bat diskimagename1.adf/dms diskimagename2.adf/dms

***************************************
FOR MUSICIANS ONLY
1. If you want to mess with TFMX, you have to download TFMX_V1.6_7v_fixed.lha and unpack it into the TFMX folder.

2. run startProtracker23d.bat, startProtracker315.bat, startProtracker362.bat, StartProtrackerWin32.bat, StartTFMX.bat, StartFutureComposer.bat, StartOctaMEDSoundStudio.bat, or StartAHX.bat to start tracking.

3. Load samples from dh1\iffsamples

4. Save your modules on dh1. There are already samples for some programs there.

5. to convert samples to protracker-friendly iff format
	a. just put a wav-file (xxx.wav) in dh1\wavsamples - subfolders are fine
	b. run ConvertWavToIff.bat xxx.wav [note] (note defaults to C3)
	c. you now have a matching xxx.iff in dh1\iffsamples

***************************************
FOR ARTISTS ONLY
1. run startgrafx2.bat to start pixelling. Save your stuff on dh1\art. There is a number of samples there

***************************************
FOR CODERS ONLY
1. If you don't have Visual Studio 2013 already installed, then you should get it. Visual Studio 2013 Community edition is now free - download it at https://www.visualstudio.com/en-us/products/visual-studio-community-vs.aspx

2. install toolchain\linguist.vsix if you want syntax highlighting

2b. you have to manually change the colors in tools->options->fonts and colors for the display items - that somehow doesn't transfer over from the style file:
Keyword, Keyword2, Header4, Header5, Comment, Number, string. There may be multiple dupes with upper/lower cases, so just set both)

3. Open WinUAEToolchain.sln (if you want to play with the tools) exampledemo.sln or examplebootblock.sln in VS2013, and press f5 to build and launch.

3b. the BuildAndRun bat files in the examples take care of everything -  Visual Studio doesn't do anything other than call the bat file. For exampledemo, it converts music and art, assembles and links, and optionally packs the final file. For Examplebootblock, it assembles and links, optionally packs the block, creates a disk image and puts the bootblock on there. It also runs a code prettifying pass, and launches the example. It takes a couple of parameters: -debug (set the Debug macro to 1 - this  disables packing, and shows some copper colors), -dontrun (build only) -dontbuild (run last build), -aros (use aros rom instead of kickstart). 

3c.  buildAndRunDemo.bat file also contains a value for which musicplayer to use. - try to set it to 1-5 (3 and 5 of them will try to load modules that are not included in this package)

4. download  "Amiga Hardware Reference Manual" - maybe look in http://amiga-manuals.xiik.net/ebooks? - and some manual for the 68000

5. you may want to download notepad++ or something else as notepad doesn't do well with unix format text files. Go to http://ninite.com to install notepad++

6. To generate a sine table, use startSineCreator.bat

7. to manually crunch a file, use toolchain\shrinkler.exe or StartTitanicsCruncher.bat

8. to manually convert a mod-file to p61 format, run startp61converter.bat

9. to automatically convert a mod-file to p61 format, run convertModToP61.bat modfilename.mod p61filename.p61 [mode] - mode can be OneFile, OneFile_Delta, OneFile_Delta_PackSample, TwoFiles, TwoFiles_Delta, TwoFiles_Delta_PackSample

10. to write files to a disk image, create a disk image, write sector, write a bootblock, or copy files to an disk image, use toolchain\CopyToAdf.exe. Parameter /? gives you the full description of all options

11. to prettify a file or a number of files, run toolchain\Shallow  -i inputfile -o outputfile [options] or -l listfile [options]. Parameter -? gives you the full description of all options

12. to debug, press shift+f12 inside WinUAE. I usually use "w 4 4 4 w" to set a breakpoint, to use with my WinUAEBreakpoint macro

12. to convert a single image or a batch of images, run toolchain\KingCon. There are options up the wazoo, so check it out. Parameter -? gives you the full description of all options
	This is not very thoroughly tested. It focuses heavily on ocs/ecs support, but I threw in some aga features (sprite width, 24-bit palettes) with some limitations. I tried to make it complain wherever possible
	Special features include:
	Formats: chunky, sprite, attached sprite, bitplanes, ehb, and "vertical fill table" format
	Modes: convert images, multi-file animations, bobs, monospace fonts, or proportional fonts.
	Options: x/y/width/height/rotate/flip, trim unused space, mask on/off/inverted, extra blit word, sprite control word on/off, interleaved, save palette as raw or as copperlist 
	Saves files as binary, c-format (char/short, hex or decimal) or asm-format
	batch conversion support
	Automatically tries to downconvert non-palletized images where possible. Reads many formats. It should read alpha channel where possible and use as mask color
	Per-line color mode - if images have more colors than allowed, this saves out an per-line pallette change list, optimized for the smallest number of palette changes.
	Font generation creates an ascii-to-bob index remapping table
	Saves a preview image helps to show what is actually stored in raw files - helpful to see that the saved data is actually valid (because it generates the preview image from the saved data, not the source data).	

***************************************
CREDITS
Here is a list of the stuff I pulled together, in random order:

Main Tools

	WinUAE by Bernd Schmidt, Toni Wilen, Brian King (and many others)

	WinFellow by Petter Schau, Worfje, Torsten Enderling

	vasm/vbcc/vlink by Volker Barthelmann.  Repackaged with permission.
		this is a stock recompilation without changes. 
		For vasm/vbcc/vlink licensing agreement please see manuals\vbcc.pdf, manuals\vasm.pdf, and manuals\vlink.pdf
		VBCC/VASM also worked on by Frank Wille and others
		This package was originally based on Kusma's amiga-dev toolchain, but almost everything is rebuilt since then


Bootblock example uses
	bootblock startup code - Blueberry/Loonies
	Packfire by Hitchhikr/Neural

Demo example uses
	demo startup code - Blueberry/Loonies
	Shrinkler - Blueberry/Loonies
	various music players

KingCon uses
	FreeImage by Floris van den Berg, Hervé Drolon, and others

CopyToAdf uses
	AdfLib by  Laurent Clévy, Bjarke Viksoe, Gary Harris, Dan Sutherland

Shallow uses
	68000 Linguistics definition file originally set up by 71M (but practically completely redone by me)
	
ConvertWavToIff uses
	SoundExchange by Chris Bagwell and others

convertModToP61 uses 
	Scripit - Khalid Aldoseri
	P61Con (and The Player source) by - Guru/Sahara Surfers,Photon/Scoopex,NoName,Platon42,Tolkien,The Dark Coder
	
Standalone tools
	Grafx2 by Sunset Design (G.Dorme & K.Maritaud) and A.Destugues & Y.Rizoud
	
	Future Composer - SUPERSERO of THE SUPERIONS and Jochen Hippel

	AHX by Dexter/Abyss
	AHX User guide redux by Lavaburn,Deltafire,Syphus,Xeron

	Protracker2.3d by crayon/noxious, ZAP/The Amiga Freelancers, Detron and Duff, Karsten Obarski
	Protracker3.15 by Outland/Cryptoburners, ZAP/The Amiga Freelancers, Karsten Obarski
	Protracker3.62 by TTL/Osiris, ZAP/The Amiga Freelancers, Karsten Obarski
	Protracker Win32 - Olav "8bitbubsy" Sorensen
	Protracker Command Reference by Dopefish

	Octamed Soundstudio by Teijo Kinunnen

	TFMX by Chris Hülsbeck, Peter Thierolf, Jochen Hippel and fixes by Jonathan H. Pickard
	TFMX player source and documentation by Jonathan H. Pickard

	DeliTracker by Frank Riffel and Peter Kunath

Assets
	PT-01 and PT-02 by Photon/Scoopex
	sample art and music the rest by various old group mates - Facet, Slash, Mikael Balle, Jesper Kyd, Julius 

Misc
	AdfView by  Bjarke Viksoe

	Sine Creator by Grokk and Fred of The Gang

	Linguist by Jesse Jones

	Winguide by Steven Eckles

	Titanics Cruncher by Triad and Zulu / Titanics

	jumptype by Amigaman Designs / Wizzcat

	MemPeek by Futuresoft

	HowToCode, startup code snippets, iconstartup, autogen files - Comrade J / SAE

Phew, I hope that is everything




