CPCWiki - THE Amstrad CPC encyclopedia! - User contributions [en]

Technical information about Locomotive BASIC

2007-03-14T17:47:15Z

80.167.220.254:

The are two versions of Locomotive BASIC used in the Amstrad CPC and CPC+ computers. v1.0 is used by the CPC464, and v1.1 is used by the CPC664, CPC6128, CPC464+ and CPC6128+.

== Passing parameters to a RSX (Resident System Extension) command or binary function ==

A RSX (Resident System Extension) command is accessed through BASIC with a "|" character prefix. e.g. The "DIR" RSX, is accessed by "|DIR".

A binary function is accessed through BASIC using the "CALL" command.

Passing a string parameter:

BASIC v1.0

a$="A":|DRIVE,@a$

BASIC v1.1:

|DRIVE,"A"

== Additional keywords and variables in BASIC v1.1 ==

* BASIC v1.1 has the following additional keywords:

:* COPYCHR$
:* CURSOR
:* DEC$
:* FILL
:* FRAME
:* GRAPHICS
:* MASK

* BASIC v1.1 has the following additional predefined variables:

:* DERR

== Entering BASIC programs ==

A maximum of 255 characters can be entered for a single BASIC line.

This is converted into the tokenised BASIC program which is more compact than the line entered. The BASIC keywords are converted into "tokens", or 1-2 byte sequences which uniquely identify each keyword.

== Structure of a BASIC program ==

A BASIC program is stored in a tokenised format. Here the keywords are represented by 1 or 2 byte unique sequences.

Each line of the BASIC program has the form:

{|{{Prettytable|width: 700px; font-size: 2em;}}
|''Offset''||''Size''||''Description''
|-
|0||2||Length of line data in bytes (note 1)
|-
|2||2||16-bit decimal integer line number (note 2)
|-
|4||n||BASIC line encoded into tokens (note 3)
|-
|n+1||1||"0" the end of line marker (note 4)
|-
|}

'''Notes:'''

* This 16-bit value has two functions:
:* if "0" it signals the end of the BASIC program. In this case, there is no furthur BASIC program lines or data.
:* otherwise, this value defines the length of the tokenised BASIC program line in bytes, and includes the 2 bytes defining this value, the 2 bytes defining the program line number, and the end of line marker. This number is stored in little endian notation with low byte followed by high byte.
* This 16-bit value defines the line number and exists if the length of line data in bytes is not "0". A line number is a integer number in the range 1-65535. This number is stored in little endian notation with low byte followed by high byte.
* This data defines the tokenised BASIC program line and exists if the length of line data in bytes is not "0". The length is dependant on the BASIC program line contents.
* This value defines the end of the tokenised BASIC line data and exists if the length of line data in bytes is not "0". The BASIC interpreter looks for this token during the processing of this line, and if found, will stop execution and continue to the next line.

== BASIC tokens ==

This table list the BASIC tokens with no prefix byte.

{|{{Prettytable|width: 700px; font-size: 2em;}}
|''Code (hexidecimal)''||''BASIC Keyword''
|-
|&00||end of tokenised line marker
|-
|&01||":" statement seperator
|-
|&02||integer variable definition (defined with "%" suffix)
|-
|&03||string variable definition (defined with "$" suffix)
|-
|&04||floating point variable definition (defined with "!" suffix)
|-
|&05||var?
|-
|&06||var?
|-
|&07||var?
|-
|&08||var?
|-
|&09||var?
|-
|&0a||var?
|-
|&0b||variable definition (no suffix)
|-
|&0c||variable definition (no suffix)
|-
|&0d||variable definition (no suffix)
|-
|&0e||number constant "0"
|-
|&0f||number constant "1"
|-
|&10||number constant "2"
|-
|&11||number constant "3"
|-
|&12||number constant "4"
|-
|&13||number constant "5"
|-
|&14||number constant "6"
|-
|&15||number constant "7"
|-
|&16||number constant "8"
|-
|&17||number constant "9"
|-
|&18||number constant "10"
|-
|&19||8-bit integer decimal value
|-
|&1a||16-bit integer decimal value
|-
|&1b||16-bit integer binary value (with "&X" prefix)
|-
|&1c||16-bit integer hexadecimal value (with "&H" or "&" prefix)
|-
|&1d||16-bit BASIC program line memory address pointer
|-
|&1e||16-bit integer BASIC line number
|-
|&1f||floating point value
|-
|&20||" " (space) symbol
|-
|&21||ASCII "!" symbol
|-
|&22||quoted string value
|-
|&23-7b||ASCII printable symbols
|-
|&7c||"|" symbol; prefix for RSX commands
|-
|&80||[[AFTER]]
|-
|&81||[[AUTO]]
|-
|&82||[[BORDER]]
|-
|&83||[[CALL]]
|-
|&84||[[CAT]]
|-
|&85||[[CHAIN]]
|-
|&86||[[CLEAR]]
|-
|&87||[[CLG]]
|-
|&88||[[CLOSEIN]]
|-
|&89||[[CLOSEOUT]]
|-
|&8a||[[CLS]]
|-
|&8b||[[CONT]]
|-
|&8c||[[DATA]]
|-
|&8d||[[DEF]]
|-
|&8e||[[DEFINT]]
|-
|&8f||[[DEFREAL]]
|-
|&90||[[DEFSTR]]
|-
|&91||[[DEG]]
|-
|&92||[[DELETE]]
|-
|&93||[[DIM]]
|-
|&94||[[DRAW]]
|-
|&95||[[DRAWR]]
|-
|&96||[[EDIT]]
|-
|&97||[[ELSE]]
|-
|&98||[[END]]
|-
|&99||[[ENT]]
|-
|&9a||[[ENV]]
|-
|&9b||[[ERASE]]
|-
|&9c||[[ERROR]]
|-
|&9d||[[EVERY]]
|-
|&9e||[[FOR]]
|-
|&9f||[[GOSUB]], [[GO SUB]]
|-
|&a0||[[GOTO]], [[GO TO]]
|-
|&a1||[[IF]]
|-
|&a2||[[INK]]
|-
|&a3||[[INPUT]]
|-
|&a4||[[KEY]]
|-
|&a5||LET
|-
|&a6||LINE
|-
|&a7||LIST
|-
|&a8||LOAD
|-
|&a9||LOCATE
|-
|&aa||MEMORY
|-
|&ab||MERGE
|-
|&ac||MID$
|-
|&ad||MODE
|-
|&ae||MOVE
|-
|&af||MOVER
|-
|&b0||NEXT
|-
|&b1||NEW
|-
|&b2||ON
|-
|&b3||ON BREAK
|-
|&b4||ON ERROR GOTO, ON ERROR GO TO
|-
|&b5||SQ
|-
|&b6||OPENIN
|-
|&b7||OPENOUT
|-
|&b8||ORIGIN
|-
|&b9||OUT
|-
|&ba||PAPER
|-
|&bb||PEN
|-
|&bc||PLOT
|-
|&bd||PLOTR
|-
|&be||POKE
|-
|&bf||PRINT
|-
|&c0||"'" symbol (same function as REM keyword)
|-
|&c1||RAD
|-
|&c2||RANDOMIZE
|-
|&c3||READ
|-
|&c4||RELEASE
|-
|&c5||REM
|-
|&c6||RENUM
|-
|&c7||RESTORE
|-
|&c8||RESUME
|-
|&c9||RETURN
|-
|&ca||RUN
|-
|&cb||SAVE
|-
|&cc||SOUND
|-
|&cd||SPEED
|-
|&ce||STOP
|-
|&cf||SYMBOL
|-
|&d0||TAG
|-
|&d1||TAGOFF
|-
|&d2||TROFF
|-
|&d3||TRON
|-
|&d4||WAIT
|-
|&d5||WEND
|-
|&d6||WHILE
|-
|&d7||WIDTH
|-
|&d8||WINDOW
|-
|&d9||WRITE
|-
|&da||ZONE
|-
|&db||DI
|-
|&dc||EI
|-
|&dd||FILL (v1.1)
|-
|&de||GRAPHICS (v1.1)
|-
|&df||MASK (v1.1)
|-
|&e0||FRAME (v1.1)
|-
|&e1||CURSOR (v1.1)
|-
|&e2||(note 2)
|-
|&e3||ERL
|-
|&e4||FN
|-
|&e5||SPC
|-
|&e6||STEP
|-
|&e7||SWAP
|-
|&e8||(note 2)
|-
|&e9||(note 2)
|-
|&ea||TAB
|-
|&eb||THEN
|-
|&ec||TO
|-
|&ed||USING
|-
|&ee||> (greater than)
|-
|&ef||= (equal)
|-
|&f0||>=, > =, => (greater or equal)
|-
|&f1||< (less than)
|-
|&f2||<>, < > (not equal)
|-
|&f3||=<, <=, < = (less than or equal)
|-
|&f4||+ (addition)
|-
|&f5||- (subtraction or unary minus)
|-
|&f6||* (multiplication)
|-
|&f7||/ (division)
|-
|&f8||^ (x to the power of y)
|-
|&f9||\ (integer division)
|-
|&fa||AND
|-
|&fb||MOD
|-
|&fc||OR
|-
|&fd||XOR
|-
|&fe||NOT
|-
|&ff||(prefix for additional keywords)
|-
|}

''Notes:''

* The &ff code is used as a prefix for more keywords. See the table below for the list of keywords using this prefix.
* &e2,&e8 and &e9 are not used
* &7c ("|") is a character prefix used to identify a RSX command.

e.g. "|DIR".

An RSX is encoded in a BASIC program using the following structure:

Offset Count Description
0 1 "|" character prefix
1 1 8-bit byte offset to tokens following RSX name.
2 x RSX name. (Last character of name has bit 7 set to "1", all other characters have bit 7 set to "0")
* This token identifies a integer (16-bit) number. The two bytes following this token is the number, stored low byte then high byte. e.g. &19,&2d,&00 represents the integer number "&002d"="45".
* This token (&0B) is changed at run-time to &0D
* This token identifies a integer variable. 02,00,00,var name offset to number in program setup when program RUN. The variable name is stored directly, with bit 7 of the last character set.
* This token identifies a string variable. offset to string in program string stored AS IS with quotes around it.
* This token identifies a floating point number. Immediatly following the token are 5 bytes which define the number.

Offset Count Description
0 1 &1f (note 1)
1 5 Floating point number (note 2)
1. This byte is the BASIC token identifying a floating point number
2. These 5 bytes define the floating point number.
* The space symbol is used as a command seperator
* Variable definitions:
o The variable definition has the following structure:
Offset Count Description
0 1 Token defining variable type
2 2 16-bit Byte offset to variable value within tokenised BASIC program.
4 x Variable name

