P·HYDRA DOCUMENTATION: USEME

=== P·HYDRA DOCUMENTATION ===
The "How To Use It" File

(USEME, ver L5M)

Firstly,

Before getting into this file, you should have a general understanding of what P·HYDRA is and how it works. Visit the P·HYDRA info page at: <http://p-hydra.laemeur.com/>. That page (an HTML version of the 'WHAT' file) has a description of the program, download links, and the most recent versions of the OPS, OPS_QREF, KEYS, and USEME files (collectively, the DOCS).

Caveat

Terminology may be kind-of inconsistent in this and the other documention. Apologies for that. Generally, I try to refer to P·HYDRA as "the program", and the programs that P·HYDRA runs as "sequences", but sometimes I use "programs". Also, "head" and "playhead" are the same thing. Also also, I usually refer to P·HYDRA's instructions as, um, "instructions", but you may also see "ops", "operations", and "commands". Same thing. Sorry.

SECTIONS IN THIS FILE

1. The Interface
2. MAKE IT GO
3. Load/Save
4. PCM Samples
5. FM Synthesis

SECTION 1: THE INTERFACE

P·HYDRA's interface is more-or-less a simple hex editor: the screen shows one page of the computer's RAM (256 bytes), and you have a little blinking cursor that you can move around and use to change the contents of the computer's memory. The hex editor takes up most of the screen, but there are five tiers of information shown:

TIER 1 The info bar
TIER 2 The AUDCTL status bar
TIER 3 The hex editor
TIER 4 Command disassembly
TIER 5 Useless decorations

TIER 1: The Info Bar

The info bar presents some of the essential information you need to operate the program, or at least to help you figure out what the hell the program is doing at any given time. It's laid-out like this:

INPUT | CUR. | ACT. HEAD | HEAD LOCATIONS | DELAYS | ( ignore
__ | | # LOC. | 1 2 3 4 5 6 | 1 2 3 4 5 6 | this crap
00-00-00-00 | 00-00 | 00 00-00 | 00-00 00-00 00-00 00-00 00-00 00-00 | 00 00 00 00 00 00 | ... )

INPUT

The editor has a four-byte input buffer, and its contents are displayed here. Every time you type a hexadecimal digit, its value is pushed onto the right side of the input buffer. So you could type:

0 0 0 F 0 0 0 0

And the input buffer will fill up with "00 0F 00 00" (which is an instruction to do nothing and immediately process the next instruction in the sequence). If you press [Enter] at any time the byte under the cursor in the hex editor will be replaced with the lowest (right-most) byte in the input buffer. If you press [Ctrl]+[Return], the entire four-byte input buffer will be copied into the instruction block that the cursor is currently placed in.

CUR.

Short for "cursor", obv. This shows the current cursor location in memory. This is little-endian, so if your cursor is on the second byte of page 0x40, this will read "01 40", not "40 01".

ACT. HEAD # LOC.

Active head number and location. As the sequencer is running, these are updated to show which head is currently being processed, and what its memory location is (again, little-endian). This can be handy if your sequence/program gets stuck in a weird loop and you don't know where it's getting stuck.

HEAD LOCATIONS

Pretty self-explanatory: the program counter values for each of the heads.

DELAYS

The values of each head's delay register.

TIER 2: The AUDCTL Status Bar

The AUDCTL status bar is a row of sixty-four chunky pixels. Only the first eight are of any importance. They represent the state of each bit in POKEY's AUDCTL register, left-to-right, bit 7 to bit 0. For a refresher on what they mean, I'll copy in this great little chart out of De Re Atari (Chapter 7):

If set, this bit...
0 0 0 0 0 0 0 0
| | | | | | | |
| | | | | | | +-- Switches main clock base from 64Khz to 1.79Mhz
| | | | | | +---- Inserts high-pass filter into channel 2, clocked by channel 4
| | | | | +------ Inserts high-pass filter into channel 1, clocked by channel 3
| | | | +-------- Joins channel 4 to channel 3 (16 bit resolution)
| | | +---------- Joins channel 2 to channel 1 (16 bit resolution)
| | +------------ Clocks channel 3 with 1.79Mhz
| +-------------- Clocks channel 1 with 1.79Mhz
+---------------- Makes the 17-bit poly counter into a 9-bit poly-counter

You can toggle the AUDCTL bits by pressing [Ctrl]+[1], [2], [3], ...[8] on the keyboard, which correspond visually with the bits as shown on the screen. That is, [Ctrl]+[1] toggles AUDCTL bit 7, the left-most bit/key, while [Ctrl]+[8] toggles AUDCTL bit 0.

The remaining fifty-six pixels on the line are just blinkenlights. It's not that they don't represent actual variables in the program, it's just that they aren't terribly useful displayed in that fashion.

TIER 3: The Hex Editor

This is where all the work gets done. The hex editor section shows a single page of system RAM, laid out as eight rows of 64 bytes. Because P·HYDRA instructions are all four bytes long, this is more like an 8x8 grid of instructions.

