Palette
The DSA  ' &PALETTE ' command can be used to select a palette for use in the viewport.  Specifying a negative palette number restores the default Atarti palette.

The Atari is capable of displaying 512 different colors ( but only 16 at a time! )  The colors are encoded into three 3-bit fields of a 16-bit word for a total of 9 bits or 512 different possibilities.  The encoding is like this:   0000000rrrgggbbb.  The red component uses bits 6-8, the green 3-5, and the blue 0-2.  So each possible color is represented by a number between 0 and 511.  We will call these numbers the 'Atari Color Numbers'.

The &PALETTE command allows you to specifiy what color will appear on the screen for each of these 512 possible 'Atari Color Numbers' and allows you, moreover, to choose from 32,768 different colors.

Here is how it works.......You provide a table of 512 16-bit numbers, one for each Atari color number..  Each number represents a color in 16-bit color notation.  The number consists of three 5-bit fields representing the intensities of the red, green, and blue components of the color.  In binary, like this:   0rrrrrgggggbbbbb.  The red intensitiy uses bits 10-14, the green 5-9, and the blue 0-4.

Let us say that you want the Atari color of GREEN to appear on the viewport as RED.  The Atari color number for GREEN is 0000000000111000 in binary.  The red component is zero and the blue component is zero and the green component is seven.  In decimal, this number is 56.  You have decided hat you want this to appear as RED.  So you provide a 16-bit color of 0111110000000000 in binary.  The red component is 31 (maximum), the green component is zero and the blue component is zero.  In hex this is 0x7C00.  In decimal, this is 31744.  So your palette looks like this:

0 Not yet decided
1Not yet decided
2Not yet decided
...
56  0x7C00
...
510Not yet decided
511Not yet decided

Where only the one color has been determined.  You still need to decide how the other 511 colors should appear.

IMPORTANT notes:   WATCH OUT.

The 16-bit entries in the palette you provide are in 'little-endian' format.  The low byte comes first!!!!  So, for example, if you look at entry 56 of the palette we computed in the example above, you will see the two bytes in reverse order.......0x00 followed by 0x7C.  Or, the two bytes together as 0x007C ( 124 in decimal ).

The palette you provide does not 'replace' the current palette.  It 'blends' with the current palette.  You provide a 'density' parameter.  If you specify a density of zero then the current palette will not be changed. If you provide a density of 100 then the current palette will be completely replaced.  If you provide a density of 50 then the result will be half way between the current palette and the palette you provide.  Using this feature allows you to 'fade' from one palette to another by doing several &PALETTE commands.  Each will change the current palette a little bit more like the palette you provide.  If, for example, you specify a density of 25 then the first application will result in 75 percent original and 25 percent new.  The second application will result in 56 percent original and 44 percent new.  The third will result in 42 percent original and 58 percent new.  Then 31 percent original.  Then 24 percent.  Then 18, 13, 10, 8, 6, etc.  (Mutiplying by 0.75 at each application).

A Program to display the 512 Atari colors
A Demonstration Dungeon