The 16-bit byte offset is initially set to 0, but is setup when the program is RUN. The offset is stored in little-endian format, with low byte followed by high byte.
o The token byte defines the variable type (i.e. string, floating point, integer) and the suffix ("$", none and "%").
o The variable name is stored in the program, with bit 7 of the last character set to "1". e.g. The variable named "abc" will be encoded as 'a','b','c'+&80
* String values:
o Each string value is prefixed with &22 token.
o All strings must be enclosed by double quote symbols ("). This symbols define the start and end of the string value.
o The string value can contain any symbol except the quote ("). i.e. 0-&21, and &23-&ff can be used.
* After running a program, Tokens of "1d" with 16-bit BASIC program line pointers are changed to token "1e" with the 16-bit memory address of the BASIC line number in memory.

This table list the BASIC tokens with a &ff prefix byte.

Code
(hexidecimal) BASIC keyword
&00 ABS
&01 ASC
&02 ATN
&03 CHR$
&04 CINT
&05 COS
&06 CREAL
&07 EXP
&08 FIX
&09 FRE
&0a INKEY
&0b INP
&0c INT
&0d JOY
&0e LEN
&0f LOG
&10 LOG10
&11 LOWER$
&12 PEEK
&13 REMAIN
&14 SGN
&15 SIN
&16 SPACE$
&17 SQ
&18 SQR
&19 STR$
&1a TAN
&1b UNT
&1c UPPER$
&1d VAL
(note 2)
&40 EOF
&41 ERR
&42 HIMEM
&43 INKEY$
&44 PI
&45 RND
&46 TIME
&47 XPOS
&48 YPOS
&49 DERR (v1.1)
(note 3)
&71 BIN$
&72 DEC$ (v1.1)
&73 HEX$
&74 INSTR
&75 LEFT$
&76 MAX
&77 MIN
&78 POS
&79 RIGHT$
&7a ROUND
&7b STRING$
&7c TEST
&7d TESTR
&7e COPYCHR$ (v1.1)
&7f VPOS
(note 4)

NOTES:

* These codes are prefixed by &FF. e.g. The keyword "ABS" is stored as the following sequence:

&FF,&00

* Codes &1e...&3f inclusive are not used
* Codes &4a...&6f inclusive are not used
* Codes &80...&ff inclusive are not used

== Floating Point data definition ==

A floating point number represents a number with both an integer and fractional part.

In Amstrad BASIC, a floating point number is stored in base-2 in a normalized form:

1 x 2<exponent>

The representation uses 5 bytes and is stored using the following structure:

Byte 0 1 2 3 4
Bit 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0
Function mantissa (bits 23-16) mantissa (bits 15-8) mantissa (bits 7-0) sign mantissa (bits 30-24) exponent

=== Sign ===

The sign is represented by bit 7 of byte 3.

The value of the sign bit indicates the sign of the floating point number.

* If the sign bit is "1", then the number is negative.
* If the sign bit is "0", then the number is positive.

=== Mantissa ===

The mantissa holds the normalized number. The exponent is manipulated so that the most significant bit is always 1. Since it is always 1, it is not stored. It's value is implied by the representation.

=== Exponent ===

The exponent is 8-bit and is stored in byte 4.

It is stored with a bias of 128.

* 128-255 are positive exponents,
* 0-127 are negative exponents.

To obtain the signed exponent, you must subtract 128 from the stored exponent.

The minimum exponent is 0 and this describes a number of 2^-127.

The maximum exponent is 255 and this describes a number of 2^128.

== BASIC floating-point/real variables ==

A floating point (real) variable describes a number with integer and fractional parts.

* A integer variable is defined with a "!" character postfix.

e.g.

a! = 3.141592654

* A real number uses 5 bytes of memory as storage. The format is described above.
* The address of a real variable can be found in BASIC by:

PRINT @a!

Where "a" should be replaced with the name of the variable.

== BASIC integer variables ==

A integer variable describes a whole number. i.e. a number without any fractional part.

NOTES:

* A integer variable is defined with a "%" character postfix.

e.g.

a% = 3

* A integer variable has a range of -32768 to 32767
* A integer variable always uses two bytes of memory as storage with the following format:

Offset Length Description
0 2 Integer number

* The address of the integer variable can be found in BASIC by:

PRINT @a%

where "a" should be replaced with the name of the variable.

== BASIC string variables ==

A string is a variable which contains a group of characters.

NOTES:

* A string variable is defined in BASIC with a "$" character postfix.

e.g.

a$ = "hello"

* A string variable is described internally by a "string descriptor block" which has the following structure:

Offset Length Description
0 1 Length of string in bytes/characters
1 2 Location of start of string

* The address of the "string descriptor block" for the string variable can be found in BASIC by typing:

PRINT @a$

replacing "a$" with the name of the string variable.

* A string uses a minimum of 3 bytes of storage (a 0 character length string) and a maximum of 258 bytes of storage. 3 bytes are used by the "string descriptor block")
* A string variable can contain any ASCII character code in the range 0-255.
* A string variable can store a minimum of 0 characters and a maximum of 255 characters.
* The length of the string in characters is defined in the string descriptor block. The string does not have a termination character.

Cassette data information

2007-03-13T23:05:18Z

80.167.220.254:

== Recording a sound ==

A sound is recorded by making a measurement of the amplitude of the sound at regular intervals which are defined by the "sample rate". The act of taking the measurement is often called "sampling" and each measurement unit is called a "sample". A file which contains samples is often called a "sound sample" or "audio sample".

The "sample rate" defines the rate/frequency at which the measurements are taken. The higher the sample rate, the faster the measurements are taken, and the lower the sample rate, the slower the measurements are taken. The sample rate is described by the "Hz" unit of measurement. The "Hz" unit of measurement means "per second". Therefore, a sample rate of 44010Hz means 44010 measurements are taken each second (this is one measurement every 1/44010 th of a second).

If the "sample rate" is too low, then changes in the sound which occur between each measurement will not be measured. Therefore the faster the measurements are taken, the more accurate the recording will be, and therefore the higher the quality of sound that can be recorded.

It is worth noting that at high sample rates, because there are many more measurements taken, the resulting size of the file (containing the audio data) can be large.

A "sample" which uses 8-bits for storage can represent 256 distinct amplitude levels and a sample which uses 16-bits for storage can describe 65535 distinct amplitude levels. The higher the number of bits used by each sample for storage, the larger the range of distinct amplitude levels that can be represented. Therefore, the higher the number of bits used by each sample for storage, the higher the quality of sound that can be recorded.

All modern sound cards should support 8-bit and 16-bit samples and sample rates of 22050Hz and 44100Hz.

Some sound cards will support a greater range of recording rates which can be lower and higher than these values.

For samp2cdt you should save the file as "PCM" ("Pulse Code Modulation"). This is a uncompressed, unencoded storage representation. Each sample is a single measurement of the amplitude of the sound taken at a measurement point in time.

Other representations such as "ADPCM" ("Amplitude Delta Pulse Code Modulation"), encode or compress the data to reduce the size of the audio file. Samp2cdt can't understand these representations, so please use "PCM" only.

[[Image:wave1.gif]]

''Fig 1. An amplitude/time graph showing the waveform of the original sound''

[[Image:wave2.gif]]

''Fig 2. An amplitude/time graph showing the waveform of the original sound. The crosses indicate the amplitude measured at each sample time and the dotted lines indicate the the time of each measurement. The duration of time between each dotted line, defined by the sample rate, is equal to the duration of a sample. From this it can be seen that each sample has a finite and equal duration.''

[[Image:wave3.gif]]

''Fig 3. An amplitude/time graph showing the waveform of the original sound. As in Fig 2, the crosses indicate the amplitude measured at each sample time. The dotted line shows the waveform generated by sampling. The final value of each sample is defined to be the amplitude measured at the time of measurement.''

[[Image:wave4.gif]]

''Fig 4. An amplitude/time graph showing the sampled waveform. This waveform was generated at a high sample rate, and therefore the resulting waveform has a shape which is similar to the original. This waveform is the type you can see in a audio recording program like Goldwave.''

[[Image:wave5.gif]]

''Fig 5. An amplitude/time graph showing the waveform of the original sound. As in Fig 2, this graph shows the amplitude of each measurement, and the dotted line indicates the time of measurement. This graph was created using a low sample rate. Notice that the time between each measurement is longer compared to Fig 2.''

[[Image:wave6.gif]]

''Fig 6. An amplitude/time graph showing the waveform of the original sound. As in Fig 3, the crosses indicate the amplitude measured at each sample time, and the dotted line shows the waveform generated by sampling. This graph shows the resulting waveform generated using a low sample rate.''

[[Image:wave7.gif]]

''Fig 7. An amplitude/time graph showing the sampled waveform. This waveform was generated at a low sample rate, and therefore the resulting waveform is much more coarse compared to Fig 4. Notice that although the general shape is similar to the original waveform, and much of the smoothness is is lost between the time of each measurement. The loss of smoothness also means loss of information since this waveform is not the same as the original. If you compare this graph against Fig 4 then you will see that the lower the sample rate, the more information is lost. The higher the sample rate, the less information is lost. Therefore, to record a sound, it is best to use a high sample rate''

Notes:

1. The "Nyquist theory" states that in order to accuratly record a sound of a known frequency, you must use a recording frequency which is twice that frequency.

i.e. to record a sound of 3000Hz, you must record using 6000Hz.

If you use a lower frequency (e.g. 5000Hz), then the sound is not recorded accuratly.

Most Amstrad loaders are between 300 to 2500Hz, therefore you should use a recording sample rate of at least 5000Hz. It is recommended to use one of the "common" sample rates. e.g. 22050Hz (22Khz) or 44100Hz (44.1Khz)

2. There are two different representations to store the amplitude of the sample in a PCM audio file: unsigned or signed.

* A 8-bit unsigned sample has values between 0 and 255. In this range, 0 represents a low amplitudes, 255 a high amplitude, and the amplitudes increase linearly from 0 to 255.

* A 8-bit signed sample has values between -128 and 127. In this range, -128 represents a low amplitude, and 127 high amplitude, and the amplitudes increase linearly from -128 to 127.

Both methods can represent the same data, so there is no advantage to using either. The original reason for the two methods is due to the original method to playback the sound. Modern sound cards can play both methods of data storage.

== Duplication of cassettes ==

When the writing of a program is completed a "master" cassette is created. This cassette contains a audio representation of the computer data.

The master cassette is then duplicated, using a machine, onto many blank cassettes. These cassettes are packaged with instructions and distributed.

It is also easy to make a copy of a cassette if you have a twin cassette system, where one cassette unit will play the sound and the other will record. A first generation copy taken from a original cassette could be considered a copy of a copy of the master cassette.

Each time a cassette is copied however, additional noise may be introduced into the copied version. This noise is a mixture of noise from the original, and noise created by the machine making the copy. Therefore the sound on any cassette contains a mixture of noise and the sound of the computer data.

A loader on the computer must therefore be able to identify the actual sound of the data from other sounds that are on the cassette. If it can't do this, then there will be loading errors.

If you are transfering a cassette using samp2cdt, then you are advised to use an original (i.e. a cassette created directly from a master cassette), or a first generation copy (i.e. a cassette copied from an original).

== Loader ==

A "loader" is the name given to a program that reads data from cassette into the computer memory.

There is a "system" loader which is built into the Amstrad CPC ROM. This loader is activated when the computer is in cassette mode (note 1), and it can only understand one specific computer audio sound, the audio sound of the Amstrad CPC system data-blocks.

To read other loading systems (e.g. a fast-loader), there must be a program on the cassette (a "pre-loader" or "boot loader" or sometimes refered to as "loader"), stored using the Amstrad CPC system loader, which when executed will be able to understand and load fast-loader data.

This loader program is usually stored immediatly before any fast-loader blocks, and takes over from the system loader to load the remaining fast-loader blocks.

|program for fast-loader| |fast-loader block(s)|

So when a cassette is loaded the following occurs:

1. system loader recognises and loads "program for fast-loader".
2. "program for fast loader" takes control and loads the data from the fast-loader block(s) into computer memory
3. when loading has completed, the program is executed.

Notes:

1. a CPC without a disc interface (e.g. a CPC464, CPC464+ or KC Compact) will start-up in cassette mode. For a CPC with a disc interface attached (or internal), you must type |TAPE to enter cassette mode.

You can test if the computer is operating in cassette mode by typing RUN". If you see "Press PLAY then any key", then the computer is operating in cassette mode. If there is an error, then the computer is not operating in cassette mode.

== Amstrad cassette hardware ==

=== Reading ===

The audio from the cassette is read from a cassette player through the Amstrad's cassette electronics.

The Amstrad's cassette electronics converts the amplitude of the sound (a analogue signal) into a "0" or "1" measurement (a digital signal). This measurement can then be read from bit 7 of port B of the PPI 8255 IC.

[[Image:conv.gif]]

''Fig 8. This image shows the conversion of the audio waveform from the cassette into the digital representation by the Amstrad's cassette electronics. i.e. audio waveform (on cassette) -> Amstrad's cassette electronics -> 0 and 1 measurements''

The resulting measurements can be read using the following Z80 instructions:

<pre>
ld b,&f5 ;; I/O port address for PPI 8255 port B
;; (PPI 8255 port B is operating as input.)
in a,(c) ;; read port B inputs
and %10000000 ;; isolate bit 7 which contains the measurement.
</pre>

This measurement is *not* the actual state of a data-bit, but represents a low ("0") or high amplitude ("1"). In this document, the value of this measurement will be refered to as a "high" ("1") or "low" ("0") level.

Notes:

1. The CPC464 and CPC464+ have a cassette player built in. To connect a cassette player to the CPC664, CPC6128 or KC Compact then you must use a lead.
2. It is not known exactly how the amplitude of the sound from the cassette corresponds to the final "0" or "1" measurement.

samp2cdt uses a crude method to perform this conversion.

For a 8-bit signed sample:

* if the amplitude is 0..128, then the final measurement will be "1".
* if the amplitude is -128..0 then the final measurement will be "0".

=== Writing ===

A waveform is written to cassette using bit 5 of port C of the 8255 PPI IC. The waveform can only be defined by a high or low level, defined by the state of bit 5, which is then converted by the Amstrad's cassette electronics into a final output amplitude which is recorded onto cassette.

A high level can be written using the following Z80 instructions:

<pre>
ld b,&f6 ;; I/O port address for PPI 8255 port C
;; (PPI 8255 port C is operating as output.)

set 5,a ;; set cassette write output to high level
out (c),a ;; output level
</pre>

A low level can be written using the following Z80 instructions:

<pre>
ld b,&f6 ;; I/O port address for PPI 8255 port C
;; (PPI 8255 port C is operating as output.)

res 5,a ;; set cassette write output to low level
out (c),a ;; output level
</pre>

The amplitude of the output waveform is not amplified, therefore if you wish to record the cassette audio direct from an Amstrad you will need to amplify the waveform.

If the state of bit 5 is changed at a fixed frequency, then the graph of the state of bit 5 over time will be a square wave. However, the resulting audio written on the cassette will not be a perfect square wave because nature will attempt to convert the waveform into a sine wave.
Loading system audio waveform

Every loading system on the Amstrad uses a serial bit-stream. i.e. a single bit of information is read at a time.

This serial bit-stream is grouped into blocks of audio sound.

Every loading system uses a basic structure to describe each audio block in the following order:

|pilot|sync|data|trailer|

'''pilot'''

This is also refered to as "leader" by some documents.

This is constructed from a repeated waveform often with a fixed number of repetitions defined by the loading system.

The shape of the waveform is known by the loader program and this is used to identify the pilot waveform from other waveforms that may be present (e.g. noise).

The pilot is often long, so that the loader doesn't need to see the start of the pilot waveform in order to load the block.

The loader program will test the incoming waveform, checking it against the parameters defined for the pilot, before the waveform is accepted as the pilot waveform. (e.g. the number of repetitions must be some defined minimum value). The incoming waveform must fall within these specifications otherwise the waveform is not accepted as a pilot waveform.

'''sync ("synchronisation")'''

The sync is a waveform which is different to the pilot, and this defines the end of the pilot and the start of the data. When this sync has been detected, the loader knows that there is data following, and that the loader is always at the same point in the data stream. i.e. the loader program is synchronised to a specific point in the data waveform.

'''data'''

This is the actual data which is composed of waveforms defining "0" and "1" data bits.

The first element of the data may be a marker or id which may, for example, indicate the type of data in the block or the number of the block.

The remaining bits will define the data and zero or more checksums.

The whole data may consist of a single block with a single location and length (e.g. one block for a screen another for data), or multiple blocks each with their own location and length. (e.g. one block for screen and data)

The location and lengths of the blocks may be in the data stream itself, or they may be in a preceeding block, or may be hard-coded into the loader program.

'''trailer'''

The trailer always follows the data. Some loaders may not have a trailer. The two main purposes of the trailer are to ensure that the waveform of the last data bit in the data is constructed correctly and to provide some time in which the loader can prepare for the next block.

The exact definition of the loading systems's audio waveform is defined by the loader program.

samp2cdt has a number of decoder algorithms which recognises the audio waveform of various loading systems. These decoders read the waveform using a similar method to the loader program itself. These decoders have been created by examining the instructions of each loader program and the graph of the waveform in a sound recording package.

== Example of a typical loading system ==

The data on cassette actually consists of changing 0 and 1 levels. (a "level" is a magnitude of a value). The loader measures the time between each "level transition" where a "level transition" is the change from a "0" to a "1" level or the change from a "1" to a "0" level. The level can be timed using the following Z80 instructions:

<pre>
;; - keep testing the state of bit 7 of PPI 8255 port B
;; - update the counter to record the number of tests done
;; - when bit 7 of PPI 8255 port B changes state, stop testing.
;; counter will hold the total number of tests made.
;;
;; B = &F5 (I/O address of PPI 8255 input port B)
;; C = previous data read from PPI port B ld d,0
;; initialise count to 0 .loop inc d
;; increment count in a,(c)
;; read input to PPI 8255 port B xor c
;; exclusive-or with previous data read from PPI 8255 port B and %10000000
;; isolate bit 7
;; if result is 0, then the state of bit 7 that has
;; been read is the same as the previous state. i.e. bit 7 has not changed state.
;; if result is not 0, then the state of bit 7 has changed.
;; e.g. if bit 7 was previously 1, it is now 0. if bit 7 was previously 0, it is now 1. jr z,loop
;; when execution reaches here we know that bit 7 has changed state and D
;; contains the number of tests.
</pre>

== Loader operation==

The loader generally operates in this way:

1. Time a wave. Is the duration of the wave within the minimum and maximum duration required for the pilot. If yes, go to 2, else go to 1.

2. We might have seen a wave from the pilot signal. time a wave. Is the duration of this wave within the minimum and maximum duration required for the pilot. If yes, increment number of waves seen, go to 2, else go to 1.

3. Have we seen the minimum number of pilot waves? Yes, go to 4, else go to 2. 4. time a wave. Is the duration of the wave within the minimum and maximum duration required for the sync? 2. Each Z80 instruction takes a finite time to execute. The execution time depends on the computer. If the timing of the Z80 instructions used by the test algorithm is known and predictable, then the time for each test can be calculated. Now, since the count represents the number of tests made before the condition is true (i.e. bit 7 changes state), the total time for the condition to be true, is the sum of the time for each test made. If each test always takes the same time, then the total time is the number of tests multiplied by the time for one test. In the Amstrad computer, all Z80 instructions execute in multiples of 1us (microsecond) regardless of their location in RAM. This fact simplifies this calculation.
Checksum

A "Checksum" is used to verify the loaded data.

A Checksum is the result of the "checksum calculation" made on a block of data. The actual calculation can be different depending on the method chosen.

There are two "Checksum"s.

1. a stored "Checksum".

This is the result of the "checksum calculation" calculated from the correct data. This is then stored with the data (e.g. before or after the data) when the master cassette is created.
2. a calculated "Checksum".

This is the result of the "checksum calculation" calculated from the data read from the cassette. After the calculation is complete it is compared against the stored checksum.

The stored and calculated "Checksums" are initialised with the same initial value and calculated using the same algorithm. Therefore, if the stored checksum matches the calculated checksum, it is assumed that the loaded data is identical to the original data. The data is verified to be correct.

If the stored checksum doesn't match the calculated checksum, then there has been a error. One or more bit's of data is incorrect. The checksum is designed to detect errors only, and often it is not possible to know which bit or bits of data is incorrect and in this case it is not often possible to correct the errors to reproduce the correct data.

A loader which has a checksum therefore is better than a loader that doesn't have a checksum, because the checksum will verify that the data is correct or incorrect.

With a loader which doesn't have a checksum, you have no way to verify the data, and therefore you can't guarantee that the data is identical to the original.

In this case, the only way to test that the data is correct is to make multiple transfers of the program and test each thoroughly (e.g. if the program is a game, you would play the game to the end), checking for graphic corruption and bugs. If all of the transfers operate the same, then you can assume that the data is correct.

== Various Audio file formats ==

There are numerous Audio file formats, each of which can store audio, but each has it's own structures and representation for the data.

The "format" of a file describes the internal structure, order and encoding of the data within the file.

Here is a list of the audio file formats supported by samp2cdt:

* Windows Wave file (a file which has the ".wav" file extension) is the common file format used for audio sounds on computers running "Windows".
* A Voice Wave file (a file which has the ".voc" file extension) was created by Creative for the original Soundblaster ISA sound card. This file format is used by the original voc2tzx utility which samp2cdt was developed from.
* A Audio Interchange file (a file which has the ".aiff" or ".aif" file extension) is the common file format used for audio sounds on the Mac computer.
* A file which has the ".iff" file extension is the common file format used for audio sounds by the Amiga computer.

Cassette data information

2007-03-13T21:42:30Z

80.167.220.254:

== Recording a sound ==

A sound is recorded by making a measurement of the amplitude of the sound at regular intervals which are defined by the "sample rate". The act of taking the measurement is often called "sampling" and each measurement unit is called a "sample". A file which contains samples is often called a "sound sample" or "audio sample".

The "sample rate" defines the rate/frequency at which the measurements are taken. The higher the sample rate, the faster the measurements are taken, and the lower the sample rate, the slower the measurements are taken. The sample rate is described by the "Hz" unit of measurement. The "Hz" unit of measurement means "per second". Therefore, a sample rate of 44010Hz means 44010 measurements are taken each second (this is one measurement every 1/44010 th of a second).

If the "sample rate" is too low, then changes in the sound which occur between each measurement will not be measured. Therefore the faster the measurements are taken, the more accurate the recording will be, and therefore the higher the quality of sound that can be recorded.

It is worth noting that at high sample rates, because there are many more measurements taken, the resulting size of the file (containing the audio data) can be large.

A "sample" which uses 8-bits for storage can represent 256 distinct amplitude levels and a sample which uses 16-bits for storage can describe 65535 distinct amplitude levels. The higher the number of bits used by each sample for storage, the larger the range of distinct amplitude levels that can be represented. Therefore, the higher the number of bits used by each sample for storage, the higher the quality of sound that can be recorded.

All modern sound cards should support 8-bit and 16-bit samples and sample rates of 22050Hz and 44100Hz.

Some sound cards will support a greater range of recording rates which can be lower and higher than these values.

For samp2cdt you should save the file as "PCM" ("Pulse Code Modulation"). This is a uncompressed, unencoded storage representation. Each sample is a single measurement of the amplitude of the sound taken at a measurement point in time.

Other representations such as "ADPCM" ("Amplitude Delta Pulse Code Modulation"), encode or compress the data to reduce the size of the audio file. Samp2cdt can't understand these representations, so please use "PCM" only.

[[Image:wave1.gif]]

''Fig 1. An amplitude/time graph showing the waveform of the original sound''

[[Image:wave2.gif]]

''Fig 2. An amplitude/time graph showing the waveform of the original sound. The crosses indicate the amplitude measured at each sample time and the dotted lines indicate the the time of each measurement. The duration of time between each dotted line, defined by the sample rate, is equal to the duration of a sample. From this it can be seen that each sample has a finite and equal duration.''

[[Image:wave3.gif]]

''Fig 3. An amplitude/time graph showing the waveform of the original sound. As in Fig 2, the crosses indicate the amplitude measured at each sample time. The dotted line shows the waveform generated by sampling. The final value of each sample is defined to be the amplitude measured at the time of measurement.''

[[Image:wave4.gif]]

''Fig 4. An amplitude/time graph showing the sampled waveform. This waveform was generated at a high sample rate, and therefore the resulting waveform has a shape which is similar to the original. This waveform is the type you can see in a audio recording program like Goldwave.''

[[Image:wave5.gif]]

''Fig 5. An amplitude/time graph showing the waveform of the original sound. As in Fig 2, this graph shows the amplitude of each measurement, and the dotted line indicates the time of measurement. This graph was created using a low sample rate. Notice that the time between each measurement is longer compared to Fig 2.''

[[Image:wave6.gif]]

''Fig 6. An amplitude/time graph showing the waveform of the original sound. As in Fig 3, the crosses indicate the amplitude measured at each sample time, and the dotted line shows the waveform generated by sampling. This graph shows the resulting waveform generated using a low sample rate.''

[[Image:wave7.gif]]

''Fig 7. An amplitude/time graph showing the sampled waveform. This waveform was generated at a low sample rate, and therefore the resulting waveform is much more coarse compared to Fig 4. Notice that although the general shape is similar to the original waveform, and much of the smoothness is is lost between the time of each measurement. The loss of smoothness also means loss of information since this waveform is not the same as the original. If you compare this graph against Fig 4 then you will see that the lower the sample rate, the more information is lost. The higher the sample rate, the less information is lost. Therefore, to record a sound, it is best to use a high sample rate''

Notes:

1. The "Nyquist theory" states that in order to accuratly record a sound of a known frequency, you must use a recording frequency which is twice that frequency.

i.e. to record a sound of 3000Hz, you must record using 6000Hz.

If you use a lower frequency (e.g. 5000Hz), then the sound is not recorded accuratly.

Most Amstrad loaders are between 300 to 2500Hz, therefore you should use a recording sample rate of at least 5000Hz. It is recommended to use one of the "common" sample rates. e.g. 22050Hz (22Khz) or 44100Hz (44.1Khz)

2. There are two different representations to store the amplitude of the sample in a PCM audio file: unsigned or signed.

* A 8-bit unsigned sample has values between 0 and 255. In this range, 0 represents a low amplitudes, 255 a high amplitude, and the amplitudes increase linearly from 0 to 255.

* A 8-bit signed sample has values between -128 and 127. In this range, -128 represents a low amplitude, and 127 high amplitude, and the amplitudes increase linearly from -128 to 127.

Both methods can represent the same data, so there is no advantage to using either. The original reason for the two methods is due to the original method to playback the sound. Modern sound cards can play both methods of data storage.

== Duplication of cassettes ==

When the writing of a program is completed a "master" cassette is created. This cassette contains a audio representation of the computer data.

The master cassette is then duplicated, using a machine, onto many blank cassettes. These cassettes are packaged with instructions and distributed.

It is also easy to make a copy of a cassette if you have a twin cassette system, where one cassette unit will play the sound and the other will record. A first generation copy taken from a original cassette could be considered a copy of a copy of the master cassette.

Each time a cassette is copied however, additional noise may be introduced into the copied version. This noise is a mixture of noise from the original, and noise created by the machine making the copy. Therefore the sound on any cassette contains a mixture of noise and the sound of the computer data.

A loader on the computer must therefore be able to identify the actual sound of the data from other sounds that are on the cassette. If it can't do this, then there will be loading errors.

If you are transfering a cassette using samp2cdt, then you are advised to use an original (i.e. a cassette created directly from a master cassette), or a first generation copy (i.e. a cassette copied from an original).

== Loader ==

A "loader" is the name given to a program that reads data from cassette into the computer memory.

There is a "system" loader which is built into the Amstrad CPC ROM. This loader is activated when the computer is in cassette mode (note 1), and it can only understand one specific computer audio sound, the audio sound of the Amstrad CPC system data-blocks.

To read other loading systems (e.g. a fast-loader), there must be a program on the cassette (a "pre-loader" or "boot loader" or sometimes refered to as "loader"), stored using the Amstrad CPC system loader, which when executed will be able to understand and load fast-loader data.

This loader program is usually stored immediatly before any fast-loader blocks, and takes over from the system loader to load the remaining fast-loader blocks.

|program for fast-loader| |fast-loader block(s)|

So when a cassette is loaded the following occurs:

1. system loader recognises and loads "program for fast-loader".
2. "program for fast loader" takes control and loads the data from the fast-loader block(s) into computer memory
3. when loading has completed, the program is executed.

Notes:

1. a CPC without a disc interface (e.g. a CPC464, CPC464+ or KC Compact) will start-up in cassette mode. For a CPC with a disc interface attached (or internal), you must type |TAPE to enter cassette mode.

You can test if the computer is operating in cassette mode by typing RUN". If you see "Press PLAY then any key", then the computer is operating in cassette mode. If there is an error, then the computer is not operating in cassette mode.

== Amstrad cassette hardware ==

=== Reading ===

The audio from the cassette is read from a cassette player through the Amstrad's cassette electronics.

The Amstrad's cassette electronics converts the amplitude of the sound (a analogue signal) into a "0" or "1" measurement (a digital signal). This measurement can then be read from bit 7 of port B of the PPI 8255 IC.

[Picture showing the conversion process]

[Fig 8. This image shows the conversion of the audio waveform from the cassette into the digital representation by the Amstrad's cassette electronics. i.e. audio waveform (on cassette) -> Amstrad's cassette electronics -> 0 and 1 measurements]

The resulting measurements can be read using the following Z80 instructions:

<pre>
ld b,&f5 ;; I/O port address for PPI 8255 port B
;; (PPI 8255 port B is operating as input.)
in a,(c) ;; read port B inputs
and %10000000 ;; isolate bit 7 which contains the measurement.
</pre>

This measurement is *not* the actual state of a data-bit, but represents a low ("0") or high amplitude ("1"). In this document, the value of this measurement will be refered to as a "high" ("1") or "low" ("0") level.

Notes:

1. The CPC464 and CPC464+ have a cassette player built in. To connect a cassette player to the CPC664, CPC6128 or KC Compact then you must use a lead.
2. It is not known exactly how the amplitude of the sound from the cassette corresponds to the final "0" or "1" measurement.

samp2cdt uses a crude method to perform this conversion.

For a 8-bit signed sample:

* if the amplitude is 0..128, then the final measurement will be "1".
* if the amplitude is -128..0 then the final measurement will be "0".

=== Writing ===

A waveform is written to cassette using bit 5 of port C of the 8255 PPI IC. The waveform can only be defined by a high or low level, defined by the state of bit 5, which is then converted by the Amstrad's cassette electronics into a final output amplitude which is recorded onto cassette.

A high level can be written using the following Z80 instructions:

<pre>
ld b,&f6 ;; I/O port address for PPI 8255 port C
;; (PPI 8255 port C is operating as output.)

set 5,a ;; set cassette write output to high level
out (c),a ;; output level
</pre>

A low level can be written using the following Z80 instructions:

<pre>
ld b,&f6 ;; I/O port address for PPI 8255 port C
;; (PPI 8255 port C is operating as output.)

res 5,a ;; set cassette write output to low level
out (c),a ;; output level
</pre>

The amplitude of the output waveform is not amplified, therefore if you wish to record the cassette audio direct from an Amstrad you will need to amplify the waveform.

If the state of bit 5 is changed at a fixed frequency, then the graph of the state of bit 5 over time will be a square wave. However, the resulting audio written on the cassette will not be a perfect square wave because nature will attempt to convert the waveform into a sine wave.
Loading system audio waveform

Every loading system on the Amstrad uses a serial bit-stream. i.e. a single bit of information is read at a time.

This serial bit-stream is grouped into blocks of audio sound.

Every loading system uses a basic structure to describe each audio block in the following order:

|pilot|sync|data|trailer|

'''pilot'''

This is also refered to as "leader" by some documents.

This is constructed from a repeated waveform often with a fixed number of repetitions defined by the loading system.

The shape of the waveform is known by the loader program and this is used to identify the pilot waveform from other waveforms that may be present (e.g. noise).

The pilot is often long, so that the loader doesn't need to see the start of the pilot waveform in order to load the block.

The loader program will test the incoming waveform, checking it against the parameters defined for the pilot, before the waveform is accepted as the pilot waveform. (e.g. the number of repetitions must be some defined minimum value). The incoming waveform must fall within these specifications otherwise the waveform is not accepted as a pilot waveform.

'''sync ("synchronisation")'''

The sync is a waveform which is different to the pilot, and this defines the end of the pilot and the start of the data. When this sync has been detected, the loader knows that there is data following, and that the loader is always at the same point in the data stream. i.e. the loader program is synchronised to a specific point in the data waveform.

'''data'''

This is the actual data which is composed of waveforms defining "0" and "1" data bits.

The first element of the data may be a marker or id which may, for example, indicate the type of data in the block or the number of the block.

The remaining bits will define the data and zero or more checksums.

The whole data may consist of a single block with a single location and length (e.g. one block for a screen another for data), or multiple blocks each with their own location and length. (e.g. one block for screen and data)

The location and lengths of the blocks may be in the data stream itself, or they may be in a preceeding block, or may be hard-coded into the loader program.

'''trailer'''

The trailer always follows the data. Some loaders may not have a trailer. The two main purposes of the trailer are to ensure that the waveform of the last data bit in the data is constructed correctly and to provide some time in which the loader can prepare for the next block.

The exact definition of the loading systems's audio waveform is defined by the loader program.

samp2cdt has a number of decoder algorithms which recognises the audio waveform of various loading systems. These decoders read the waveform using a similar method to the loader program itself. These decoders have been created by examining the instructions of each loader program and the graph of the waveform in a sound recording package.

== Example of a typical loading system ==

The data on cassette actually consists of changing 0 and 1 levels. (a "level" is a magnitude of a value). The loader measures the time between each "level transition" where a "level transition" is the change from a "0" to a "1" level or the change from a "1" to a "0" level. The level can be timed using the following Z80 instructions: ;; - keep testing the state of bit 7 of PPI 8255 port B ;; - update the counter to record the number of tests done ;; - when bit 7 of PPI 8255 port B changes state, stop testing. ;; counter will hold the total number of tests made. ;; ;; B = &F5 (I/O address of PPI 8255 input port B) ;; C = previous data read from PPI port B ld d,0 ;; initialise count to 0 .loop inc d ;; increment count in a,(c) ;; read input to PPI 8255 port B xor c ;; exclusive-or with previous data read from PPI 8255 port B and %10000000 ;; isolate bit 7 ;; if result is 0, then the state of bit 7 that has ;; been read is the same as the previous state. i.e. bit 7 has not changed state. ;; if result is not 0, then the state of bit 7 has changed. ;; e.g. if bit 7 was previously 1, it is now 0. if bit 7 was previously 0, it is now 1. jr z,loop ;; when execution reaches here we know that bit 7 has changed state and D ;; contains the number of tests.

== Loader operation==

The loader generally operates in this way:

1. time a wave. Is the duration of the wave within the minimum and maximum duration required for the pilot. If yes, go to 2, else go to 1.

2. We might have seen a wave from the pilot signal. time a wave. Is the duration of this wave within the minimum and maximum duration required for the pilot. If yes, increment number of waves seen, go to 2, else go to 1.

3. Have we seen the minimum number of pilot waves? Yes, go to 4, else go to 2. 4. time a wave. Is the duration of the wave within the minimum and maximum duration required for the sync? 2. Each Z80 instruction takes a finite time to execute. The execution time depends on the computer. If the timing of the Z80 instructions used by the test algorithm is known and predictable, then the time for each test can be calculated. Now, since the count represents the number of tests made before the condition is true (i.e. bit 7 changes state), the total time for the condition to be true, is the sum of the time for each test made. If each test always takes the same time, then the total time is the number of tests multiplied by the time for one test. In the Amstrad computer, all Z80 instructions execute in multiples of 1us (microsecond) regardless of their location in RAM. This fact simplifies this calculation.
Checksum

A "Checksum" is used to verify the loaded data.

A Checksum is the result of the "checksum calculation" made on a block of data. The actual calculation can be different depending on the method chosen.

There are two "Checksum"s.

1. a stored "Checksum".

This is the result of the "checksum calculation" calculated from the correct data. This is then stored with the data (e.g. before or after the data) when the master cassette is created.
2. a calculated "Checksum".

This is the result of the "checksum calculation" calculated from the data read from the cassette. After the calculation is complete it is compared against the stored checksum.

The stored and calculated "Checksums" are initialised with the same initial value and calculated using the same algorithm. Therefore, if the stored checksum matches the calculated checksum, it is assumed that the loaded data is identical to the original data. The data is verified to be correct.

If the stored checksum doesn't match the calculated checksum, then there has been a error. One or more bit's of data is incorrect. The checksum is designed to detect errors only, and often it is not possible to know which bit or bits of data is incorrect and in this case it is not often possible to correct the errors to reproduce the correct data.

A loader which has a checksum therefore is better than a loader that doesn't have a checksum, because the checksum will verify that the data is correct or incorrect.

With a loader which doesn't have a checksum, you have no way to verify the data, and therefore you can't guarantee that the data is identical to the original.

In this case, the only way to test that the data is correct is to make multiple transfers of the program and test each thoroughly (e.g. if the program is a game, you would play the game to the end), checking for graphic corruption and bugs. If all of the transfers operate the same, then you can assume that the data is correct.
Various Audio file formats

There are numerous Audio file formats, each of which can store audio, but each has it's own structures and representation for the data.

The "format" of a file describes the internal structure, order and encoding of the data within the file.

Here is a list of the audio file formats supported by samp2cdt:

* Windows Wave file (a file which has the ".wav" file extension) is the common file format used for audio sounds on computers running "Windows".
* A Voice Wave file (a file which has the ".voc" file extension) was created by Creative for the original Soundblaster ISA sound card. This file format is used by the original voc2tzx utility which samp2cdt was developed from.
* A Audio Interchange file (a file which has the ".aiff" or ".aif" file extension) is the common file format used for audio sounds on the Mac computer.
* A file which has the ".iff" file extension is the common file format used for audio sounds by the Amiga computer.

Cassette data information

2007-03-13T21:32:42Z

80.167.220.254:

== Recording a sound ==

A sound is recorded by making a measurement of the amplitude of the sound at regular intervals which are defined by the "sample rate". The act of taking the measurement is often called "sampling" and each measurement unit is called a "sample". A file which contains samples is often called a "sound sample" or "audio sample".

The "sample rate" defines the rate/frequency at which the measurements are taken. The higher the sample rate, the faster the measurements are taken, and the lower the sample rate, the slower the measurements are taken. The sample rate is described by the "Hz" unit of measurement. The "Hz" unit of measurement means "per second". Therefore, a sample rate of 44010Hz means 44010 measurements are taken each second (this is one measurement every 1/44010 th of a second).

If the "sample rate" is too low, then changes in the sound which occur between each measurement will not be measured. Therefore the faster the measurements are taken, the more accurate the recording will be, and therefore the higher the quality of sound that can be recorded.

It is worth noting that at high sample rates, because there are many more measurements taken, the resulting size of the file (containing the audio data) can be large.

A "sample" which uses 8-bits for storage can represent 256 distinct amplitude levels and a sample which uses 16-bits for storage can describe 65535 distinct amplitude levels. The higher the number of bits used by each sample for storage, the larger the range of distinct amplitude levels that can be represented. Therefore, the higher the number of bits used by each sample for storage, the higher the quality of sound that can be recorded.

All modern sound cards should support 8-bit and 16-bit samples and sample rates of 22050Hz and 44100Hz.

Some sound cards will support a greater range of recording rates which can be lower and higher than these values.

For samp2cdt you should save the file as "PCM" ("Pulse Code Modulation"). This is a uncompressed, unencoded storage representation. Each sample is a single measurement of the amplitude of the sound taken at a measurement point in time.

Other representations such as "ADPCM" ("Amplitude Delta Pulse Code Modulation"), encode or compress the data to reduce the size of the audio file. Samp2cdt can't understand these representations, so please use "PCM" only.

[[Image:wave1.gif]]

'''Fig 1. An amplitude/time graph showing the waveform of the original sound'''

[[Image:wave2.gif]]

'''Fig 2. An amplitude/time graph showing the waveform of the original sound. The crosses indicate the amplitude measured at each sample time and the dotted lines indicate the the time of each measurement. The duration of time between each dotted line, defined by the sample rate, is equal to the duration of a sample. From this it can be seen that each sample has a finite and equal duration.''

[[Image:wave3.gif]]

'''Fig 3. An amplitude/time graph showing the waveform of the original sound. As in Fig 2, the crosses indicate the amplitude measured at each sample time. The dotted line shows the waveform generated by sampling. The final value of each sample is defined to be the amplitude measured at the time of measurement.'''

[[Image:wave4.gif]]

'''Fig 4. An amplitude/time graph showing the sampled waveform. This waveform was generated at a high sample rate, and therefore the resulting waveform has a shape which is similar to the original. This waveform is the type you can see in a audio recording program like Goldwave.'''

[[Image:wave5.gif]]

'''Fig 5. An amplitude/time graph showing the waveform of the original sound. As in Fig 2, this graph shows the amplitude of each measurement, and the dotted line indicates the time of measurement. This graph was created using a low sample rate. Notice that the time between each measurement is longer compared to Fig 2.'''

[[Image:wave6.gif]]

'''Fig 6. An amplitude/time graph showing the waveform of the original sound. As in Fig 3, the crosses indicate the amplitude measured at each sample time, and the dotted line shows the waveform generated by sampling. This graph shows the resulting waveform generated using a low sample rate.'''

[[Image:wave7.gif]]

'''Fig 7. An amplitude/time graph showing the sampled waveform. This waveform was generated at a low sample rate, and therefore the resulting waveform is much more coarse compared to Fig 4. Notice that although the general shape is similar to the original waveform, and much of the smoothness is is lost between the time of each measurement. The loss of smoothness also means loss of information since this waveform is not the same as the original. If you compare this graph against Fig 4 then you will see that the lower the sample rate, the more information is lost. The higher the sample rate, the less information is lost. Therefore, to record a sound, it is best to use a high sample rate'''

Notes:

1. The "Nyquist theory" states that in order to accuratly record a sound of a known frequency, you must use a recording frequency which is twice that frequency.

i.e. to record a sound of 3000Hz, you must record using 6000Hz.

If you use a lower frequency (e.g. 5000Hz), then the sound is not recorded accuratly.

Most Amstrad loaders are between 300 to 2500Hz, therefore you should use a recording sample rate of at least 5000Hz. It is recommended to use one of the "common" sample rates. e.g. 22050Hz (22Khz) or 44100Hz (44.1Khz)

2. There are two different representations to store the amplitude of the sample in a PCM audio file: unsigned or signed.

* A 8-bit unsigned sample has values between 0 and 255. In this range, 0 represents a low amplitudes, 255 a high amplitude, and the amplitudes increase linearly from 0 to 255.

* A 8-bit signed sample has values between -128 and 127. In this range, -128 represents a low amplitude, and 127 high amplitude, and the amplitudes increase linearly from -128 to 127.

Both methods can represent the same data, so there is no advantage to using either. The original reason for the two methods is due to the original method to playback the sound. Modern sound cards can play both methods of data storage.

== Duplication of cassettes ==

When the writing of a program is completed a "master" cassette is created. This cassette contains a audio representation of the computer data.

The master cassette is then duplicated, using a machine, onto many blank cassettes. These cassettes are packaged with instructions and distributed.

It is also easy to make a copy of a cassette if you have a twin cassette system, where one cassette unit will play the sound and the other will record. A first generation copy taken from a original cassette could be considered a copy of a copy of the master cassette.

Each time a cassette is copied however, additional noise may be introduced into the copied version. This noise is a mixture of noise from the original, and noise created by the machine making the copy. Therefore the sound on any cassette contains a mixture of noise and the sound of the computer data.

A loader on the computer must therefore be able to identify the actual sound of the data from other sounds that are on the cassette. If it can't do this, then there will be loading errors.

If you are transfering a cassette using samp2cdt, then you are advised to use an original (i.e. a cassette created directly from a master cassette), or a first generation copy (i.e. a cassette copied from an original).

== Loader ==

A "loader" is the name given to a program that reads data from cassette into the computer memory.

There is a "system" loader which is built into the Amstrad CPC ROM. This loader is activated when the computer is in cassette mode (note 1), and it can only understand one specific computer audio sound, the audio sound of the Amstrad CPC system data-blocks.

To read other loading systems (e.g. a fast-loader), there must be a program on the cassette (a "pre-loader" or "boot loader" or sometimes refered to as "loader"), stored using the Amstrad CPC system loader, which when executed will be able to understand and load fast-loader data.

This loader program is usually stored immediatly before any fast-loader blocks, and takes over from the system loader to load the remaining fast-loader blocks.

|program for fast-loader| |fast-loader block(s)|

So when a cassette is loaded the following occurs:

# system loader recognises and loads "program for fast-loader".
# "program for fast loader" takes control and loads the data from the fast-loader block(s) into computer memory
# when loading has completed, the program is executed.

Notes:

# a CPC without a disc interface (e.g. a CPC464, CPC464+ or KC Compact) will start-up in cassette mode. For a CPC with a disc interface attached (or internal), you must type |TAPE to enter cassette mode.

You can test if the computer is operating in cassette mode by typing RUN". If you see "Press PLAY then any key", then the computer is operating in cassette mode. If there is an error, then the computer is not operating in cassette mode.

== Amstrad cassette hardware ==

=== Reading ===

The audio from the cassette is read from a cassette player through the Amstrad's cassette electronics.

The Amstrad's cassette electronics converts the amplitude of the sound (a analogue signal) into a "0" or "1" measurement (a digital signal). This measurement can then be read from bit 7 of port B of the PPI 8255 IC.

[Picture showing the conversion process]

[Fig 8. This image shows the conversion of the audio waveform from the cassette into the digital representation by the Amstrad's cassette electronics. i.e. audio waveform (on cassette) -> Amstrad's cassette electronics -> 0 and 1 measurements]

The resulting measurements can be read using the following Z80 instructions:

<pre>
ld b,&f5 ;; I/O port address for PPI 8255 port B
;; (PPI 8255 port B is operating as input.)
in a,(c) ;; read port B inputs
and %10000000 ;; isolate bit 7 which contains the measurement.
</pre>

This measurement is *not* the actual state of a data-bit, but represents a low ("0") or high amplitude ("1"). In this document, the value of this measurement will be refered to as a "high" ("1") or "low" ("0") level.

Notes:

1. The CPC464 and CPC464+ have a cassette player built in. To connect a cassette player to the CPC664, CPC6128 or KC Compact then you must use a lead.
2. It is not known exactly how the amplitude of the sound from the cassette corresponds to the final "0" or "1" measurement.

samp2cdt uses a crude method to perform this conversion.

For a 8-bit signed sample:
* if the amplitude is 0..128, then the final measurement will be "1".
* if the amplitude is -128..0 then the final measurement will be "0".

=== Writing ===

A waveform is written to cassette using bit 5 of port C of the 8255 PPI IC. The waveform can only be defined by a high or low level, defined by the state of bit 5, which is then converted by the Amstrad's cassette electronics into a final output amplitude which is recorded onto cassette.

A high level can be written using the following Z80 instructions:

ld b,&f6 ;; I/O port address for PPI 8255 port C
;; (PPI 8255 port C is operating as output.)

set 5,a ;; set cassette write output to high level
out (c),a ;; output level

A low level can be written using the following Z80 instructions:

ld b,&f6 ;; I/O port address for PPI 8255 port C
;; (PPI 8255 port C is operating as output.)

res 5,a ;; set cassette write output to low level
out (c),a ;; output level

The amplitude of the output waveform is not amplified, therefore if you wish to record the cassette audio direct from an Amstrad you will need to amplify the waveform.

If the state of bit 5 is changed at a fixed frequency, then the graph of the state of bit 5 over time will be a square wave. However, the resulting audio written on the cassette will not be a perfect square wave because nature will attempt to convert the waveform into a sine wave.
Loading system audio waveform

Every loading system on the Amstrad uses a serial bit-stream. i.e. a single bit of information is read at a time.

This serial bit-stream is grouped into blocks of audio sound.

Every loading system uses a basic structure to describe each audio block in the following order:

|pilot|sync|data|trailer|

pilot
This is also refered to as "leader" by some documents.

This is constructed from a repeated waveform often with a fixed number of repetitions defined by the loading system.

The shape of the waveform is known by the loader program and this is used to identify the pilot waveform from other waveforms that may be present (e.g. noise).

The pilot is often long, so that the loader doesn't need to see the start of the pilot waveform in order to load the block.

The loader program will test the incoming waveform, checking it against the parameters defined for the pilot, before the waveform is accepted as the pilot waveform. (e.g. the number of repetitions must be some defined minimum value). The incoming waveform must fall within these specifications otherwise the waveform is not accepted as a pilot waveform.
sync ("synchronisation")
The sync is a waveform which is different to the pilot, and this defines the end of the pilot and the start of the data. When this sync has been detected, the loader knows that there is data following, and that the loader is always at the same point in the data stream. i.e. the loader program is synchronised to a specific point in the data waveform.
data
This is the actual data which is composed of waveforms defining "0" and "1" data bits.

The first element of the data may be a marker or id which may, for example, indicate the type of data in the block or the number of the block.

The remaining bits will define the data and zero or more checksums.

The whole data may consist of a single block with a single location and length (e.g. one block for a screen another for data), or multiple blocks each with their own location and length. (e.g. one block for screen and data)

The location and lengths of the blocks may be in the data stream itself, or they may be in a preceeding block, or may be hard-coded into the loader program.
trailer
The trailer always follows the data. Some loaders may not have a trailer. The two main purposes of the trailer are to ensure that the waveform of the last data bit in the data is constructed correctly and to provide some time in which the loader can prepare for the next block.

The exact definition of the loading systems's audio waveform is defined by the loader program.

samp2cdt has a number of decoder algorithms which recognises the audio waveform of various loading systems. These decoders read the waveform using a similar method to the loader program itself. These decoders have been created by examining the instructions of each loader program and the graph of the waveform in a sound recording package.
Example of a typical loading system
The data on cassette actually consists of changing 0 and 1 levels. (a "level" is a magnitude of a value). The loader measures the time between each "level transition" where a "level transition" is the change from a "0" to a "1" level or the change from a "1" to a "0" level. The level can be timed using the following Z80 instructions: ;; - keep testing the state of bit 7 of PPI 8255 port B ;; - update the counter to record the number of tests done ;; - when bit 7 of PPI 8255 port B changes state, stop testing. ;; counter will hold the total number of tests made. ;; ;; B = &F5 (I/O address of PPI 8255 input port B) ;; C = previous data read from PPI port B ld d,0 ;; initialise count to 0 .loop inc d ;; increment count in a,(c) ;; read input to PPI 8255 port B xor c ;; exclusive-or with previous data read from PPI 8255 port B and %10000000 ;; isolate bit 7 ;; if result is 0, then the state of bit 7 that has ;; been read is the same as the previous state. i.e. bit 7 has not changed state. ;; if result is not 0, then the state of bit 7 has changed. ;; e.g. if bit 7 was previously 1, it is now 0. if bit 7 was previously 0, it is now 1. jr z,loop ;; when execution reaches here we know that bit 7 has changed state and D ;; contains the number of tests.
Loader operation
The loader generally operates in this way: 1. time a wave. Is the duration of the wave within the minimum and maximum duration required for the pilot. If yes, go to 2, else go to 1. 2. We might have seen a wave from the pilot signal. time a wave. Is the duration of this wave within the minimum and maximum duration required for the pilot. If yes, increment number of waves seen, go to 2, else go to 1. 3. Have we seen the minimum number of pilot waves? Yes, go to 4, else go to 2. 4. time a wave. Is the duration of the wave within the minimum and maximum duration required for the sync? 2. Each Z80 instruction takes a finite time to execute. The execution time depends on the computer. If the timing of the Z80 instructions used by the test algorithm is known and predictable, then the time for each test can be calculated. Now, since the count represents the number of tests made before the condition is true (i.e. bit 7 changes state), the total time for the condition to be true, is the sum of the time for each test made. If each test always takes the same time, then the total time is the number of tests multiplied by the time for one test. In the Amstrad computer, all Z80 instructions execute in multiples of 1us (microsecond) regardless of their location in RAM. This fact simplifies this calculation.
Checksum

A "Checksum" is used to verify the loaded data.

A Checksum is the result of the "checksum calculation" made on a block of data. The actual calculation can be different depending on the method chosen.

There are two "Checksum"s.

1. a stored "Checksum".

This is the result of the "checksum calculation" calculated from the correct data. This is then stored with the data (e.g. before or after the data) when the master cassette is created.
2. a calculated "Checksum".

This is the result of the "checksum calculation" calculated from the data read from the cassette. After the calculation is complete it is compared against the stored checksum.

The stored and calculated "Checksums" are initialised with the same initial value and calculated using the same algorithm. Therefore, if the stored checksum matches the calculated checksum, it is assumed that the loaded data is identical to the original data. The data is verified to be correct.

If the stored checksum doesn't match the calculated checksum, then there has been a error. One or more bit's of data is incorrect. The checksum is designed to detect errors only, and often it is not possible to know which bit or bits of data is incorrect and in this case it is not often possible to correct the errors to reproduce the correct data.

A loader which has a checksum therefore is better than a loader that doesn't have a checksum, because the checksum will verify that the data is correct or incorrect.

With a loader which doesn't have a checksum, you have no way to verify the data, and therefore you can't guarantee that the data is identical to the original.

In this case, the only way to test that the data is correct is to make multiple transfers of the program and test each thoroughly (e.g. if the program is a game, you would play the game to the end), checking for graphic corruption and bugs. If all of the transfers operate the same, then you can assume that the data is correct.
Various Audio file formats

There are numerous Audio file formats, each of which can store audio, but each has it's own structures and representation for the data.

The "format" of a file describes the internal structure, order and encoding of the data within the file.

Here is a list of the audio file formats supported by samp2cdt:

* Windows Wave file (a file which has the ".wav" file extension) is the common file format used for audio sounds on computers running "Windows".
* A Voice Wave file (a file which has the ".voc" file extension) was created by Creative for the original Soundblaster ISA sound card. This file format is used by the original voc2tzx utility which samp2cdt was developed from.
* A Audio Interchange file (a file which has the ".aiff" or ".aif" file extension) is the common file format used for audio sounds on the Mac computer.
* A file which has the ".iff" file extension is the common file format used for audio sounds by the Amiga computer.

Programming:CPC Plus Screen Splitting

2007-03-12T14:35:05Z

80.167.220.254:

<pre>
;; This example shows how to split the screen using the CPC+
;; If you want to do the same effect on the CPC, then you will
;; need to use the "rupture"/"vertical splitting" technique.
;;
;; This example is designed for CPC+ only and will
;; not work on CPC or KC Compact.
;;
;;;; This example will compile with the MAXAM assembler
;; or the built-in assembler of WinAPE32.

;; NOTE - For this example to work, the code must not
;; be in the range &4000-&7fff inclusive. The ASIC registers
;; are paged into this range, and the code would not be
;; visible to the CPU if it was also in this range.
org &8000

;;--------------------------------------------------
;; STEP 1 - Unlock CPC+ additional features
;; unlock asic to gain access to asic registers

di
ld b,&bc
ld hl,sequence
ld e,17
.seq
ld a,(hl)
out (c),a
inc hl
dec e
jr nz,seq
ei

;;---------------------------------------------------
;; STEP 2 - Set display start address for display before split

;; this address corresponds to a start of &c000
ld hl,&3000

;; set display start address (high)
ld bc,&bc0c
out (c),c
inc b
out (c),h

;; set display start address (low)
ld bc,&bc0d
out (c),c
inc b
out (c),l

;;---------------------------------------------------
;; STEP 3 - Set display start address for display after split
;;
;; - The split is refreshed by the ASIC, so as soon as it has been initialised
;; it will remain active until it is disabled (by writing 0 as the scan-line for the split)
;; No extra CPU time is required to maintain the split.
;;
;; - The split address is defined the same as the CRTC display start address
;;
;; - The split address is in the same order as the CRTC display start address
;; (high byte followed by low byte)

;; page-in asic registers to &4000-&7fff
ld bc,&7fb8
out (c),c

;; set scan-line that split will activate on
ld a,100
ld (&6801),a

;; set screen address of split:
;; this address corresponds to start of &4000
ld hl,&1000

ld a,h
ld (&6802),a
ld a,l
ld (&6803),a

;; page-out asic registers
ld bc,&7fa0
out (c),c

;;----------------------------------------------------

ret

;;----------------------------------------------------------
;; this is the sequence to unlock the ASIC extra features
.sequence
defb &ff,&00,&ff,&77,&b3,&51,&a8,&d4,&62,&39,&9c,&46,&2b,&15,&8a,&cd,&ee
</pre>

Programming:CPC Plus Hardware Sprites

2007-03-12T14:33:56Z

80.167.220.254:

<pre>
;; This example shows a CPC+ hardware sprite.
;;
;; This example is designed for CPC+ only and will
;; not work on CPC or KC Compact.
;;
;;
;; This example will compile with the MAXAM assembler
;; or the built-in assembler of WinAPE32.

;; NOTE - For this example to work, the code must not
;; be in the range &4000-&7fff inclusive. The ASIC registers
;; are paged into this range, and the code would not be
;; visible to the CPU if it was also in this range.
org &8000

;;--------------------------------------------------
;; STEP 1 - Unlock CPC+ additional features
;; unlock asic to gain access to asic registers

di
ld b,&bc
ld hl,sequence
ld e,17
.seq
ld a,(hl)
out (c),a
inc hl
dec e
jr nz,seq
ei

;;--------------------------------------------------
;; STEP 2 - Setup sprite pixel data
;;
;; The ASIC has internal "RAM" used to store the sprite pixel
;; data. If you want to change the pixel data for a sprite
;; then you need to copy new data into the internal "RAM".

;; page-in asic registers to &4000-&7fff
ld bc,&7fb8
out (c),c

;; stored sprite pixel data
ld hl,sprite_pixel_data

;; address of sprite 0 pixel data
;; sprite 0 pixel data is in the range &4000-&4100
ld de,&4000

;; length of pixel data for a single sprite (16x16 = 256)
ld bc,&100
ldir

;; page-out asic registers
ld bc,&7fa0
out (c),c

;;--------------------------------------------------
;; STEP 3 - Setup sprite palette
;;
;; The sprites use a single 15 entry sprite palette.
;; pen 0 is ALWAYS transparent.
;;
;; The sprite palette is different to the screen palette.

;; page-in asic registers to &4000-&7fff
ld bc,&7fb8
out (c),c

;; copy colours into ASIC sprite palette registers
ld hl,sprite_colours
ld de,&6422
ld bc,15*2
ldir

;; page-out asic registers
ld bc,&7fa0
out (c),c

;;--------------------------------------------------
;; STEP 4 - Setup sprite properties
;;
;; Each sprite has properties which define the x,y coordinates
;; and x,y magnification.

;; page-in asic registers to &4000-&7fff
ld bc,&7fb8
out (c),c

;; set x coordinate for sprite 0
ld hl,100
ld (&6000),hl

;; set y coordinate for sprite 0
ld hl,100
ld (&6002),hl

;; set sprite x and y magnification
;; x magnification = 1
;; y magnification = 1
ld a,%0101
ld (&6004),a

;; page-out asic registers
ld bc,&7fa0
out (c),c

;;--------------------------------------------------
ret

;;--------------------------------------------------
;; - there is two bytes per colour.
;; - these are stored in a form that can be written direct
;; to the CPC+ colour palette registers (i.e. xGRB)
;; - pen 0 is always transparent and doesn't have a entry
;; in the CPC+ palette

.sprite_colours
defw &0111 ;; colour for sprite pen 1
defw &0222 ;; colour for sprite pen 2
defw &0333 ;; colour for sprite pen 3
defw &0444 ;; colour for sprite pen 4
defw &0555 ;; colour for sprite pen 5
defw &0666 ;; colour for sprite pen 6
defw &0777 ;; colour for sprite pen 7
defw &0888 ;; colour for sprite pen 8
defw &0999 ;; colour for sprite pen 9
defw &0aaa ;; colour for sprite pen 10
defw &0bbb ;; colour for sprite pen 11
defw &0ccc ;; colour for sprite pen 12
defw &0ddd ;; colour for sprite pen 13
defw &0eee ;; colour for sprite pen 14
defw &0fff ;; colour for sprite pen 15

;;---------------------------------------------
;; - there is one pixel per byte (bits 3..0 of each byte define the palette index for this pixel)
;; - these bytes are stored in a form that can be written direct to the ASIC
;; sprite pixel data
.sprite_pixel_data
defb &00,&00,&00,&00,&00,&00,&00,&00,&00,&00,&00,&00,&00,&00,&00,&00 ;; line 0
defb &00,&00,&00,&00,&00,&00,&00,&00,&00,&00,&00,&00,&00,&00,&00,&00 ;; line 1
defb &00,&00,&00,&00,&00,&00,&00,&00,&00,&00,&00,&00,&00,&00,&00,&00 ;; line 2
defb &00,&00,&00,&00,&00,&00,&00,&00,&00,&00,&00,&00,&00,&00,&00,&00 ;; line 3
defb &00,&00,&00,&00,&00,&00,&00,&00,&00,&00,&00,&00,&00,&00,&00,&00 ;; line 4
defb &00,&00,&00,&00,&00,&00,&00,&00,&00,&00,&00,&00,&00,&00,&00,&00 ;; line 5
defb &00,&00,&00,&00,&00,&00,&00,&00,&00,&00,&00,&00,&00,&00,&00,&00 ;; line 6
defb &00,&00,&00,&00,&00,&00,&00,&00,&00,&00,&00,&00,&00,&00,&00,&00 ;; line 7
defb &00,&00,&00,&00,&00,&00,&00,&00,&00,&00,&00,&00,&00,&00,&00,&00 ;; line 8
defb &00,&00,&00,&00,&00,&00,&00,&00,&00,&00,&00,&00,&00,&00,&00,&00 ;; line 9
defb &00,&00,&00,&00,&00,&00,&00,&00,&00,&00,&00,&00,&00,&00,&00,&00 ;; line 10
defb &00,&00,&00,&00,&00,&00,&00,&00,&00,&00,&00,&00,&00,&00,&00,&00 ;; line 11
defb &00,&00,&00,&00,&00,&00,&00,&00,&00,&00,&00,&00,&00,&00,&00,&00 ;; line 12
defb &00,&00,&00,&00,&00,&00,&00,&00,&00,&00,&00,&00,&00,&00,&00,&00 ;; line 13
defb &00,&00,&00,&00,&00,&00,&00,&00,&00,&00,&00,&00,&00,&00,&00,&00 ;; line 14
defb &00,&00,&00,&00,&00,&00,&00,&00,&00,&00,&00,&00,&00,&00,&00,&00 ;; line 15

;;----------------------------------------------------------
;; this is the sequence to unlock the ASIC extra features
.sequence
defb &ff,&00,&ff,&77,&b3,&51,&a8,&d4,&62,&39,&9c,&46,&2b,&15,&8a,&cd,&ee
</pre>

Programming:CPC Plus Vertical scroll

2007-03-12T13:37:34Z

80.167.220.254:

<pre>
;; This example shows how to scroll the screen vertically using the
;; CPC+ "soft" hardware scroll. This scroll is smooth because it will scroll
;; a scanline at a time.
;;
;; This example will only work on the CPC+.
;;
;; The scroll is made by changing the start of the screen using the CRTC,
;; (which will scroll the screen vertically by the number of scanlines defined by register 9),
;; and a scan-line adjustment defined using the CPC+ "soft" hardware scroll register.

;; The location of this code is important. It must not be located
;; between &4000-&7fff.
org &8000
nolist

;;----------------------------------------------------------------------
;; unlock asic to gain access to asic registers
di
ld b,&bc
ld hl,sequence
ld e,17
.seq
ld a,(hl)
out (c),a
inc hl
dec e
jr nz,seq
ei

;;----------------------------------------------------------------------
;; install a interrupt handler
;;
;; We install our own interrupt handler for this reason:
;; - To stop the firmware interrupt from being executed, this will
;; ensure that our direct access to the hardware will not be interrupted
;; by the firmware, and that the values we write are not re-written by
;; the firmware.

di ;; disable interrupts
im 1 ;; set interrupt mode 1 (jump to &0038 when interrupt occurs)
ld hl,&c9fb ;; EI:RET
ld (&0038),hl ;; &0038 is executed
ei

;;----------------------------------------------------------------------
;; main loop

.main_loop
;; wait for start of vsync. This test assumes that the start of the vsync
;; has not yet happened.

ld b,&f5
.ml2
in a,(c)
rra
jr nc,ml2

;; The vsync has just started, we can safely setup the scroll
;; without the display being effected.

;;-----------------------------------------------------------------------
;; update vertical scan-line scroll adjustment

;; page in ASIC ram
;; ASIC registers will be paged into memory range &4000-&7fff
ld bc,&7fb8
out (c),c

;; get scan-line scroll adjustment
ld a,(scanline_offset)
;; shift into bits required for writing to hardware
add a,a
add a,a
add a,a
add a,a
;; write to "soft" hardware scroll register of CPC+
ld (&6804),a

;; page out ASIC ram
ld bc,&7fa0
out (c),c

;;-----------------------------------------------------------------------
;; update CRTC with scroll offset

ld hl,(scroll_offset) ;; get scroll offset

ld a,h
or &30 ;; This defines the "base" of the screen in 16k units.
;; &00 -> screen uses &0000-&3fff
;; &10 -> screen uses &4000-&7fff
;; &20 -> screen uses &8000-&bfff
;; &30 -> screen uses &c000-&ffff
ld h,a

ld bc,&bc0c ;; select CRTC register 12
out (c),c

inc b ;; B = &BD
out (c),h ;; write to CRTC register 12

dec b
inc c ;; BC = &BC0D
out (c),c ;; select CRTC register 13

inc b
out (c),l ;; write to CRTC register 13

;;----------------------------------------------------------------------

;; we need to wait long enough for the VSYNC signal to finish, so that the
;; test at the beginning of this loop will synchronise with the *start* of the
;; vsync.

;; this first HALT will catch the interrupt that occurs two scanlines from
;; the start of the VSYNC, the second will delay a furthur 52 scanlines. The maximum
;; duration for the VSYNC is 16 scanlines.
halt

halt

;; update the scroll ready for the next update of the display
call scroll_up

;; loop
jp main_loop

;;----------------------------------------------------------------------
;; adjust scroll parameters to scroll the screen up
;;
;; Each CRTC character is 8 scanlines tall, therefore the CRTC scroll offset
;; will scroll the screen up by 8 scanlines at a time.
;;
;; We use the CPC+ "soft" hardware scroll to set the scanline offset within
;; each CRTC character.
;;
;; The CPC+ "soft" hardware scroll is updated for every scanlines.
;; The CRTC scroll offset is only updated once for every 8 scanlines.

.scroll_up

;; get scanline offset
ld a,(scanline_offset)
inc a
;; ensure it is in range
and &7
;; store scanline offset
ld (scanline_offset),a
cp 0
ret nz

;; by now we have scrolled through 8 scanlines using the CPC+ "soft" hardware
;; scroll, now we need to update the screen start address

;; get the crtc scroll offset
ld hl,(scroll_offset)

ld bc,40 ;; this is the same as the value written to CRTC register 1
;; and defines the width of the display in CRTC characters.
add hl,bc

ld a,h ;; ensure the scroll offset is in the range &300-&3ff
and &3
ld h,a

;; store the crtc scroll offset
ld (scroll_offset),hl
ret

;;----------------------------------------------------------------------
;; scroll offset of the screen to be written to CRTC register 12 and 13
;; This value is defined in "CRTC" characters.
.scroll_offset
defw 0

;;----------------------------------------------------------------------
;; holds a number between 0 and 7 which is the scanline adjustment
;; for the scroll
.scanline_offset
defb 0

;;----------------------------------------------------------------------
;; this is the sequence to unlock the ASIC extra features
.sequence
defb &ff,&00,&ff,&77,&b3,&51,&a8,&d4,&62,&39,&9c,&46,&2b,&15,&8a,&cd,&ee
</pre>

Programming:CPC Plus Horizontal scroll

2007-03-12T13:36:28Z

80.167.220.254:

<pre>
;; This example shows how to scroll the screen horizonatally using the
;; CPC+ "soft" hardware scroll. This scroll is smooth because it will scroll
;; a pixel at a time.
;;
;; This example will only work on the CPC+.
;;
;; The scroll is made by changing the start of the screen using the CRTC,
;; (which will scroll the screen vertically by the number of scanlines defined by register 9),
;; and a scan-line adjustment defined using the CPC+ "soft" hardware scroll register.

;; The location of this code is important. It must not be located
;; between &4000-&7fff.
org &8000
nolist

;;----------------------------------------------------------------------
;; unlock asic to gain access to asic registers
di
ld b,&bc
ld hl,sequence
ld e,17
.seq
ld a,(hl)
out (c),a
inc hl
dec e
jr nz,seq
ei

;;----------------------------------------------------------------------
;; install a interrupt handler
;;
;; We install our own interrupt handler for this reason:
;; - To stop the firmware interrupt from being executed, this will
;; ensure that our direct access to the hardware will not be interrupted
;; by the firmware, and that the values we write are not re-written by
;; the firmware.

di ;; disable interrupts
im 1 ;; set interrupt mode 1 (jump to &0038 when interrupt occurs)
ld hl,&c9fb ;; EI:RET
ld (&0038),hl ;; &0038 is executed
ei

;;----------------------------------------------------------------------
;; main loop

.main_loop
;; wait for start of vsync. This test assumes that the start of the vsync
;; has not yet happened.

ld b,&f5
.ml2
in a,(c)
rra
jr nc,ml2

;; The vsync has just started, we can safely setup the scroll
;; without the display being effected.

;;-----------------------------------------------------------------------
;; update vertical scan-line scroll adjustment

;; page in ASIC ram
;; ASIC registers will be paged into memory range &4000-&7fff
ld bc,&7fb8
out (c),c

;; get scan-line scroll adjustment
ld a,(horz_pixel_offset)
;; bits 3..0 define the horizontal pixel scroll offset
;; bits 6..4 define the vertical scanline scroll offset

;; write to "soft" hardware scroll register of CPC+
ld (&6804),a

;; page out ASIC ram
ld bc,&7fa0
out (c),c

;;-----------------------------------------------------------------------
;; update CRTC with scroll offset

ld hl,(scroll_offset) ;; get scroll offset

ld a,h
or &30 ;; This defines the "base" of the screen in 16k units.
;; &00 -> screen uses &0000-&3fff
;; &10 -> screen uses &4000-&7fff
;; &20 -> screen uses &8000-&bfff
;; &30 -> screen uses &c000-&ffff
ld h,a

ld bc,&bc0c ;; select CRTC register 12
out (c),c

inc b ;; B = &BD
out (c),h ;; write to CRTC register 12

dec b
inc c ;; BC = &BC0D
out (c),c ;; select CRTC register 13

inc b
out (c),l ;; write to CRTC register 13

;;----------------------------------------------------------------------

;; we need to wait long enough for the VSYNC signal to finish, so that the
;; test at the beginning of this loop will synchronise with the *start* of the
;; vsync.

;; this first HALT will catch the interrupt that occurs two scanlines from
;; the start of the VSYNC, the second will delay a furthur 52 scanlines. The maximum
;; duration for the VSYNC is 16 scanlines.
halt

halt

;; update the scroll ready for the next update of the display
call scroll_right

;; loop
jp main_loop

;;----------------------------------------------------------------------
;; adjust scroll parameters to scroll the screen right
;;
;; Each CRTC character is 2 bytes.
;;
;; In mode 0 there are 2 pixels per byte, there are 4 pixels for each CRTC character.
;; In mode 1 there are 4 pixels per byte, there are 8 pixels for each CRTC character.
;; In mode 2 there are 8 pixels per byte, there are 16 pixels for each CRTC character.
;;
;; The horizontal pixel scroll offset is defined for mode 2 resolution.
;; Pixels in mode 1 are twice the width of mode 2 pixels.
;; Pixels in mode 0 are four times the width of mode 2 pixels.
;;
;; The horizontal pixel scroll offset is updated for every pixel.
;; The CRTC scroll offset is updated for every CRTC character (every 16 pixels in mode 2
;; OR every 8 pixels in mode 1 OR every 4 pixels in mode 0).

.scroll_right
;; get horizontal pixel scroll offset
ld a,(horz_pixel_offset)

sub 1 ;; increments for pixel scrolling:
;; 1 for mode 2
;; 2 for mode 1
;; 4 for mode 0
and &f
ld (horz_pixel_offset),a
cp 0
ret nz

;; by now we have scrolled through:
;; - 16 pixels in mode 2
;; - 8 pixels in mode 1
;; - 4 pixels in mode 0

;; get the crtc scroll offset
ld hl,(scroll_offset)

inc hl ;; update offset

ld a,h ;; ensure the scroll offset is in the range &300-&3ff
and &3
ld h,a

;; store the crtc scroll offset
ld (scroll_offset),hl
ret

;;----------------------------------------------------------------------
;; scroll offset of the screen to be written to CRTC register 12 and 13
;; This value is defined in "CRTC" characters.
.scroll_offset
defw 0

;;----------------------------------------------------------------------
;; holds a number between 0 and 15 which is the pixel offset
;; for the scroll
.horz_pixel_offset
defb 0

;;----------------------------------------------------------------------
;; this is the sequence to unlock the ASIC extra features
.sequence
defb &ff,&00,&ff,&77,&b3,&51,&a8,&d4,&62,&39,&9c,&46,&2b,&15,&8a,&cd,&ee
</pre>