P·HYDRA reserves 64 pages of RAM for program storage, starting at page 0x40. When the program is first loaded, the cursor is placed at 0x4000, so that's the first page of RAM you'll see. You're not restricted to this area of RAM, though! If you are so inclined, you can browse right on down into OS RAM and change stuff around and crash the computer. If that's your thing, go for it.

To edit your program (or anything else in RAM), you use the arrow keys* to move the cursor around. You can move it by bytes, instructions (four bytes), lines (64 bytes/8 instructions), or pages (256 bytes/64 instructions). As mentioned above, you can change individual bytes or entire four-byte instructions using the input buffer; you can also increment and decrement bytes, copy bytes and instructions to/from the input buffer, insert blank instructions, delete instructions ...

I bet you'd love to know which keys to press to do all of those things. Well, have a look at the KEYS file for that!

* Actually, the keys that the arrows are PRINTED on move the cursor, so, "-" is UP, "=" is DOWN, "+" is LEFT, and "*" is RIGHT. This is sort-of annoying when using P·HYDRA in emulation, but it saves you having to hold CTRL when moving the cursor on a real Atari.

You can also use the "G" key to GO TO a specific page of RAM. Just type the page number into the input buffer and press G; the cursor will be warped to the specified page, but its byte offset into the page will be the same. So, if the cursor is currently at 0x4032 and you type "5 0 G", then the cursor's location will change to 0x5032.

When the cursor moves around, the instruction disassembly line is updated, which is the next tier:

TIER 4: Instruction Disassembly

It can be a bit hard to remember all of P·HYDRA's opcodes as hexadecimal digits, so below the hex editor is a single line of text showing a disassembly of the 4-byte instruction under the cursor. The line shows:

Of course, the command disassembly line is also handy because the tiny text in the hex editor section can be damned hard to read.

TIER 5: Useless Decoration

Looks nice, don't it?

SECTION 2: MAKE IT GO

Oh, right. We do want the sequence to run at some point, don't we?

Okay, here's how that works.

Keys T, Y, U, I, O, and P are the on/off toggles for each of the six heads. To start running a sequence/program, you have to turn on one of the heads to make it start reading instructions.

When P·HYDRA loads, the program counter of all heads is set to 0x4000. A sample sequence should also be loaded when P·HYDRA first fires-up, so you can simply press "T" to turn on head #1 and make it start slurping-up instructions.

To start a head at a specific address, move the cursor to where you want the head to start reading instructions and press [Ctrl] plus the corresponding head toggle key. This will set the head's program counter to the cursor's location. If the head is currently disabled, you'll have to press its toggle key to make it start reading instructions. If the head was already enabled, it will automatically start reading instructions from the new address as soon as its delay counter counts down to 0.

SECTION 2.1: MAKE IT STOP

[Ctrl] + [R] will reset POKEY and disable all of the heads. Because sometimes... the noise... dear god.

SECTION 3: LOAD/SAVE

You can save and load sequences to a floppy disk. This has been implemented in about the most half-assed way imaginable, but it works.

Pressing [Ctrl] + [S] will Save the current sequence to a file named "PRG" on whatever floppy is inserted in drive #1. [Ctrl] + [L] will load "PRG" from the currently inserted disk in drive #1. That's it.

Want to save multiple programs to a disk? Too bad! One sequence per floppy. And no warnings about overwrites or missing files or any of that stuff. It's 2019, for heaven's sake. We're all using SD cards or SIO2PC interfaces these days, and disk images are basically free and can be duplicated by the thousand in seconds. If you're using physical floppy disks for that authentic experience, well, you must own boxes of the things, right? I know I do.*

Also, since there's no real "release" version of the software, and because the instruction set can be broken at any time, it's good to just save your sequences along with a disk that boots the version of P·HYDRA that they were written in.

* But seriously, I would like to make disk save/load more sane and useful some day.

SECTION 4: PCM SAMPLES

P·HYDRA gives you the ability to load a single PCM waveform into memory, and you can play it back in sequences with the GOPCM operation (opcode 30). Yes, that's right, A SINGLE 8-bit, 2kHz digital sample!

Actually, as I write this the "loading" part of this feature is not implemented. Rather, if you're assembling from source you can assemble-in a sample, but I haven't gotten around to doing the disk loader. The current P·HYDRA binary ships with a sample of a Roland TR-909 kick drum built-in, just because it's so hard to get a decent kick drum sound with POKEY.

At some future time, though, yes, you'll be able to load PCM samples from disk.

SECTION 5: FM SYNTHESIS

This is my main contribution to the sonic landscape of POKEY music. No, this will not turn your Atari into a DX7, or even an AdLib card, but it can make some gnarly new noises that were not previously available on the Atari 8-bit.

Bascially, P·HYDRA has a sample-based sine-wave oscillator that you can use as a modulator for voice #4's square-wave. That's it! Alternatively, you can run voice #4 in volume-only mode to just get the sine-wave.

For the low-down on how it works, take a look at the GOFM, SETFMF, and SETFMC operations in the OPS file.

SECTION SECTION: SPECIAL SECTION

Um. That's it, I guess?

-L.

=== END P·HYDRA DOCUMENTATION FILE "USEME" ===