To do the advanced lessons you should have already finished Pong.

This Week: As you complete a full game you may find the NROM memory limits to be too small. To enable more ROM on carts many forms of "bank switching" were used. This article deals with just one type of CHR switching, used on CNROM carts. CNROM is easy to use and very cheap to manufacture. The ReproPak, PowerPak, and PowerPak Lite all support CNROM completely so it is easy to get your code running on real hardware. If you are using donor carts you can look up games that use CNROM at BootGod's NES Cart Database.


CHR Bank Switching
Bank switching is exchanging one chunk of ROM for a different chunk, while keeping everything in same address range. It is not making a copy, so it happens instantly. You can switch between different banks whenever you want. The size and memory range of the banks depends on the mapper. For the CNROM mapper used in this article the bank size is 8KB of CHR ROM. The whole 8KB range of PPU memory $0000-1FFF is switched at once. This means the graphics for all background tiles and sprite tiles will be swapped. In your game you may have some tiles duplicated in multiple banks so they do not appear to change on screen. PRG is not bank switched, so it remains at the NROM limit of 32KB.


Set Mapper Number
The first part of adding bank switching is changing the mapper number your .NES file uses. At the top of your code has previously been:

  .inesmap 0 ; mapper 0 = NROM, no bank swapping

The new line is:

  .inesmap 3 ; mapper 3 = CNROM, 8KB CHR ROM bank swapping

This line in the header just tells the emulator to use CNROM to play your game. A list of other iNES mapper numbers can be seen at the wiki at http://nesdevwiki.org/....


Set CHR Size
The next part is to increase the size of your CHR ROM. Change the .ineschr value from 1 to 2, showing that there are now two 8KB banks. CNROM can handle 32KB of CHR ROM or four 8KB banks but this example will only use two.


Add CHR Data
The third part adds the data for the next bank into your game. Just make a new .bank statement below your current one for CHR, giving it the next sequential number. In your code when you set which bank to switch to this is the number used. PRG bank numbers are ignored so your original CHR bank will be #0 and the new one will be #1.


Bank Switching Code
The final part it to write your bank switching code. This subroutine will take a bank number in the A register and switch the CHR bank to it immediately. The actual switch is done by writing the desired bank number anywhere in the $8000-FFFF memory range. The cart hardware sees this write and changes the CHR bank.

... your game code ...

  LDA #$01 ;;put new bank to use into the A register

  JSR Bankswitch ;;jump to bank switching code

... your game code ...

Bankswitch:

  STA $8000 ;;new bank to use

  RTS

Bus Conflicts
When you start running your code on real hardware there is one catch to worry about. For basic mappers, the PRG ROM does not care if it receives a read or a write command. It will respond to both like a read by putting the data on the data bus. This is a problem for bank switching, where the CPU is also trying to put data on the data bus at the same time. They electrically fit in a "bus conflict". The CPU could win, giving you the right value. Or the ROM could win, giving you the wrong value. This is solved by having the ROM and CPU put the same value on the data bus, so there is no conflict. First a table of bank numbers is made, and the value from that table is written to do the bank switch.

... code ...

  LDA #$01 ;;put new bank to use into A

  JSR Bankswitch ;;jump to bank switching code

... code ...

Bankswitch:

  TAX ;;copy A into X

  STA Bankvalues, X ;;new bank to use

  RTS

Bankvalues:

  .db $00, $01, $02, $03 ;;bank numbers

The X register is used as an index into the Bankvalues table, so the value written by the CPU will match the value coming from the ROM.



Putting It All Together
Download and unzip the chrbanks.zip sample files. This set is based on the previous Week 5 code. Make sure that file, mario0.chr, mario1.chr, and chrbanks.bat is in the same folder as NESASM3, then double click on chrbanks.bat. That will run NESASM3 and should produce chrbanks.nes. Run that NES file in FCEUXD SP to see small Mario.

Inside the LatchController subroutine a new section is added to read the Select and Start buttons from the controller. The Select button switches to CHR bank 0, and the Start button switches to CHR bank 1. Graphics of CHR bank 1 have been rearranged so Mario will change to a beetle.  The tile numbers are not changed, but the graphics for those tiles are.

This Week: The MMC1 is the first advanced mapper made by Nintendo. It is used for many games including top titles like The Legend of Zelda. The main benefits are mirroring control, up to 256KB of PRG ROM, 128KB of CHR RAM or ROM, and 8KB of WRAM. The WRAM can be battery backed for saved games. This tutorial will cover all features of the MMC1 and how to use them. You should be comfortable with the normal Nerdy Nights series before starting.  Another more simple lesson for bankswitching is Advanced Nerdy Nights #1.  If you only need one or two of the banking features then you may want to consider more simple and cheaper mappers instead such as UNROM or CNROM.

Carts using the MMC1 will have the S*ROM board code, like SNROM and SGROM. BootGod's NesCartDB database can be searched for which games use which boards. The ReproPak MMC1 board can also be used to build carts.


Shift Registers
The MMC1 uses a 5 bit shift register to temporarily store the banking bits. Shift registers were covered in Week 7. When writing to the register data comes in from data bit 0 only. This is similar to the controller reading where data outputs to data bit 0. Every time a write happens the current bits are shifted and D0 is inserted. The first bit you write eventually becomes to lowest bank bit. On the 5th write when the shift register is full the 5 bit value gets copied to the banking register. At this point the bank switch happens immediately without any delays. To load a bank register the LSR instruction is used for shifting:

  LDA banknumber
  STA bankreg    ; load bank bit 0 to shift register from data bit 0
  LSR A          ; shift in next data bit to position 0
  STA bankreg    ; load bank bit 1 from data bit 0
  LSR A
  STA bankreg    ; bank bit 2
  LSR A
  STA bankreg    ; bank bit 3
  LSR A
  STA bankreg    ; bank bit 4, bank register loaded, bank switch happens here

Unlike other simple mappers like UNROM and CNROM, there are no bus conflicts. The ROM is not enabled while you are writing so you do not have to make the data you are writing match.

Data bit 7 is also connected to the MMC1. When a write happens to any banking register with D7=1 the shift register is reset back to position 0. It will then take another 5 writes to fully load the next value. All other bits are ignored and D0 is not loaded into the shift register. The PRG bits of the control register are also reset to their default values as shown in the next section. Usually you will only reset the MMC1 at the very beginning of your program:

  LDA #%10000000
  STA $8000

Config Register at $8000-9FFF
To load the config register, do 5 writes to the $8000-9FFF range. The config bits are:

  43210
  -----
  CPRMM
  |||||
  |||++- Mirroring (0: one-screen, lower bank; 1: one-screen, upper bank;
  |||               2: vertical; 3: horizontal)
  ||+--- PRG swap range (0: switch 16 KB bank at $C000; 1: switch 16 KB bank at $8000;
  ||                            only used when PRG bank mode bit below is set to 1)
  |+---- PRG size (0: switch 32 KB at $8000, ignoring low bit of bank number;
  |                         1: switch 16 KB at address specified by location bit above)
  +----- CHR size (0: switch 8 KB at a time; 1: switch two separate 4 KB banks)

Mirroring Config
Your program can change the mirroring at any point using these bits. You do not need to wait for vblank to change them. When using the MMC1 the .inesmir directive bit is ignored. You must set it through your code. Mirroring set to 0 and 1 are single screen mirroring modes. Only 1KB is used for all nametables. When scrolling the screen will wrap both vertically and horizontally. Mirroring set to 2 is the typical vertical mirroring, and 3 is horizontal mirroring.

PRG Bank Size Config
The MMC1 swaps PRG ROM in either 16KB or 32KB chunks. By default this bit is set to 1 for 16KB banks. Clearing it to 0 enables 32KB banks. Notice these are not the same size as the 8KB NESASM banks so the bank numbers will be different. When using 16KB banks the MMC1 banks are twice as big, so you must divide your NESASM bank number by 2 when writing it to the bank register. When using 32KB banks you must divide by 4. 16KB banks is most commonly used, with the bulk of the code in the fixed bank and data/graphics/music in the swappable banks.

PRG Swap Range Config
When using 16KB banks set above, the PRG address range that gets swapped can be configured. If 32KB banks are used this bit is ignored and the entire $8000-FFFF range is swapped at once.

By default this bit is set to 1, making the $8000-BFFF range swappable while the $C000-FFFF range is fixed to the last bank Of PRG. This matches the PRG swapping of the UNROM mapper and is most commonly used. Clearing this bit to 0 changes this so $8000-BFFF is fixed and $C000-FFFF is swappable.

Changing the range or bank size can be useful for swapping audio samples but you have to be careful to put IRQ/reset/NMI vectors in all banks that are loaded into the vector area at $FFFA-FFFF.

CHR Bank Size Config
Like the PRG the CHR bank size can be configured to either 4KB or 8KB banks. With 8KB banks the whole $0000-1FFF range is one bank. With 4KB banks there are two banks at PPU $0000-0FFF and $1000-1FFF. This can be used with background in one bank and sprites in another. Then, for example, all sprites could be swapped and the background could stay.


CHR Bank 0 Register at $A000-BFFF
This is the register for CHR bank 0. To set it do 5 writes to the $A000-BFFF range. When in 4KB CHR mode it selects a bank for PPU $0000-0FFF. The full 5 bit value is used so there are 32 possible banks. Each bank is 4KB making it 128KB CHR maximum. When in 8KB CHR mode this register controls the full PPU $0000-1FFF. The bottom bit is ignored so there are 16 possible banks. Each bank is now 8KB which is still 128KB max.

This Week: Time to learn how to do horizontal background scrolling, like Super Mario Bros. Hopefully it is explained with the most easy to understand code. There is no compression, no buffers, and no metatiles, so only the ideas of scrolling are presented. Once you understand the scrolling part you should look into those other topics to save code/data space and increase performance if needed.



Nametable Review
Before starting the scrolling you must fully understand how nametables work. One nametable is 32x30 background tiles, which covers exactly one visible screen. Including the attribute table, each screen needs 1KB of PPU RAM. The NES PPU has the address space for 4 nametables ($2000, $2400, $2800, $2C00) in a 2x2 grid:

       +-----------+-----------+
       |           |           |
       |           |           |
       |   $2000   |   $2400   |
       |           |           |
       |           |           |
       +-----------+-----------+
       |           |           |
       |           |           |
       |   $2800   |   $2C00   |
       |           |           |
       |           |           |
       +-----------+-----------+

However the NES only has 2KB of PPU RAM inside the console, so there are only two actual nametables. The other two nametables are copies of those actual ones. Your mirroring settings determine the layout of the actual nametables and which ones are copies.

Vertical mirroring means the nametables stacked vertically are the same data. 0 ($2000) is a mirror of 2 ($2800), and 1 ($2400) is a mirror of 3 ($2C00). 0 and 1 are next to each other and have different data. This is what we want for horizontal scrolling. When you are looking at nametable 0 and scroll to the right, nametable 1 will be in view. Typically your mirroring setting is the opposite of the scrolling direction. To set the iNES header:

  .inesmir 1  ;;VERT mirroring for HORIZ scrolling

Scroll registers
Before scrolling we will fill both nametables 0 ($2000) and 1 ($2400). The same data will be copied into both, except the attribute table will be different. By setting the second nametable attributes to another color palette the two screens will have a very visible difference.

FillNametables:
  LDA $2002             ; read PPU status to reset the high/low latch
  LDA #$20
  STA $2006             ; write the high byte of $2000 address (nametable 0)
  LDA #$00
  STA $2006             ; write the low byte of $2000 address
  LDY #$08
  LDX #$00              ; fill 256 x 8 bytes = 2KB, both nametables all full
  LDA #$7F
FillNametablesLoop:
  STA $2007
  DEX
  BNE FillNametablesLoop
  DEY
  BNE FillNametablesLoop

FillAttrib0:
  LDA $2002             ; read PPU status to reset the high/low latch
  LDA #$23
  STA $2006             ; write the high byte of $23C0 address (nametable 0 attributes)
  LDA #$C0
  STA $2006             ; write the low byte of $23C0 address
  LDX #$40              ; fill 64 bytes
  LDA #$00              ; palette group 0
FillAttrib0Loop:
  STA $2007
  DEX
  BNE FillAttrib0Loop

FillAttrib1:
  LDA $2002             ; read PPU status to reset the high/low latch
  LDA #$27
  STA $2006             ; write the high byte of $27C0 address (nametable 1 attributes)
  LDA #$C0
  STA $2006             ; write the low byte of $27C0 address
  LDX #$40              ; fill 64 bytes
  LDA #$FF              ; palette group 3
FillAttrib1Loop:
  STA $2007
  DEX
  BNE FillAttrib1Loop

The scroll registers are at $2005. Like some other PPU registers you need to write to it twice. The first write is the horizontal scroll count, the second write is the vertical scroll count. The scroll sets which pixel of the nametable for the start of the left side of the screen. Previously we have set the scroll to 0 so the left side of the screen is aligned with the left edge of the nametable. The scroll registers are both 8 bit registers, making the scroll range 0 to 255. The screen is 256 pixels wide so the horizontal scroll register covers one full screen wide.

This sample code just increments the horizontal scroll register ($2005) by 1 on every frame. You can see when the first nametable scrolls off the screen, the second one comes on screen. The previously set colors make the split between nametables obvious. As the scroll register wraps from 255 to 0 the first nametable becomes completely visible again. You can also see the sprites are not affected by the scroll registers. They have their own separate x and y position data.

NMI:
  LDA #$00
  STA $2003       
  LDA #$02
  STA $4014       ; sprite DMA from $0200
  
  ; run other game graphics updating code here
  
  LDA #$00
  STA $2006        ; clean up PPU address registers
  STA $2006

  INC scroll       ; add one to our scroll variable each frame
  LDA scroll
  STA $2005        ; write the horizontal scroll count register

  LDA #$00         ; no vertical scrolling
  STA $2005
    
  ;;This is the PPU clean up section, so rendering the next frame starts properly.
  LDA #%10010000   ; enable NMI, sprites from Pattern Table 0, background from Pattern Table 1
  STA $2000
  LDA #%00011110   ; enable sprites, enable background, no clipping on left side
  STA $2001

  ; run normal game engine code here
  ; reading from controllers, etc
  
  RTI              ; return from interrupt

The full code and compiled .NES file is available from the download link at the bottom of this tutorial. scrolling1.asm includes everything up to this point.


Nametable Register
The problem with just the scroll register is that it isn't big enough. In the previous example the scroll wrapped from 255 to 0, so the second nametable is never shown on the left side. Both nametables together is 512 pixels wide but the scroll can only count 256 pixels. The solution is to switch which nametable is on the left side of the screen at the same time the scroll register wraps to 0.


Vertical mirroring means nametables are arranged horizontally


Scrolling shows nametable 0 and 1 (blue) on the screen (red)


When the scroll register wraps, nametable 0 is displayed again


Swap which nametable is on the left when the wrap happens to display nametable 1


To set the starting nametable, change bit 0 of the PPU control register at $2000. Clearing it to 0 will put nametables 0 and 2 on the left side of the screen with 1 and 3 to the right. Setting it to 1 will put 1 and 3 on the left, and 0 and 2 on the right.

This sample code has the same scroll incrementing, but swaps the nametables at the same time the scroll wraps from 255 to 0. Instead of the background jumping it continuously scrolls from one nametable to the next. When the scroll wraps again the nametables are swapped again and the scrolling keeps going.

NMI:

  INC scroll       ; add one to our scroll variable each frame
NTSwapCheck:
  LDA scroll       ; check if the scroll just wrapped from 255 to 0
  BNE NTSwapCheckDone
  
NTSwap:
  LDA nametable    ; load current nametable number (0 or 1)
  EOR #$01         ; exclusive OR of bit 0 will flip that bit
  STA nametable    ; so if nametable was 0, now 1
                   ;    if nametable was 1, now 0
NTSwapCheckDone:

  LDA #$00
  STA $2003       
  LDA #$02
  STA $4014       ; sprite DMA from $0200
  
  ; run other game graphics updating code here

  LDA #$00
  STA $2006        ; clean up PPU address registers
  STA $2006
  
  LDA scroll
  STA $2005        ; write the horizontal scroll count register

  LDA #$00         ; no vertical scrolling
  STA $2005
    
  ;;This is the PPU clean up section, so rendering the next frame starts properly.
  LDA #%10010000   ; enable NMI, sprites from Pattern Table 0, background from Pattern Table 1
  ORA nametable    ; select correct nametable for bit 0
  STA $2000
  
  LDA #%00011110   ; enable sprites, enable background, no clipping on left side
  STA $2001
    
  ; run normal game engine code here
  ; reading from controllers, etc
  
  RTI              ; return from interrupt

The full code and compiled .NES file is available from the download link at the bottom of this tutorial. scrolling2.asm includes everything up to this point.


Drawing New Columns
For just two screens of graphics the code above is fine. Games like Super Dodgeball use this method. Both nametables are filled and scrolled between. For games like SMB where the levels are wider than two screens some new background data will have to be inserted. The solution is to draw a new vertical column of tiles somewhere off the visible screen, before it is scrolled into the visible area. As long as the new column is drawn ahead of the visible area, calculated by the current scroll and nametable, it will appear continuous. The tricky part is figuring out which column to draw, and where it is to be placed. If we always use the opposite nametable and the same scroll point we will be drawing the column that is about to come on screen.




>When to Draw
We will draw a new column anytime the scroll register becomes a multiple of 8, meaning the scroll is aligned to the tiles. Some bit masking and testing can calculate when this happens. First any part of the scroll not 0 to 7 is thrown away. Then if the result equals 0 the scroll count is a multiple of 8.

  LDA scroll
  AND #%00000111     ; throw away higher bits
  BEQ DrawNewColumn  ; see if lower bits = 0

Where to Draw
Now that we know when to draw, we need to calculate the starting PPU address of the new column. The scroll register counts in pixels, but we want to count in tiles for which column to draw. Each tile is 8 pixels wide, so we divide the scroll by 8 to get the tile number. That number is the low bits of the address.

  LDA scroll
  LSR A
  LSR A
  LSR A            ; shift right 3 times = divide by 8
  STA columnLow    ; $00 to $1F, screen is 32 tiles wide

The high bits of the address will come from the current nametable. First the low bit is inverted, to get the off screen nametable number. Then the number is shifted up and added to the base address.

  LDA nametable
  EOR #$01          ; invert low bit, A = $00 or $01
  ASL A             ; shift up, A = $00 or $02
  ASL A             ; $00 or $04
  CLC
  ADC #$20          ; add high byte of nametable base address ($2000)
  STA columnHigh    ; now address = $20 or $24 for nametable 0 or 1

Now the scroll count and nametable have been used to make the full column address to start copying new background data. It will be at the top of the nametable that is off screen. As the scroll and nametable are changed, that calculation will still give the correct starting address.

How to Draw
Previously when we have been copying data to the background the PPU is set to auto increment the address by 1. That helps with the copying because a whole row of data can be copied while only writing the PPU address once. Incrementing by 1 goes to the next horizontal tile. In this case we want to go to the next vertical tile because we are copying a column instead of a row. We want it to increment by 32 which will jump down instead of across. There are 32 tiles per row, so adding 32 will always go down to the next row in the same column. The PPU has an increment 32 mode, set using bit 2 in the PPU control register at $2000. When bit 2 is set to 0 the increment mode is +1. When bit 2 is set to 1 the increment mode is +32. By setting the increment mode to +32 and copying 30 bytes of background tiles we can draw one column at a time.

DrawColumn:
  LDA #%00000100        ; set to increment +32 mode, don't care about other bits
  STA $2000
  
  LDA $2002             ; read PPU status to reset the high/low latch
  LDA columnHigh
  STA $2006             ; write the high byte of column address
  LDA columnLow
  STA $2006             ; write the low byte of column address
  LDX #$1E              ; copy 30 bytes
  LDY #$00
DrawColumnLoop:
  LDA columnData, y
  STA $2007
  INY
  DEX
  BNE DrawColumnLoop

By using the when/where/how we can draw a new column of data off screen before it becomes visible. The full code and compiled .NES file is available from the download link at the bottom of this tutorial. scrolling3.asm includes everything up to this point. It will be best to watch in an emulator where you can see everything that is off screen. First open the scrolling3.nes file in the FCEUXDSP emulator. Then choose "Name Table Viewer..." from the "Tools" menu. Reset the emulator and watch the new columns being drawn off the visible screen area.


Drawing Real Background Data
The last example drew new columns, but it wasn't any real data. This example adds another counter to keep track of how far along into the level a player is. By incrementing this counter every time a new column is drawn the correct next column is easy to find. The DrawNewColumn function has been updated to use the counter to load real background data. It can also be used at the beginning of the game initialization to populate the starting nametable data instead of using the fill loops.

The full code and compiled .NES file is available from the download link at the bottom of this tutorial. scrolling4.asm includes 4 screens (128 columns) of real background ripped from SMB.


Updating the Attributes
The final piece of the scrolling puzzle is the attribute table. Updating it is the same process as the background, where the attributes are updated while they are off screen. Again the scroll and nametable registers will be used to calculate the correct attribute bytes to update. Each attribute byte covers a 4x4 tile area. 4 tiles wide is 32 pixels, so the attributes must be updated anytime the scroll register is a multiple of 32. The column numbers already calculated could be used instead of the scroll variables to do the calculations.

  LDA scroll
  AND #%00011111     ; check for multiple of 32
  BEQ NewAttrib      ; if low 5 bits = 0, time to write new attribute bytes

Only 8 attribute bytes will need to be changed each time. However they are not sequential, so the PPU increment +1 or +32 modes will not work. The PPU address needs to be changed for every attribute byte updated. The starting address is the base attribute table at $20C0. Like the background address the nametable bit is shifted up and added in. Then the scroll register is divided by 32 to get the attribute byte offset. All that is calculated together to find the PPU address of the first attribute byte. After that 8 is added to the address for each of the next bytes.

  LDA nametable
  EOR #$01          ; invert low bit, A = $00 or $01
  ASL A             ; shift up, A = $00 or $02
  ASL A             ; $00 or $04
  CLC
  ADC #$20          ; add high byte of attribute base address ($20C0)
  STA columnHigh    ; now address = $20 or $24 for nametable 0 or 1
  
  LDA scroll
  LSR A
  LSR A
  LSR A
  LSR A
  LSR A
  CLC
  ADC #$C0
  STA columnLow     ; attribute base + scroll / 32

The full code and compiled .NES file is available from the download link at the bottom of this tutorial. scrolling5.asm has the same incrementing scroll, but now draws the new column and attribute bytes. Use the Name Table Viewer again to check out the attributes being updated. You can see the attribute update change the color of the off screen clouds before that column of tiles is changed. The same thing is why you see graphical glitches on the sides of SMB3 while it is scrolling. To use this in your own game you will need to expand columnNumber to a bigger value.



Once you have understood everything here, there are some more advanced concepts to check out:

Meta Tiles - This idea is to store your backgrounds as bigger blocks instead of individual tiles. Things like the question blocks would be stored as one byte in the ROM and then decoded into the 4 tiles when it is being drawn. Mostly this saves huge amounts of data space and could make updating attributes easier.

Buffers - A section of RAM can be reserved to act as a buffer for the data to draw to the PPU later. Outside of vblank where the is more processing time the next graphics updates would be calculated and stored in a buffer. Then during vblank those buffers can be dumped right to the PPU, saving time.

Compression - Packing the background data into simple compression formats like RLE can save even more data space. Combine that with meta tiles and buffers to have a full scrolling engine.

Putting It All Together
Download and unzip the scrolling.zip sample files. Each of them adds a small step, so go through them one at a time. Try expanding the background data to add more columns, making the scroll speed variable, or making the scrolling controlable.

This Week: After scrolling this tutorial should be pretty simple. Sprite 0 has a special PPU flag associated with it. Here it will be used to do split screen scrolling to enable a static status bar on the top of the screen.



Sprite 0 Hit Flag
Sprite 0 has a special flag in the PPU status register at bit 6. When a non transparent pixel of sprite 0 overlaps a non transparent pixel of the background, the flag is set. In the SMB example, sprite 0 is placed at the bottom of the coin icon. That is one part of the status bar that does not move.

People are starting to complete the Nerdy Nights tutorial series and we're seeing a lot of new homebrewers in the forum.  This is great!  One question that a lot of people ask after finishing up their Pong game is "how do I do sound?"  Well, I hope to teach you .

The plan is to have a series of tutorial that take you from having no sound to having a working music/sfx engine.  We'll start very simple (making a beep) and work our way up.  These tutorials will assume that you have completed the original Nerdy Nights tutorials (I won't reteach binary or 6502).

And I'm going to steal bunnyboy's disclaimer and re-use it as my own:

And finally these will not be without errors to begin with and may not be the absolute best way to do anything. People develop their own programming styles and this is just mine...

The APU

Music and sound effects on the NES are generated by the APU (Audio Processing Unit), the sound chip inside the CPU.  The CPU "talks" to the APU through a series of I/O ports, much like it does with the PPU and joypads.

PPU: $2000-$2007
Joypads: $4016-$4017
APU: $4000-$4015, $4017

Channels

The APU has 5 channels: Square 1, Square 2, Triangle, Noise and DMC.  The first four play waves and are used in just about every game.  The DMC channel plays samples (pre-recorded sounds) and is used less often.

Square
The square channels produce square waveforms.  A square wave is named for its shape.  It looks like this:
 
As you can see the wave transitions instantaneously from its high point to its low point (where the lines are vertical).  This gives it a hollow sound like a woodwind or an electric guitar.

Triangle
The triangle channel produces triangle waveforms.  A triangle wave is also named for its shape.  It looks like this:
 
The sound of a triangle wave is smoother and less harsh than a square wave. On the NES, the triangle channel is often used for bass lines (in low octaves) or a flute (in high octaves).  It can also be used for drums.

Noise
The noise channel has a random generator, which makes the waves it produces sound like.. noise.  This channel is generally used for percussion and explosion sounds.

DMC
The DMC channel plays samples, which are pre-recorded sounds.  It is often used to play voice recordings ("Blades of Steel") and percussion samples.  Samples take up a lot of ROM space, so not many games make use of the DMC channel.


Enabling Channels

Before you can use the channels to produce sounds, you need to enable them.  Channels are toggled on and off via port $4015:

APUFLAGS ($4015)

76543210
   |||||
   ||||+- Square 1 (0: disable; 1: enable)
   |||+-- Square 2
   ||+--- Triangle
   |+---- Noise
   +----- DMC

Here are some code examples using $4015 to enable and disable channels:   
   
   lda #%00000001
   sta $4015 ;enable Square 1 channel, disable others
 
   lda #%00010110
   sta $4015 ;enable Square 2, Triangle and DMC channels.  Disable Square 1 and Noise.
 
   lda #$00
   sta $4015 ;disable all channels
 
   lda #$0F
   sta $4015 ;enable Square 1, Square 2, Triangle and Noise channels.  Disable DMC.
             ;this is the most common usage.
             
Try opening up some of your favorite games in FCEUXD SP and set a breakpoint on writes to $4015.  Take a look at what values are getting written there.  If you don't know how to do this, follow these steps:

1. Open FCEUXD SP
2. Load a ROM
3. Open up the Debugger by pressing F1 or going to Tools->Debugger
4. In the top right corner of the debugger, under "BreakPoints", click the "Add..." button
5. Type "4015" in the first box after "Address:"
6. Check the checkbox next to "Write"
7. Set "Memory" to "CPU Mem"
8. Leave "Condition" and "Name" blank and click "OK"

Now FCEUX will pause emulation and snap the debugger anytime your game makes a write (usually via STA) to $4015.  The debugger will tell you the contents of the registers at that moment, so you can check what value will be written to $4015.  Some games will write to $4015 every frame, and some only do so once at startup.  Try resetting the game if your debugger isn't snapping.

What values are being written to $4015?  Can you tell what channels your game is using?


Square 1 Channel

Let's make a beep.  This week we'll learn how to produce a sound on the Square 1 channel.  The Square channels are everybody's favorites because you can control the volume and tone and perform sweeps on them.  You can produce a lot of interesting effects using the Squares.

Square 1 is controlled via ports $4000-$4003.  The first port, $4000, controls the duty cycle (ie, tone) and volume for the channel.  It looks like this:

SQ1_ENV ($4000)

76543210
||||||||
||||++++- Volume
|||+----- Saw Envelope Disable (0: use internal counter for volume; 1: use Volume for volume)
||+------ Length Counter Disable (0: use Length Counter; 1: disable Length Counter)
++------- Duty Cycle

For our purposes, we will focus on Volume and Duty Cycle.  We will set Saw Envelope Disable and Length Counter Disable to 1 and then forget about them.  If we leave Saw Envelopes on, the volume of the channel will be controlled by an internal counter.  If we turn them off, WE have control of the volume.  If WE have control, we can code our own envelopes (much more versatile).  Same thing with the Length Counter.  If we disable it, we have more control over note lengths.  If that didn't make sense, don't worry.  It will become clearer later.  For now we're just going to disable and forget about them.

Volume controls the channel's volume.  It's 4 bits long so it can have a value from 0-F.  A volume of 0 silences the channel.  1 is very quiet and F is loud.

Duty Cycle controls the tone of the Square channel.  It's 2 bits long, so there are four possible values:

00 = a weak, grainy tone.  Think of the engine sounds in RC Pro-Am. (12.5% Duty)
01 = a solid mid-strength tone. (25% Duty)
10 = a strong, full tone, like a clarinet or a lead guitar (50% Duty)
11 = sounds a lot like 01 (25% Duty negated)

The best way to know the difference in sound is to listen yourself.  I recommend downloading FamiTracker and playing with the different Duty settings in the Instrument Editor.

For those interested, Duty Cycle actually refers to the percentage of time that the wave is in "up" position vs. "down" position.  Here are some pictures:

12.5% 25%

50%

25% negated


Don't sweat it if graphs and waves aren't your thing.  Use your ears instead.

Here's a code snippet that sets the Duty and Volume for the Square 1 channel:

    lda #%10111111; Duty 10 (50%), volume F (max!)
    sta $4000

$4001 controls sweeps for Square 1.  We'll skip them for now.

Setting the Note
$4002 and $4003 control the period of the wave, or in other words what note you hear (A, C#, G, etc).  Periods are 11-bits long.  $4002 holds the low 8-bits and $4003 holds the high 3-bits of the period.  We'll get into more detail in a future tutorial, but for now just know that changing the values written to these ports will change the note that is played.

SQ1_LO ($4002)

76543210
||||||||
++++++++- Low 8-bits of period

SQ1_HI ($4003)

76543210
||||||||
|||||+++- High 3-bits of period
+++++---- Length Counter

The Length Counter, if enabled, controls how long the note is played.  We disabled it up in the $4000 section, so we can forget about it for now.

Here is some code that will produce an eternal beep on the Square 1 channel:

    lda #%00000001
    sta $4015 ;enable square 1
 
    lda #%10111111 ;Duty 10, Volume F
    sta $4000
 
    lda #$C9    ;0C9 is a C# in NTSC mode
    sta $4002
    lda #$00
    sta $4003
    
Putting It All Together
Download and unzip the square1.zip sample files. All the code above is in the square1.asm file. Make sure square1.asm and square1.bat are all in the same folder as NESASM3, then double click square1.bat. That will run NESASM3 and should produce the square1.nes file. Run that NES file in FCEUXD SP to listen to your beep!  Edit square1.asm to change the Volume (0 to F), or to change the Duty Cycle for the square wave.  Try changing the period to produce different notes.

Next Week: Square 2 and Triangle.  Multiple beeps!

Last Week: APU Overview and Square 1 Basics

This week: We will learn how to makes sounds with the Square 2 and Triangle channels.

Square 2

Last time we produced a beep on the Square 1 channel by making writes to $4000-$4003.  Now we'll learn how to do it with Square 2.  This is very easy because Square 1 and Square 2 are almost identical.  We control the Square 2 channel with ports $4004-$4007, and they more or less mirror Square 1's $4000-4003.

SQ2_ENV ($4004)

76543210
||||||||
||||++++- Volume
|||+----- Saw Envelope Disable (0: use internal counter for volume; 1: use Volume for volume)
||+------ Length Counter Disable (0: use Length Counter; 1: disable Length Counter)
++------- Duty Cycle


SQ2_SWEEP ($4005)
Skip this for now.  This port, incidentally, is where Square 2 differs from Square 1.


SQ2_LO ($4006)

76543210
||||||||
++++++++- Low 8-bits of period


SQ2_HI ($4007)

76543210
||||||||
|||||+++- High 3-bits of period
+++++---- Length Counter

To produce a sound, first we enable the channel via $4015:

    lda #%00000010 ;enable Square 2
    sta $4015
    
Then we write to the Square 2 ports:

    lda #%00111000 ;Duty Cycle 00, Volume 8 (half volume)
    sta $4004
 
    lda #$A9   ;$0A9 is an E in NTSC mode
    sta $4006
 
    lda #$00
    sta $4007
    
Except for sweeps, the Square 2 channel works just like the Square 1 channel.
    
Triangle

The Triangle channel produces triangle waveforms which have a smooth sound to them.  Think of the flute-like melody in the Dragon Warrior overland song.  That's the Triangle.

Unlike the Square channels, we have no control over the Triangle channel's volume or tone.  It makes only one type of sound and it's either on (playing) or off (silent).  We manipulate the Triangle channel via ports $4008-$400B.

TRI_CTRL ($4008)

76543210
||||||||
|+++++++- Value
+-------- Control Flag (0: use internal counters; 1: disable internal counters)

The triangle channel has two internal counters that can be used to automatically control note duration.  We are going to disable them so that we can control note length manually.  We will set the Control Flag to 1 and forget about it.

When the internal counters are disabled, Value controls whether the channel is on or off.  To silence the channel, set Value to 0.  To turn the channel on (ie, unsilence), set Value to any non-zero value.  Here are some examples:

    lda #%10000000 ;silence the Triangle channel
    sta $4008
 
    lda #%10000001 ;Triangle channel on
    sta $4008
 
    lda #%10001111 ;Triangle channel on
    sta $4008
 
    lda #%11111111 ;Triangle channel on
    sta $4008
    
Note that the last three examples are functionally the same.  Any non-zero value in Value makes the Triangle channel play.

Unused Port
$4009 is unused

Setting the Note
$400A and $400B control the period of the wave, or in other words what note you hear (A, C#, G, etc).  Like the Squares, Triangle periods are 11-bits long.  $400A holds the low 8-bits and $400B holds the high 3-bits of the period.  We'll learn more about periods next week, but for now just know that changing the values written to these ports will change the note that is played.

TRI_LO ($400A)

76543210
||||||||
++++++++- Low 8-bits of period

TRI_HI ($400B)

76543210
||||||||
|||||+++- High 3-bits of period
+++++---- Length Counter

The Length Counter, if enabled, controls how long the note is played.  We disabled it up in the $4008 section, so we can forget about it for now.

Here is some code to play an eternal beep on the Triangle channel:

    lda #%00000100 ;enable Triangle channel
    sta $4015

    lda #%10000001 ;disable counters, non-zero Value turns channel on
    sta $4008
 
    lda #$42   ;a period of $042 plays a G# in NTSC mode.
    sta $400A
 
    lda #$00
    sta $400B
    
Multiple Beeps
We now know how to use the Square 1, Square 2 and Triangle channels to make sound.  It doesn't take too much extra work to make them all play at the same time.  We just have to enable all three channels via $4015 and then write to the ports.  Here's some code that will play a C#m chord (C# E G#) using the knowledge we have gained up to now:

    lda #%00000111  ;enable Sq1, Sq2 and Tri channels
    sta $4015
 
    ;Square 1
    lda #%00111000  ;Duty 00, Volume 8 (half volume)
    sta $4000
    lda #$C9        ;$0C9 is a C# in NTSC mode
    sta $4002       ;low 8 bits of period
    lda #$00
    sta $4003       ;high 3 bits of period
 
    ;Square 2
    lda #%01110110  ;Duty 01, Volume 6
    sta $4004
    lda #$A9        ;$0A9 is an E in NTSC mode
    sta $4006
    lda #$00
    sta $4007
 
    ;Triangle
    lda #%10000001  ;Triangle channel on
    sta $4008
    lda #$42        ;$042 is a G# in NTSC mode
    sta $400A
    lda #$00
    sta $400B
    
Putting It All Together
Download and unzip the triad.zip sample files. All the code above is in the triad.asm file. Make sure triad.asm and triad.bat are all in the same folder as NESASM3, then double click triad.bat. That will run NESASM3 and should produce the triad.nes file. Run that NES file in FCEUXD SP to listen to your C#m chord!  Edit triad.asm to change the Volume and Duty Cycle for the square waves.  Try changing the Periods to produce different notes.

Try to silence the various channels by either disabling them via $4015 or silencing them via $4000/$4004/$4008.

Finally try writing some code that will silence/unsilence the individual channels based on user input, like so:

A: toggle Square 1 channel on/off
B: toggle Square 2 channel on/off
Select: toggle Triangle channel on/off

Next Week: Periods and Lookup Tables

Last Week: Square 2 and Triangle Basics

This week: We will learn about periods and build a period lookup table that spans 8 octaves.

Periods

In the last two lessons, I've been giving you the values to plug into the 11-bit periods for the Square and Triangle channels.  I haven't been giving you an explanation of what a period is, or where I got those numbers.  So this week we're going to learn about periods.

What is a period?
A period refers to the length of a wave, or rather the time length of the repeating part of a wave.  Take a look at this square wave (x-axis is time):

Notice how it is repeating.  It starts high and remains high for 2 time units.  Then it goes low and remains low for 2 time units.  Then it repeats.  When we say period, we are talking about the horizontal time length of this repeating wave.  In this case, the period is 4 time units.  The longer a period is, the lower the note will sound.   Conversely, the shorter a period is, the higher the note will sound.  Look at these 3 Square waves:

Period = 6 time units

Period = 4 time units

Period = 1 time unit

The top wave has the longest period (6 time units) and it will sound the lowest.  The bottom wave has a short period (1 time unit) and will sound higher than the other two.

On the NES, we write an 11-bit period to the APU ports.  The smaller the number, the shorter the period, the higher the note.  Larger numbers = longer periods = lower notes.  Look at the following code snippets that write an 11-bit period to the Square 1 ports:

    lda #$C9
    sta $4002
    lda #$05
    sta $4003 ;period $5C9: large number = long period = low note
 
    ;----
 
    lda #$09
    sta $4002
    lda #$00
    sta $4003 ;period $009: small number = short period = very high note

Periods -> Notes
So how do we know which 11-bit period values correspond to which notes?  The magic forumla is:

    P = C/(F*16) - 1
    
    P = Period
    C = CPU speed (in Hz)
    F = Frequency of the note (also in Hz).  
    
The value of C differs between NTSC and PAL machines, which is why a game made for NTSC will sound funny on a PAL NES, and vice-versa.

To find the period values for notes, we will have to look up note frequencies and plug them into the formula.  Or we can cross our fingers and hope somebody has already done the work for us and put the answers in an easy-to-read table.  Lucky for us a cool fellow named Celius has done just that, for both NTSC and PAL.  Here are the charts:

http://www.freewebs.com/the_bott/NotesTableNTSC.txt
http://www.freewebs.com/the_bott/NotesTablePAL.txt

Lookup Tables
It is fairly common practice to store period values in a lookup table.  A lookup table is a table of pre-calculated data stored in ROM.  Like an answer sheet.  Lookup tables are used to cut down on complicated, time-consuming calculations.  Let's look at a trivial example.  Let's say you want a subroutine that takes a value in A and returns 3^A.  If you took the brute-force approach, you might write something like this:

multiplier .rs 1

; takes a value (0-5) in A and returns 3^A
three_to_the_a:
    bne .not_zero
    lda #$01        ;3^0 is 1
    rts
.not_zero:
    tay
    lda #$03
.loop:    
    sta multiplier
    dey
    beq .done
    clc
    adc multiplier
    adc multiplier
    jmp .loop
.done:
    rts
    
It works, but it's not very pretty.  Here is how we would do it with a lookup table:

;lookup table with pre-calculated answers
powers_of_3:
    .byte 1, 3, 9, 27, 81, 243
 
three_to_the_a:
    tay
    lda powers_of_3, y
    rts
    
Easier to code.  Easier to read.  And it runs faster too.

NESASM3 Tip#1: Local Labels
You may have noticed in the above example that I put a period in front of some labels: .done, .loop, .not_zero.  NESASM3 treats these as local labels.  There are two types of labels: global and local.  A global label exists across the whole program and must be unique.  A local label only exists between two global labels.  This means that we can reuse the names of local labels - they only need to be unique within their scope.  Using local labels saves you the trouble of having to create unique names for common case labels (like looping).  I tend to use local labels for all labels that occur within subroutines.  To make a label local, stick a period in front of it.
    
Note Lookup Table
Let's take Celius's tables and turn them into a note lookup table. Period values are 11 bits so we will need to define our lookup table using words.  Note that .word is the same as .dw.  Here is a note_table for NTSC:

;Note: octaves in music traditionally start from C, not A.  
;      I've adjusted my octave numbers to reflect this.
note_table:
    .word                                                                $07F1, $0780, $0713 ; A1-B1 ($00-$02)
    .word $06AD, $064D, $05F3, $059D, $054D, $0500, $04B8, $0475, $0435, $03F8, $03BF, $0389 ; C2-B2 ($03-$0E)
    .word $0356, $0326, $02F9, $02CE, $02A6, $027F, $025C, $023A, $021A, $01FB, $01DF, $01C4 ; C3-B3 ($0F-$1A)
    .word $01AB, $0193, $017C, $0167, $0151, $013F, $012D, $011C, $010C, $00FD, $00EF, $00E2 ; C4-B4 ($1B-$26)
    .word $00D2, $00C9, $00BD, $00B3, $00A9, $009F, $0096, $008E, $0086, $007E, $0077, $0070 ; C5-B5 ($27-$32)
    .word $006A, $0064, $005E, $0059, $0054, $004F, $004B, $0046, $0042, $003F, $003B, $0038 ; C6-B6 ($33-$3E)
    .word $0034, $0031, $002F, $002C, $0029, $0027, $0025, $0023, $0021, $001F, $001D, $001B ; C7-B7 ($3F-$4A)
    .word $001A, $0018, $0017, $0015, $0014, $0013, $0012, $0011, $0010, $000F, $000E, $000D ; C8-B8 ($4B-$56)
    .word $000C, $000C, $000B, $000A, $000A, $0009, $0008                                    ; C9-F#9 ($57-$5D)

Notice that at the highest octaves, some notes have the same value (C9 and C#9 for example).  This is due to rounding.  We lose precision the higher we go, and a lot of the highest notes will sound out of tune as a result.  So in songs we probably wouldn't use octaves 8 and 9.  These high notes could be utilized for sound effects though, so we'll leave them in.
    
Once we have a note lookup table, we use the note we want as an index into the table and pull the period values from it, like this:
    
    lda #$0C            ;the 13th entry in the table (A2)
    asl a               ;multiply by 2 because we are indexing into a table of words
    tay
    lda note_table, y   ;read the low byte of the period
    sta $4002           ;write to SQ1_LO
    lda note_table+1, y ;read the high byte of the period
    sta $4003           ;write to SQ1_HI
    
To make it easier to know which index to use for each note, we can create a list of symbols:

;Note: octaves in music traditionally start at C, not A

;Octave 1
A1 = $00    ;"1" means octave 1.
As1 = $01   ;"s" means "sharp"
Bb1 = $01   ;"b" means "flat".  A# == Bb
B1 = $02

;Octave 2
C2 = $03
Cs2 = $04
Db2 = $04
D2 = $05
;...
A2 = $0C
As2 = $0D
Bb2 = $0D
B2 = $0E

;Octave 3
C3 = $0F
;... etc

Now we can use our new symbols instead of the actual index values:

    lda #A2             ;A2.  #A2 will evaluate to #$0C
    asl a               ;multiply by 2 because we are indexing into a table of words
    tay
    lda note_table, y   ;read the low byte of the period
    sta $4002           ;write to SQ1_LO
    lda note_table+1, y ;read the high byte of the period
    sta $4003           ;write to SQ1_HI
    
And if later we want to have a series of notes, symbols are much easier to read and alter:

sound_data:
    .byte C3, E3, G3, B3, C4, E4, G4, B4, C5 ; Cmaj7 (CEGB)
 
sound_data_no_symbols:
    .byte $0F, $13, $16, $1A, $1B, $1F, $22, $26, $27 ;same as above, but hard to read. Cmaj7 (CEGB)
    

Low Notes On Squares (Sweep Unit)
One last thing needs to be mentioned.  It's very important.  It has to do with the Square channels' sweep units.   The sweep units can silence the square channels in certain situations (Periods >= $400, our lowest notes), even when disabled.  We'll have to take a quick look at the sweep unit ports to solve this problem.

SQ1_SWEEP ($4001), SQ2_SWEEP ($4005)

76543210
||||||||
|||||+++- Shift
||||+---- Negate
|+++----- Sweep Unit Period
+-------- Enable (1: enabled; 0: disabled)

I'm not going to go into how it works now, but the unwanted silencing of low notes can be circumvented by setting the negate flag:

    lda #$08    ;set Negate flag on the sweep unit
    sta $4001   ;or $4005 for Square 2.
    
If you really want to know why, check the Sweep Unit section of blargg's NES APU Sound Hardware Technical Reference.

What about PAL?
For simplicity, these tutorials are going to use NTSC numbers.  Once we finish our sound engine I'll try to whip up a tutorial about adding PAL support.

Putting It All Together
Download and unzip the periods.zip sample files.  Make sure periods.asm, periods.chr, note_table.i and periods.bat are all in the same folder as NESASM3, then double click periods.bat. That will run NESASM3 and should produce the periods.nes file. Run that NES file in FCEUXD SP.  Use the d-pad to select and play any note from our note table on the Square 1 channel.  Controls are as follows:

Up - Play selected note
Down - Stop note
Left - Move selection down a note
Right - Move selection up a note

Homework: Edit periods.asm and add support for the Square 2 and Triangle channels.  Allow the user to select between channels and play different notes on all three of them.

Homework #2: Read Disch's document The Frame and NMIs.  Pay special attention to the "Take Full Advantage of NMI" section.  We are going to use this style of NMI handler with our sound engine.  In fact, periods.asm already uses it.

Next Week: Starting our sound engine.

Last Week: Periods, Lookup Tables

This Week: Sound Engine Basics.  We will setup the framework to get our sound engine running.

Sound Engine

Now that we know how to get notes to play we can start thinking about our sound engine.  What do we want it to be able to do?  How will the main program interact with it?

It's good practice to separate the different pieces of your program.  The sound engine shouldn't be messing with main program code and vice-versa.  If you mix them, your code becomes harder to read, the danger of variable conflicts increases and you open yourself up to hard-to-find bugs.   If you keep the different pieces of your program separate, you get the opposite: your code reads well, you avoid variable conflicts, and bugs are easier to trace.  Separation also improves your ability to reuse code.  If your sound engine only accesses its own internal routines and variables, it makes it that much easier to pull it out from one game and plug it into another.

There has to be some communication between the main program and the sound engine of course.  The main program needs to be able to tell the sound engine to do things like: "Play song 2" or "shut up".  But we don't want the main program sticking its nose in the sound engine's business.  We only want it to issue commands.  The sound engine will handle the rest on its own.

To set this up, we will create a small set of subroutines that the main program can use to invoke the sound engine and give it commands.  I'll call these subroutines "entrances".  We want as few entrances into the sound engine as possible.  The sound engine itself will have several internal subroutines it can work with, but the main program will only use the entrances.

Entrances
So what will our entrance subroutines be?  We need to think about what the main program would need to tell the sound engine to do.  Here is a list of entrances we might want for our sound engine:

-Initialize sound engine    (sound_init)
-Load new song/sfx          (sound_load)
-Play a frame of music/sfx  (sound_play_frame)
-Disable sound engine       (sound_disable)

The names in paranthesis are what I'm going to call the subroutines in code.  I prefixed them with sound_ for readability.  You can tell at a glance that they are sound routines.  Here is a rundown of what our commands will do:

sound_init will enable channels and silence them.  It will also initialize sound engine variables.

sound_load will take a song/sfx number as input.  It will use that song number to index into a table of pointers to song headers.  It will read the appropriate header and set up sound engine variables.  If that didn't make sense, don't worry.  We'll be covering this stuff next week.

sound_play_frame will advance the sound engine by one frame.  It will run the note timers, read from the data streams (if necessary), update sound variables and make writes to the APU ports.  This stuff will also be covered in future weeks.

sound_disable will disable channels via $4015 and set a disable flag variable.

We already know enough to knock out two of those, sound_init and sound_disable.  Let's write them now.  We'll write skeleton code for the other entrance subroutines as well.  A few things to mention before we do that though:

RAM
A sound engine requires a lot of RAM.  A large sound engine might even take up a full page of RAM.  For this tutorial, we'll stick all our sound engine variables on the $300 page of RAM.  There is nothing magic about this number.  I chose $300 for convenience.  $000 is your zero-page RAM.  $100 is your stack.  If you completed the original Nerdy Nights series, $200 will be your Sprite OAM.  So $300 is next in line.

ROM
The sound engine itself won't require a lot of ROM space for code, but if you have a lot of music your song data might take up a lot of space.  For this reason, I'm going to change our header to give us two 16k PRG-ROM banks, like this:

    .inesprg 2 ;2x 16kb PRG code
    
Now we have twice as much ROM space, just in case we need it.  BTW, this is the maximum amount of ROM we can have without using a mapper.
    
Noise Channel
I purposely haven't covered the Noise channel yet.  We will want to silence it in our init code though, so I will go ahead and teach that much.  Noise channel volume is controlled via port $400C.  It works the same as $4000/$4004 does for the Square channels, except there is no Duty Cycle control:

NOISE_ENV ($400C)

76543210
  ||||||
  ||++++- Volume
  |+----- Saw Envelope Disable (0: use internal counter for volume; 1: use Volume for volume)
  +------ Length Counter Disable (0: use Length Counter; 1: disable Length Counter)
 
Like the Squares, we will silence the Noise channel by setting both disable flags, and setting the Volume to 0.
    
Skeleton Sound Engine
Let's write the entrance subroutines to our sound engine.  Most of this code should be very familiar to you if you completed the first three tutorials in this series.

    .rsset $0300 ;sound engine variables will be on the $0300 page of RAM
 
sound_disable_flag  .rs 1   ;a flag variable that keeps track of whether the sound engine is disabled or not.
                            ;if set, sound_play_frame will return without doing anything.

    .bank 0
    .org $8000  ;we have two 16k PRG banks now.  We will stick our sound engine in the first one, which starts at $8000.

sound_init:
    lda #$0F
    sta $4015   ;enable Square 1, Square 2, Triangle and Noise channels
 
    lda #$30
    sta $4000   ;set Square 1 volume to 0
    sta $4004   ;set Square 2 volume to 0
    sta $400C   ;set Noise volume to 0
    lda #$80
    sta $4008   ;silence Triangle
 
    lda #$00
    sta sound_disable_flag  ;clear disable flag
 
    ;later, if we have other variables we want to initialize, we will do that here.
 
    rts
 
sound_disable:
    lda #$00
    sta $4015   ;disable all channels
    lda #$01
    sta sound_disable_flag  ;set disable flag
    rts

sound_load:
    ;nothing here yet
    rts
 
sound_play_frame:
    lda sound_disable_flag
    bne .done       ;if disable flag is set, don't advance a frame
    ;nothing here yet
.done:
    rts

    
Driving the Sound Engine
We have the framework setup for our sound engine to run.  The main program now has subroutines it can call to issue commands to the sound engine.  Most of them don't do anything yet, but we can still integrate them into the main program.  First we will want to make a call to sound_init somewhere in our reset code:

RESET:
    sei
    cld
    ldx #$FF
    txs
    inx
 
    ;... clear memory, etc
 
    jsr sound_init

    ;... more reset stuff
    
Next we need something to drive our sound engine.  Music is time-based.  In any piece of music, assuming a constant tempo, each quarter note needs to last exactly as long as every other quarter note.  A whole note has to be exactly as long as four quarter notes.  If our sound engine is going to play music, it needs to be time-based as well.  We have a subroutine, sound_play_frame, that will advance our sound engine a frame at a time.  Now we need to ensure it gets called repeatedly at a regular time interval.

One way to do this is to stick it in the NMI.  Recall that when enabled, the NMI will trigger at the start of every vblank.  Vblank is the only safe time to write to the PPU, so the NMI is typically full of drawing code.  We don't want to waste our precious vblank time running sound code, but what about after we are finished drawing?  If we stick our call to sound_play_frame at the end of NMI, after the drawing code, we are set.  sound_play_frame gets called once per frame, and we avoid stepping on the PPU's toes.  And since sound_play_frame doesn't write to the PPU registers, it doesn't matter if our sound code spills out of vblank.  

Let's setup the NMI to drive our sound engine:

NMI:
    pha     ;save registers
    txa
    pha
    tya
    pha
 
    ;do sprite DMA
    ;update palettes if needed
    ;draw stuff on the screen
    ;set scroll
 
    jsr sound_play_frame    ;run our sound engine after all drawing code is done.
                            ;this ensures our sound engine gets run once per frame.
 
    lda #$00
    sta sleeping            ;did you do your homework and read Disch's document last week?
                            ;http://nesdevhandbook.googlepages...
 
    pla     ;restore registers
    tay
    pla
    tax
    pla
    rti

.include
To further separate our sound engine from the main program, we can keep all our sound engine code in a separate file.  NESASM3 gives us a directive .include that we can use to copy a source file into our main program.  We actually used this directive last week to include the note_table.i file, which contained our period lookup table.  

Using .include to copy a source file into our code is very similar to how we use .incbin to import a .chr file.  Assuming our sound engine code is saved in a file called sound_engine.asm, we will add the following code to our main program:
    
    .include "sound_engine.asm"

We will continue to include note_table.i, but since it is part of our sound engine we will stick the .include directive in the sound_engine.asm file.

It's not bad practice to use includes a lot.  You can pull your joypad routines out and stick them in their own file.  You can have separate files for your gamestate code, for your PPU routines and for just about anything else you can think of.  Breaking up your code like this will make it easier to find things as your program gets larger and more complicated.  It also makes it easier to plug your old routines into new programs.
    
Putting It All Together
Download and unzip the skeleton.zip sample files.  Make sure skeleton.asm, sound_engine.asm, skeleton.chr, note_table.i, sound_data.i and skeleton.bat are all in the same folder as NESASM3, then double click skeleton.bat. That will run NESASM3 and should produce the skeleton.nes file. Run that NES file in FCEUXD SP.

I've hardcoded sound_load and sound_play_frame to play a little melody on the Square 1 channel.  It uses a simple frame counter to control note speed.  The data for the music is found in the sound_data.i file.   Use the controller to interact with the sound engine.  Controls are as follows:
    
A: Play sound from the beginning (sound_load)
B: Initialize the sound engine (sound_init)
Start: Disable sound engine (sound_disable)

Try editing sound_engine.asm to change the data stream that sound_play_frame reads from.  The different data streams available are located in sound_data.i.  Try adding your own data stream to sound_data.i too.  Use the note symbols we made last week and terminate your data stream with $FF.

Homework: Write two new sound engine entrance subroutines for the main program to use:
        1. sound_pause: pauses playback of the sound, but retains the current position in the data stream.
        2. sound_unpause: if the sound is currently paused, resumes play from the saved position.
Then modify handle_joypad to allow the user to pause/unpause the music.

Homework #2: If the ideas presented in Disch's The Frames and NMIs document are still fuzzy in your head, read it again.

Extra Credit:  See if you can understand how my drawing buffer works.  Use Disch's document to help you.  I won't cover drawing buffers in these sound tutorials, for obvious reasons, but it is definitely worth your time to learn how to use them.
    
Next week: Sound Data, Pointer Tables, Headers

Last Week: Sound Engine Basics, Skeleton sound engine

This Week: Sound Data, Pointer Tables, Headers

Designing Sound Data

We have a skeleton sound engine in place.  Time to pack it with flesh and organs.  Before we can play a song, we will have to load a song.  Before we can load a song, we will need song data.  So our next step is to decide how our sound data will look.  We'll need to design our data format, create some test data and then build our engine to read and play that data.

Data Formats
So how do we go about designing a sound data format?  A good place to start would be to look at what we are aiming to play.  We know that our sound engine will have two basic types of sound data:

1. Music
2. Sound Effects (SFX)

Music plays in the background.  It uses the first 4 channels, has a tempo, and usually loops over and over again.

Sound Effects are triggered by game events (eg, ball hitting a paddle) and don't loop indefinitely.

Sound effects have the job of communicating to the player what is going on right now, so they have priority over music.  If there is music playing on the Square 2 channel, and a sound effect is also using the Square 2 channel, the sound effect should play instead of the music.

Depending on the game, some sound effects may have higher priority than others.  For example, in a Zelda-like game the sound of the player taking damage would have priority over the sound of the player swinging their sword.  The former communicates critical information to the player while the latter is just for effect.

Streams
As mentioned above, a sound effect will have to share a channel (or channels) with the music.  This is unavoidable because music typically uses all the channels at once, all the time.  So when a sound effect starts playing, it has to steal a channel (or more) away from the music.  The music will continue to play on the other channels, but the shared channel will go to the sound effect.  This creates an interesting problem: if we stop music on a channel to play a sound effect, how do we know where to resume the music on that channel when the sound effect is finished?

The answer is that we don't actually stop the music on the shared channel.  We still advance it frame by frame in time with the other music channels.  We just don't write its data to the APU ports when a sound effect is playing.

To do this, we will need to keep track of multiple streams of sound data.  A data stream is a sequence of bytes stored in ROM that the sound engine will read and translate into APU writes.  Each stream corresponds to one channel.  Music will have 4 data streams - one for each channel.  Sound effects will have 2 streams and the sfx themselves will choose which channel(s) they use.  So 6 streams total that could potentially be running at the same time.  We will number them like this:

MUSIC_SQ1 = $00 ;these are stream number constants
MUSIC_SQ2 = $01 ;stream number is used to index into stream variables (see below)
MUSIC_TRI = $02
MUSIC_NOI = $03
SFX_1     = $04
SFX_2     = $05


Each stream will need it's own variables in RAM.  An easy way to organize this is to reserve RAM space in blocks and use the stream number as an index:

;reserve 6 bytes each, one for each stream
stream_curr_sound .rs 6     ;what song/sfx # is this stream currently playing?    
stream_channel .rs 6        ;what channel is it playing on?
stream_vol_duty .rs 6       ;volume/duty settings for this stream
stream_note_LO .rs 6        ;low 8 bits of period for the current note playing on the stream
stream_note_HI .rs 6        ;high 3 bits of the note period
;..etc

Here we have 6 bytes reserved for each variable.  Each stream gets its own byte, for example:
    stream_vol_duty+0:  MUSIC_SQ1's volume/duty settings
    stream_vol_duty+1:  MUSIC_SQ2's volume/duty
    stream_vol_duty+2:  MUSIC_TRI's on/off
    stream_vol_duty+3:  MUSIC_NOI's volume
    stream_vol_duty+4:  SFX_1's volume/duty
    stream_vol_duty+5:  SFX_2's volume/duty
    
In our sound_play_frame code we will loop through all of the streams using the stream number as an index:
    
    ldx #$00    ;start at stream 0 (MUSIC_SQ1)
.loop:
    ;read from data stream in ROM if necessary
    ;update stream variables based on what we read
 
    lda stream_vol_duty, x  ;the value in x determines which stream we are working with
    ;do stuff with volume
 
    lda stream_note_LO, x
    ;do stuff with note periods
 
    ;do more stuff with other variables
 
    inx         ;next stream
    cpx #$06    ;loop through all six streams
    bne .loop

The music streams will always be running, updating the APU ports with their data frame by frame.  When a sound effect starts playing, one or both of the sfx streams will start running.  Because our loop processes the SFX streams last, they will write to the APU last and thus overwrite the shared-channel music streams.  Our channel conflict is taken care of automatically by the order of our loop!
    
Music
We now have an idea of how our stream data will be stored in RAM, but there are still many unanswered questions.  How do we load a song?  How do we know where to find the data streams in ROM?  How do we read from those data streams?  How do we interpret what we read from those streams?

To answer these questions, we need to make a data format.  Let's start with music.  What should our music data look like?  Most NES music data is divided into three types:

1. Note - what note to play: A3, G#5, C2, etc
2. Note Length - how long to play the notes: eighth note, quarter note, whole note, etc
3. Opcodes - opcodes tell the engine to perform specific tasks: loop, adjust volume, change Duty Cycle for squares, etc
*3.5. Arguments - some opcodes will take arguments as input (e.g. how many times to loop, where to loop to).

Ranges
We will need to design our data format to make it easy for the sound engine to differentiate between these three types of data.  We do this by specifying ranges.  For example, we might say that byte values of $00-$7F represent Notes.  $80-$9F are Note Lengths, and $A0-$FF are opcodes.  I just made those numbers up.  It really doesn't matter what values we use.  The important thing is that we have ranges to test against to determine whether a byte is a note, note length or opcode.  In our engine code we will have something like this:

fetch_byte:
    lda [sound_pointer], y      ;read a byte from the data stream
    bpl .note                   ;if < #$80, it's a Note
    cmp #$A0
    bcc .note_length            ;else if < #$A0, it's a Note Length
.opcode:                        ;else it's an opcode
    ;do Opcode stuff
.note_length:
    ;do Note Length stuff
.note:
    ;do Note stuff
    
This code reads a byte from the sound data and then tests that byte to see which range it falls into.  It jumps to a different section of code for each possible range.  Almost any data format you create will be divided into ranges like this, whether it be sound data, map data, text data, whatever.

BPL and BMI
These two branch instructions are worth learning if you don't know them already.  After BEQ, BNE, BCS and BCC they are the most common branch instructions.  They are often used in range-testing.

BPL tests the Negative (N) flag and will branch if it is clear.  Think of BPL as Branch if PLus.  The N flag will be clear if the last instruction executed resulted in a value less than #$80 (ie, bit7 clear).

    lda #%01101011
        ; |
        ; +-------- bit7 is clear.  This will clear the N flag.
    bpl .somewhere  ;N flag is clear, so this will branch
 
    lda #%10010101
        ; |
        ; +-------- bit7 is set.  This will set the N flag
    bpl .somewhere  ;N flag is set, so this will not branch.

BMI is the opposite.  It tests the N flag and will branch if it is set.  Think of BMI as Branch if MInus.  The N flag will be set if the last instruction executed resulted in a value greater than or equal to #$80 (ie, bit7 set).

    lda #%01101011
        ; |
        ; +-------- bit7 is clear.  This will clear the N flag.
    bmi .somewhere  ;N flag is clear, so this will not branch
 
    lda #%10010101
        ; |
        ; +-------- bit7 is set.  This will set the N flag
    bmi .somewhere  ;N flag is set, so this will branch to the label .somewhere.

In the range-testing code above, I used BPL to check if a byte fell into the Note range (00-7F).  Go back and check it.

Song Headers
Music on the NES is typically composed of four parts: a Square 1 part, a Square 2 part, a Triangle part and a Noise part.  When you want to play a song, you will have the main program issue a command to the sound engine telling it what song you want to play.  It will look something like this:

    lda #$02
    jsr sound_load  ;load song 2
    
Somehow our sound_load subroutine will have to take that "2" and translate it into a whole song, complete with Square 1, Square 2, Triangle and Noise parts.  How does that little number become 4 streams of data?  Well, that number is an index into a pointer table, a table of pointers to song headers.  The song headers themselves will contain pointers to the individual channels' data streams.

Pointer Tables
A pointer table is a special kind of lookup table.  Only instead of holding regular old numerical data a pointer table holds addresses.  These addresses "point" to the start of data.  Addresses on the NES are 16-bit ($0000-$FFFF), so pointer tables are always tables of words.  Let's look at an example:

pointer_table:
    .word $8000, $ABCD, $CC10, $DF1B
    
Here we have a pointer table.  It's four entries long.  Each entry is a 16-bit address.  Presumably there is data at these four addresses that we will want to read sometime in our program.  To read this data we will need to index into the pointer table, grab the address and store it in a zero-page pointer variable and then read using indirect mode:

    .rsset $0000
 
ptr1 .rs 2  ;a 2-byte pointer variable.
            ;The first byte will hold the LO byte of an address
            ;The second byte will hold the HI byte of an address

    .org $E000  ;somewhere in ROM

    lda #$02    ;the third entry in the pointer table ($CC10)
    asl a       ;multiply by 2 because we are indexing into a table of words
    tay
    lda pointer_table, y    ;#$10 - little endian, so words are stored LO-byte first
    sta ptr1
    lda pointer_table+1, y  ;#$CC
    sta ptr1+1
 
    ;now our pointer is setup in ptr1.  It "points" to address $CC10.  Let's read data from there.
 
    ldy #$00
    lda [ptr1], y   ;indirect mode.  reads the byte at $CC10
    sta some_variable
    iny
    lda [ptr1], y   ;reads the byte at $CC11
    sta some_other_variable
    iny
    ;... etc
    
This code takes an index and uses it to read an address from our pointer_table.  It stores this address in a variable called ptr1 (LO byte first).  Then it reads from this address by using indirect mode.  We specify indirect mode by putting []'s around our pointer variable.  Look at this instruction:  
    
    lda [ptr1], y

It means "Find the address ptr1 is pointing to.  Add Y to that address.  Load the value at that address into A".

This is very versatile because we can stick any address we want into our ptr1 variable and read from anywhere!  A pointer table is just a lookup table of places we want to read from.

Of course you usually won't know where exactly in the ROM your data will be.  So instead of declaring addresses explicitely ($8000, $ABCD, $CC10, etc), you will use labels instead:

pointer_table:
    .word data1, data2, data3       ;these entries will evaluate to the 16-bit addresses of the labels below

data1:
    .byte $FF, $16, $82, $44        ;some random data
 
data2:
    .byte $0E, $EE, $EF, $16, $23
 
data3:
    .byte $00, $01
   
Song Header Pointer Table
Our songs work the same way.  When the main program tells the sound engine to play a song, it will send the song number with it.  This song number is actually an index into a pointer table of song headers:
    
song_headers:
    .word song0_header
    .word song1_header
    .word song2_header
    ;..etc
 
sound_load:
    asl a                   ;multiply by 2.  we are indexing into a table of pointers (words)
    tay
    lda song_headers, y     ;read LO byte of a pointer from the pointer table.
    sta sound_ptr           ;sound_ptr is a zero page pointer variable
    lda song_headers+1, y   ;read HI byte
    sta sound_ptr+1
 
    ldy #$00
    lda [sound_ptr], y
    sta some_variable
    iny
    ;...read the rest of the header data
    
Header Data
So what will our song header data look like?  At the very least it should tell us:

How many data streams we have (songs will usually have 4, but sfx will have fewer)
Which streams those are (which stream index to use)
Which channels those streams use
Where to find those streams (ie, pointers to the beginning of each stream).
Initial values for those streams (for example, initial volume)

As we add more features to our sound engine, we may expand our headers to initialize those features.  Let's start simple.  Our headers will look like this:

main header:
--------+----------------
byte #  | what it tells us
--------+----------------
00      | number of streams
01+     | stream headers (one for each stream)

stream headers:
--------+----------------
byte #  | what it tells us
--------+----------------
00      | which stream (stream number)
01      | status byte (see below)
02      | which channel
03      | initial volume (and duty for squares)
04-05   | pointer to data stream

The status byte will be a bit-flag that tells us special information about the stream.  For now we will just use bit0 to mark a stream as enabled or disabled.  In the future we may use other bits to store other information, such as stream priority.

Stream Status Byte
76543210
       |
       +- Enabled (0: stream disabled; 1: enabled)


Sample Header
Here is some code showing a sample header:

SQUARE_1 = $00 ;these are channel constants
SQUARE_2 = $01
TRIANGLE = $02
NOISE = $03

MUSIC_SQ1 = $00 ;these are stream # constants
MUSIC_SQ2 = $01 ;stream # is used to index into stream variables
MUSIC_TRI = $02
MUSIC_NOI = $03
SFX_1     = $04
SFX_2     = $05

song0_header:
    .byte $04           ;4 streams
 
    .byte MUSIC_SQ1     ;which stream
    .byte $01           ;status byte (stream enabled)
    .byte SQUARE_1      ;which channel
    .byte $BC           ;initial volume (C) and duty (10)
    .word song0_square1 ;pointer to stream
 
    .byte MUSIC_SQ2     ;which stream
    .byte $01           ;status byte (stream enabled)
    .byte SQUARE_2      ;which channel
    .byte $38           ;initial volume (8) and duty (00)
    .word song0_square2 ;pointer to stream
 
    .byte MUSIC_TRI     ;which stream
    .byte $01           ;status byte (stream enabled)
    .byte TRIANGLE      ;which channel
    .byte $81           ;initial volume (on)
    .word song0_tri     ;pointer to stream
 
    .byte MUSIC_NOI     ;which stream
    .byte $00           ;disabled.  We will have our load routine skip the
                        ;   rest of the reads if the status byte disables the stream.
                        ;   We are disabling Noise because we haven't covered it yet.

;these are the actual data streams that are pointed to in our stream headers.   
song0_square1:
    .byte A3, C4, E4, A4, C5, E5, A5 ;some notes.  A minor
 
song0_square2:
    .byte A3, A3, A3, E4, A3, A3, E4 ;some notes to play on square 2
 
song0_tri:
    .byte A3, A3, A3, A3, A3, A3, A3 ;triangle data
    
Sound Engine Variables
The last thing we need before we can write our sound_load routine is some variables.  As mentioned, our sound engine will have several streams running simultaneously.  Four will be used for music (one for each tonal channel).  Two will be used for sound effects.  So we will declare all variables in blocks of 6.  Based on our header data, we will need the following variables:

stream_curr_sound .rs 6     ;reserve 6 bytes, one for each stream
stream_status .rs 6
stream_channel .rs 6
stream_vol_duty .rs 6
stream_ptr_LO .rs 6
stream_ptr_HI .rs 6

sound_load
Now let's write some code to read our header.  Pay special attention to the X register.  I recommend tracing through the code using the sample header above.  Here is our sound_load routine:

;-------------------------------------
; load_sound will prepare the sound engine to play a song or sfx.
;   input:
;       A: song/sfx number to play
sound_load:
    sta sound_temp1         ;save song number
    asl a                   ;multiply by 2.  We are indexing into a table of pointers (words)
    tay
    lda song_headers, y     ;setup the pointer to our song header
    sta sound_ptr
    lda song_headers+1, y
    sta sound_ptr+1
 
    ldy #$00
    lda [sound_ptr], y      ;read the first byte: # streams
    sta sound_temp2         ;store in a temp variable.  We will use this as a loop counter
    iny
.loop:
    lda [sound_ptr], y      ;stream number
    tax                     ;stream number acts as our variable index
    iny
 
    lda [sound_ptr], y      ;status byte.  1= enable, 0=disable
    sta stream_status, x
    beq .next_stream        ;if status byte is 0, stream disabled, so we are done
    iny
 
    lda [sound_ptr], y      ;channel number
    sta stream_channel, x
    iny
 
 
    lda [sound_ptr], y      ;initial duty and volume settings
    sta stream_vol_duty, x
    iny
 
    lda [sound_ptr], y      ;pointer to stream data.  Little endian, so low byte first
    sta stream_ptr_LO, x
    iny
 
    lda [sound_ptr], y
    sta stream_ptr_HI, x
.next_stream:
    iny
 
    lda sound_temp1         ;song number
    sta stream_curr_sound, x
 
    dec sound_temp2         ;our loop counter
    bne .loop
    rts
    
Now our sound_load routine is ready.  If the main program calls it, like this:

    lda #$00 ;song 0
    jsr sound_load
    
Our sound_load routine will take the value in the A register and use it to fill our music RAM with everything we need to get our song running!

Reading Streams
Once we have our header loaded, we are ready to rock.  All of our active streams have pointers to their data stored in their stream_ptr_LO and stream_ptr_HI variables.  That's all we need to start reading data from them.

To read data from our data stream, we will first copy the stream pointer into a zero-page pointer variable.  Then we will read a byte using indirect mode and range-test it to determine whether it is a note, note length or opcode.  If it's a note, we will read from our note_table and store the 11-bit period in RAM.  Finally, we will update our stream pointer to point to the next byte in the stream.  

First we will need to declare some new variable blocks for the note periods:

stream_note_LO .rs 6    ;low 8 bits of period
stream_note_HI .rs 6    ;high 3 bits of period

Here is our se_fetch_byte routine (se_ stands for "sound engine"):

;--------------------------
; se_fetch_byte reads one byte from a sound data stream and handles it
;   input:
;       X: stream number
se_fetch_byte:
    lda stream_ptr_LO, x    ;copy stream pointer into a zero page pointer variable
    sta sound_ptr
    lda stream_ptr_HI, x
    sta sound_ptr+1
 
    ldy #$00
    lda [sound_ptr], y      ;read a byte using indirect mode
    bpl .note               ;if <#$80, we have a note
    cmp #$A0                ;else if <#$A0 we have a note length
    bcc .note_length
.opcode:                    ;else we have an opcode
    ;nothing here yet
    jmp .update_pointer
.note_length:
    ;nothing here yet
    jmp .update_pointer
.note:
    asl                     ;multiply by 2 because we are index into a table of words
    sty sound_temp1         ;save our Y register because we are about to destroy it
    tay
    lda note_table, y       ;pull low 8-bits of period and store it in RAM
    sta stream_note_LO, x
    lda note_table+1, y     ;pull high 3-bits of period from our note table
    sta stream_note_HI, x
    ldy sound_temp1         ;restore the Y register
 
 ;update our stream pointers to point to the next byte in the data stream
 .update_pointer:
    iny                     ;set index to the next byte in the data stream
    tya
    clc
    adc stream_ptr_LO, x    ;add Y to the LO pointer
    sta stream_ptr_LO, x
    bcc .end
    inc stream_ptr_HI, x    ;if there was a carry, add 1 to the HI pointer.
.end:
    rts

Look at the part that updates the stream pointer.   After we finish all our reads, Y will hold the index of the last byte read.  To be ready for the next frame, we will want to update our pointer to point to the next byte in the data stream.  To do this, we increment Y and add it to the pointer.  But we have to be careful here.  What if our current position is something like this:

stream_ptr: $C3FF
Y: 1    

The next position here should be $C400.  But ADC only works on the 8-bit level, so if we add 1 to the low byte of the pointer we will get this instead:

stream_ptr: $C300

The FF in the low byte becomes 00, but the high byte remains the same.  We need to increment the high byte manually.  But how do we know when to increment it and when to leave it alone?  Lucky for us, ADC sets the carry flag whenever it makes a FF->00 transition.  So we can just check the carry flag after our addition.  If it is set, increment the high byte of the pointer.  If it is clear, don't increment it.  That's what our code above does.

Playing Music
We've loaded our header.  We've set up our stream pointers in RAM.  We've written a routine that will read bytes from the streams and turn them into notes.  Now we need to update sound_play_frame.  sound_play_frame will loop through all 6 streams.  It will check the status byte to see if they are enabled.  If enabled, it will advance the stream by one frame.  Here's the code:

sound_play_frame:
    lda sound_disable_flag
    bne .done   ;if sound engine is disabled, don't advance a frame
 
    inc sound_frame_counter     
    lda sound_frame_counter
    cmp #$08    ;***change this compare value to make the notes play faster or slower***
    bne .done   ;only take action once every 8 frames.
 
    ldx #$00                ;our stream index.  start at MUSIC_SQ1 stream
.loop:
    lda stream_status, x    ;check bit 0 to see if stream is enabled
    and #$01
    beq .next_stream        ;if disabled, skip to next stream
 
    jsr se_fetch_byte       ;read from the stream and update RAM
    jsr se_set_apu          ;write volume/duty, sweep, and note periods of current stream to the APU ports
 
.next_stream:
    inx
    cpx #$06                ;loop through all 6 streams.
    bne .loop
 
    lda #$00
    sta sound_frame_counter ;reset frame counter so we can start counting to 8 again.  
.done:
    rts


And here is se_set_apu which will write a stream's data to the APU ports:
    
se_set_apu:
    lda stream_channel, x   ;which channel does this stream write to?
    asl a
    asl a                   ;multiply by 4 so Y will index into the right set of APU ports (see below)
    tay
    lda stream_vol_duty, x
    sta $4000, y
    lda stream_note_LO, x
    sta $4002, y
    lda stream_note_HI, x
    sta $4003, y
 
    lda stream_channel, x
    cmp #TRIANGLE
    bcs .end        ;if Triangle or Noise, skip this part
    lda #$08        ;else, set negate flag in sweep unit to allow low notes on Squares
    sta $4001, y
.end:
    rts
    
Writing to the APU ports directly like this is actually bad form.  We'll learn why in a later lesson.

One thing to pay attention to is how we get our APU port index.  We take the channel and multiply it by 4.  Recall that we declared constants for our channels:

SQUARE_1 = $00 ;these are channel constants
SQUARE_2 = $01
TRIANGLE = $02
NOISE = $03

If our stream_channel is $00 (SQUARE_1), we multiply by 4 to get $00.  y = 0
    $4000, y = $4000  
    $4001, y = $4001
    $4002, y = $4002
    $4003, y = $4003
If our stream_channel is $01 (SQUARE_2), we multiply by 4 to get $04.  y = 4
    $4000, y = $4004  
    $4001, y = $4005  
    $4002, y = $4006
    $4003, y = $4007
If our stream_channel is $02 (TRIANGLE), we multiply by 4 to get $08.  y = 8
    $4000, y = $4008  
    $4001, y = $4009 (unused)  
    $4002, y = $400A
    $4003, y = $400B
If our stream_channel is $03 (NOISE), we multiply by 4 to get $0C.  y = C
    $4000, y = $400C  
    $4001, y = $400D  
    $4002, y = $400E
    $4003, y = $400F

See how everything lines up nicely?

Putting It All Together
Download and unzip the headers.zip sample files.  Make sure the following files are in the same folder as NESASM3:

    headers.asm
    sound_engine.asm
    headers.chr
    note_table.i
    song0.i
    song1.i
    song2.i
    song3.i
    headers.bat

Double click headers.bat. That will run NESASM3 and should produce the headers.nes file. Run that NES file in FCEUXD SP.

Use the controller to select songs and play them.  Controls are as follows:
    
Up: Play
Down: Stop
Right: Next Song
Left: Previous Song

Song0 is a silence song.  It is not selectable.  headers.asm "plays" song0 to stop the music when you press down.  See song0.i to find out how it works.
Song1 is an evil sounding series of minor thirds.
Song2 is a short sound effect on the Sq2 channel.  It uses the SFX_1 stream.  Try playing it over the other songs to see how it steals the channel from the music.
Song3 is a simple descending chord progression.

Try creating your own songs and sound effects and add them into the mix.  To add a new song you will need to take the following steps:

1) create a song header and song data (use the included songs as reference).  Note that data streams are terminated with $FF
2) add your header to the song_headers pointer table at the bottom of sound_engine.asm
3) update the constant NUM_SONGS to reflect the new song number total (also at the bottom of sound_engine.asm)

Although not necessary, I recommend keeping your song data in a separate file like I've done with song0.i, song1.i, song2.i and song3.i.  This makes it easier to find the data if you need to edit your song later.  If you do this, don't forget to .include your file.

Next Week: Timing, Note Lengths, Buffering and Rests

Last Week: Sound Data, Pointer Tables and Headers

This Week: Tempo, Note Lengths, Buffering and Rests

Timing

Last week we put together a huge chunk of the sound engine.  We finally got it to play something that resembled a song.  But we had big limitations when it came to timing and note lengths.  We were using a single frame counter to keep time across all 6 streams of the sound engine.  This is a problem because it imposes the music's speed on our sound effects.  If you were to use such a system in a real game, your sound effects would speed up or slow down whenever you change to a faster or slower song.

We also made the mistake of advancing the sound engine when our frame counter hit its mark, but skipping it when it didn't.  What happens if a game event triggers a sound effect one or two frames after the counter hits its mark?  The sound effect won't start until the next time our counter reaches its mark - we have to wait for it!  There will be a delay.  Not good.

Worst of all, our frame counter also doesn't allow for variable note lengths.  Unless every song you write is going to consist of only 32nd notes, this is a problem.  It becomes apparent then that we need a more complex timing system.

Tempo

We'll correct the first two problems by ripping out the universal counter and giving each stream it's own private counter.  We'll also change our method of counting.  Our old method of counting frames and taking action when we reach a certain number is very limited.  For example, let's say that we have a song and our frame counter is taking action every 4 frames.  Maybe the song sounds a tad faster than we want, so we slow it down by changing the speed to update once every 5 frames.  But now the song sounds too slow.  The speed we really want is somewhere in between 4 and 5, but we can't get there with our frame counting method.  Instead we'll use a ticker.

Ticker
The ticker method involves taking a number (a tempo) and adding it to a total, frame by frame.  Eventually, that total will wraparound from FF->00 and when it does the carry flag will be set (a tick).  This carry flag tick will be the signal we look for to advance our stream.

For example, let's say our tempo value is $40 and our total starts at $00.  After one frame we will add our tempo to the total.  $00 + $40 = $40.  Now our total is $40.  Another frame goes by (2).  We add our tempo to the total again.  $40 + $40 = $80.  Our total is $80.  Another frame goes by (3).  $80 + $40 = $C0.  Another frame goes by (4).  $C0 + $40 = $00.  Carry flag is set.  TICK!  A tick tells us that it is time to advance this stream.  When we finish updating, we start adding again until we get another tick.

As you can see, a tempo value of $40 will advance our stream once every 4 frames.  If you do some math (256 / 5), you will discover that a tempo of $33 will advance the stream roughly every 5 frames.  If $40 is too fast for your song and $33 is too slow, you still have the values $34-$39 to experiment with.  Much more versatile!  To see why this works, let's see what happens with a tempo value of say $36:

$00 + $36 + $36 + $36 + $36 + $36 = $0E (Tick in 5 frames)
$0E + $36 + $36 + $36 + $36 + $36 = $1C (Tick in 5 frames)
$1C + $36 + $36 + $36 + $36       = $02 (Tick in 4 frames)
$02 + $36 + $36 + $36 + $36 + $26 = $10 (Tick in 5 frames)

A tempo of $36 produces a tick every 5 frames most of the time, but sometimes it only takes 4 frames.  You might think that this disparity would make our song sound uneven, but really a single frame only lasts about 1/60 of a second.  Our ears won't notice.  It will sound just right to us.

Here is some code that demonstrates how to implement a ticker:

stream_tempo .rs 6          ;the value to add to our ticker total each frame
stream_ticker_total .rs 6   ;our running ticker total.

sound_play_frame:
    lda sound_disable_flag
    bne .done   ;if disable flag is set, don't advance a frame
 
    ldx #$00
.loop:
    lda stream_status, x
    and #$01
    beq .endloop    ;if stream disabled, skip this stream
 
    ;add the tempo to the ticker total.  If there is a FF-> 0 transition, there is a tick
    lda stream_ticker_total, x
    clc
    adc stream_tempo, x
    sta stream_ticker_total, x
    bcc .endloop    ;carry clear = no tick. if no tick, we are done with this stream
 
    jsr se_fetch_byte   ;else there is a tick, so do stuff
    ;do more stuff
.endloop:
    inx
    cpx #$06
    bne .loop
.done:
    rts
    
Initializing
Anytime we add a new feature to our sound engine we will want to ask ourselves the following questions:

1) Is this a feature that needs to be initialized for each song/sfx?
2) If so, are the values we use to initialize the feature variable (ie, not necessarily the same for every song/sfx)?

If the answer to question #1 is yes, we will have to update sound_load to initialize the feature.
If the answer to question #2 is also yes, we will have to add a field to the song header format.  The values to plug into the initialization are different for each song, so the songs' headers will need to provide those values for us.

In the case of our new timing scheme, we have two variables that need to be initialized: sound_ticker_total and sound_tempo.  Of the two, only sound_tempo will be variable.  Different songs will have different tempos, but they won't need to have different starting sound_ticker_totals.  So we will have to add one new field to our song header format for tempo:

main header:
--------+----------------
byte #  | what it tells us
--------+----------------
00      | number of streams
01+     | stream headers (one for each stream)

stream headers:
--------+----------------
byte #  | what it tells us
--------+----------------
00      | which stream (stream number)
01      | status byte
02      | which channel
03      | initial volume (and duty for squares)
04-05   | pointer to data stream
06      | initial tempo

Then we will need to edit sound_load to read this new byte for each stream and store it in RAM.  We'll also want to initialize stream_ticker_total to some fixed starting value, preferably a high one so that the first tick will happen without a delay.  Finally, we will have to update all of our songs to include tempos in their headers.

Note Lengths

We still have the problem of note lengths.  Songs are made up of notes of variable length: quarter notes, eighth notes, sixteenth notes, etc.  Our sound engine needs to be able to differentiate between different note lengths.  But how?  We will use note length counters.

Note Length Counters
Think of the fastest note you'd ever need to play, say a 32nd note.  Since that will be our fastest note, we'll give it the smallest count possible: $01.  The next fastest note is a 16th note.  In music, a 16th note equals two 32nd notes.  In other words, a 16th note lasts twice as long as a 32nd note.  So we will give it a count value that is twice the count value of our 32nd note: $02.  The next fastest note is an 8th note.  An 8th note equals two 16th notes.  It is twice as long as a 16th note.  So its count value will be twice that of the 16th note: $04.  Going all the way up to a whole note, we can produce a lookup table like this:

note_length_table:
    .byte $01   ;32nd note
    .byte $02   ;16th note
    .byte $04   ;8th note
    .byte $08   ;quarter note
    .byte $10   ;half note
    .byte $20   ;whole note
    
We'll add more entries later for things like dotted quarter notes, but for now this is sufficient to get us started.

To play different note lengths, we will give each stream a note length counter:

stream_note_length_counter .rs 6

When a note is played, for example an 8th note, its count value will be pulled from the note_length_table and stored in the stream's note length counter.  Then every time a tick occurs we will decrement the counter.  When the note length counter reaches 0, it will signal to us that our note has finished playing and it is time for the next note.  To say it another way, a note's count value is simply how many ticks it lasts.  An eighth note is 4 ticks long.  A quarter note is 8 ticks long.  A half note is 16 ticks long ($10).

Note Lengths in Data
Now we need to add note lengths to our sound data.  Recall that we specified that byte values in the range of $80-$9F were note lengths:

se_fetch_byte:
    lda stream_ptr_LO, x
    sta sound_ptr
    lda stream_ptr_HI, x
    sta sound_ptr+1
 
    ldy #$00
    lda [sound_ptr], y
    bpl .note                ;if < #$80, it's a Note
    cmp #$A0
    bcc .note_length         ;else if < #$A0, it's a Note Length
.opcode:                     ;else it's an opcode
    ;do Opcode stuff
.note_length:
    ;do note length stuff
.note:
    ;do note stuff
    
So the first byte value that we can use for note lengths is $80.  We are going to be reading from a lookup table (note_length_table above), so we should assign the bytes in the same order as the lookup table.

-----+--------------
byte | note length
-----+--------------
$80  | 32nd note
$81  | 16th note
$82  | 8th note
$83  | quarter note
$84  | half note
$85  | whole note

Now we can use these values in our sound data to represent note lengths:

;music data for song 0, square 1 channel
song0_sq1:
    .byte $82, C3 ;play a C eighth note
    .byte $84, D5 ;play a D half note
    
Of course, memorizing which byte value corresponds to which note length is a pain.  Let's create some aliases to make it easier on us when we are creating our sound data:

;note length constants
thirtysecond = $80
sixteenth = $81
eighth = $82
quarter = $83
half = $84
whole = $85

song0_sq1:
    .byte eighth, C3    ;play a C eighth note
    .byte half, D5      ;play a D half note
    
Pulling from the table
There is a small problem here.  Lookup tables index from 0.   This wasn't a problem for note values (C5, D3, G6) because our note range started from 0 ($00-$7f).  But our note length data has a range of $80-$9F.  Somehow we will need to translate the note length byte that comes from the data stream into a number we can use to index into our table.  In other words, we need to figure out a way to turn $80 into $00, $81 into $01, $82 into $02, etc.  Anything come to mind?

If you thought "just subtract $80 from the note length value", give yourself a cookie.  If you thought "just chop off the 7-bit", give yourself two cookies.  Both solutions work, but the second solution is a little bit faster and only takes one instruction to perform:

se_fetch_byte:
    lda stream_ptr_LO, x
    sta sound_ptr
    lda stream_ptr_HI, x
    sta sound_ptr+1
 
    ldy #$00
.fetch:
    lda [sound_ptr], y
    bpl .note                ;if < #$80, it's a Note
    cmp #$A0
    bcc .note_length         ;else if < #$A0, it's a Note Length
.opcode:                     ;else it's an opcode
    ;do Opcode stuff
.note_length:
    ;do note length stuff
    and #%01111111          ;chop off bit7
    sty sound_temp1         ;save Y because we are about to destroy it
    tay
    lda note_length_table, y    ;get the note length count value
    sta stream_note_length_counter, x   ;stick it in our note length counter
    ldy sound_temp1         ;restore Y
    iny                     ;set index to next byte in the stream
    jmp .fetch              ;fetch another byte
.note:
    ;do note stuff
    
Notice that we jump back up to .fetch after we set the note length counter.  This is so that we can read the note that will surely follow the note length in the data stream.  If we simply stop after setting the note length, we'll know how long to play, but we won't know which note to play!

Here's an updated sound_play_frame routine that implements both the ticker and the note length counters.  Notice how the note length counter is only decremented when we have a tick, and we only advance the stream when the note length counter reaches zero:

sound_play_frame:
    lda sound_disable_flag
    bne .done   ;if disable flag is set, don't advance a frame
 
    ldx #$00
.loop:
    lda stream_status, x
    and #$01
    beq .endloop    ;if stream disabled, skip this stream
 
    ;add the tempo to the ticker total.  If there is a FF-> 0 transition, there is a tick
    lda stream_ticker_total, x
    clc
    adc stream_tempo, x
    sta stream_ticker_total, x
    bcc .endloop    ;carry clear = no tick.  if no tick, we are done with this stream
 
    dec stream_note_length_counter, x   ;else there is a tick. decrement the note length counter
    bne .endloop    ;if counter is non-zero, our note isn't finished playing yet
 
    jsr se_fetch_byte   ;else our note is finished.  Time to read from the data stream
    ;do more stuff. set volume, note, sweep, etc
.endloop:
    inx
    cpx #$06
    bne .loop
.done:
    rts

We have one last change to make.  When we load a new song we will want it to start playing immediately, so we should initialize the stream_note_length_counter in the sound_load routine to do just that.  Our sound_play_frame routine decrements the counter and takes action if the result is zero.  Therefore, to ensure that our song starts immediately, we should initialize our stream_note_length_counter to $01:
    
    ;somewhere inside the loop of sound_load
    lda #$01
    sta stream_note_length_counter, x
    
And now our engine supports note lengths.  But there is still room for improvement.  What if we want to play a series of 8th notes?  Not an uncommon thing to have in music.  Here is how our data would have to look now:

sound_data:
    .byte eighth, C5, eighth, E5, eighth, G5, eighth, C6, eighth, E6, eighth, G6, eighth, C7 ;Cmajor
    
That's a lot of "eighth" bytes.  Wouldn't it be better to just state "eighth" once, and assume that all notes following it are eighth notes?  Like this:

sound_data:
    .byte eighth, C5, E5, G5, C6, E6, G6, C7 ;Cmajor
    
That saved us 6 bytes of ROM space.  And if you consider that a game may have 20+ songs, each with 4 streams of data, each with potentially several strings of equal-length notes, this kind of change might save us hundreds, maybe even thousands of bytes!  Let's do it.

To pull this off, we will have to store the current note length count value in RAM.  Then when our note length counter runs to 0, we will refill it with our RAM count value.

stream_note_length .rs 6    ;note length count value

;-------

se_fetch_byte:
    lda stream_ptr_LO, x
    sta sound_ptr
    lda stream_ptr_HI, x
    sta sound_ptr+1
 
    ldy #$00
.fetch:
    lda [sound_ptr], y
    bpl .note                ;if < #$80, it's a Note
    cmp #$A0
    bcc .note_length         ;else if < #$A0, it's a Note Length
.opcode:                     ;else it's an opcode
    ;do Opcode stuff
.note_length:
    ;do note length stuff
    and #%01111111          ;chop off bit7
    sty sound_temp1         ;save Y because we are about to destroy it
    tay
    lda note_length_table, y    ;get the note length count value
    sta stream_note_length, x   ;save the note length in RAM so we can use it to refill the counter
    sta stream_note_length_counter, x   ;stick it in our note length counter
    ldy sound_temp1         ;restore Y
    iny                     ;set index to next byte in the stream
    jmp .fetch              ;fetch another byte
.note:
    ;do note stuff
 
;--------

sound_play_frame:
    lda sound_disable_flag
    bne .done   ;if disable flag is set, don't advance a frame
 
    ldx #$00
.loop:
    lda stream_status, x
    and #$01
    beq .endloop    ;if stream disabled, skip this stream
 
    ;add the tempo to the ticker total.  If there is a FF-> 0 transition, there is a tick
    lda stream_ticker_total, x
    clc
    adc stream_tempo, x
    sta stream_ticker_total, x
    bcc .endloop    ;carry clear = no tick.  if no tick, we are done with this stream
 
    dec stream_note_length_counter, x   ;else there is a tick. decrement the note length counter
    bne .endloop    ;if counter is non-zero, our note isn't finished playing yet
    lda stream_note_length, x   ;else our note is finished. reload the note length counter
    sta stream_note_length_counter, x
 
    jsr se_fetch_byte   ;Time to read from the data stream
    ;do more stuff
.endloop:
    inx
    cpx #$06
    bne .loop
.done:
    rts
    
Adding those 4 lines of code just saved us hundreds of bytes of ROM space.  A nice tradeoff for 6 bytes of RAM.  Now our data will be made up of "strings", where we have a note length followed by a series of notes:

sound_data:
    .byte eighth, C5, E5, G5, C6, E6, G6, quarter, C6 ;six 8th notes and a quarter note
    
Easy to read and easy to write.

Other Note Lengths
Now that everything is setup, we can add more note lengths to our note_length_table.  Dotted notes are very common in music.  Dotted notes are equal in length to the note plus the next fastest note.  For example, a dotted quarter note = a quarter note + an 8th note.  A dotted 8th note = an 8th note + a 16th note.  Let's add some dotted notes to our table:

note_length_table:
    .byte $01   ;32nd note
    .byte $02   ;16th note
    .byte $04   ;8th note
    .byte $08   ;quarter note
    .byte $10   ;half note
    .byte $20   ;whole note
              ;---dotted notes
    .byte $03   ;dotted 16th note
    .byte $06   ;dotted 8th note
    .byte $0C   ;dotted quarter note
    .byte $18   ;dotted half note
    .byte $30   ;dotted whole note?
    
The actual order of our note_length_table doesn't matter.  We just have to make sure our aliases are in the same order as the table:

;note length constants (aliases)
thirtysecond = $80
sixteenth = $81
eighth = $82
quarter = $83
half = $84
whole = $85
d_sixteenth = $86
d_eighth = $87
d_quarter = $88
d_half = $89
d_whole = $8A   ;don't forget we are counting in hex

Your music will determine what other entries you'll need to add to your note length table.  If one of your songs has a really really long note, like 3 whole notes tied together, add it to the table ($60) and make an alias for it (whole_x3).  If your song contains a note that is seven 8th notes long (a half note plus a dotted quarter note tied together), add it to the table ($1C) and make an alias for it (seven_eighths).

Buffering APU Writes
Before, we've been writing to the APU one stream at a time.  If two different streams shared a channel, they would both write to the same APU ports.  If three streams were to share a channel, which is possible if there are two different sound effects loaded into SFX_1 and SFX_2, all three would write to the same APU ports in the same frame.  This is bad practice.  It can also cause some unwanted noise on the square channels.

A better method is to buffer our writes.  Instead of writing to the APU ports directly, each stream will instead write its data to temporary ports in RAM.  We'll keep our loop order, so sfx streams will still overwrite the music streams.  Then when all the streams are done, we will copy the contents of our temporary RAM ports directly to the APU ports all at once.  This ensures that the APU ports only get written to once per frame max.  To do this, we first need to reserve some RAM space for our temporary port variables:

soft_apu_ports .rs 16

We reserved 16 bytes for our temporary ports.  Each one corresponds to an APU port:

soft_apu_ports+0  -> $4000      ;Square 1 ports
soft_apu_ports+1  -> $4001
soft_apu_ports+2  -> $4002
soft_apu_ports+3  -> $4003

soft_apu_ports+4  -> $4004      ;Square 2 ports
soft_apu_ports+5  -> $4005
soft_apu_ports+6  -> $4006
soft_apu_ports+7  -> $4007

soft_apu_ports+8  -> $4008      ;Triangle ports
soft_apu_ports+9  -> $4009 (unused)
soft_apu_ports+10 -> $400A
soft_apu_ports+11 -> $400B

soft_apu_ports+12 -> $400C      ;Noise ports
soft_apu_ports+13 -> $400D (unused)
soft_apu_ports+14 -> $400E
soft_apu_ports+15 -> $400F

Let's implement this by working backwards.  First we will edit sound_play_frame and pull our call to se_set_apu out of the loop.  We do this because we only want to write to the APU once, after all the streams are done looping:

;--------------------------
; sound_play_frame advances the sound engine by one frame
sound_play_frame:
    lda sound_disable_flag
    bne .done   ;if disable flag is set, don't advance a frame

    ldx #$00
.loop:
    lda stream_status, x
    and #$01    ;check whether the stream is active
    beq .endloop  ;if the channel isn't active, skip it
 
    ;add the tempo to the ticker total.  If there is a FF-> 0 transition, there is a tick
    lda stream_ticker_total, x
    clc
    adc stream_tempo, x
    sta stream_ticker_total, x
    bcc .endloop    ;carry clear = no tick.  if no tick, we are done with this stream
 
    dec stream_note_length_counter, x   ;else there is a tick. decrement the note length counter
    bne .endloop    ;if counter is non-zero, our note isn't finished playing yet
    lda stream_note_length, x   ;else our note is finished. reload the note length counter
    sta stream_note_length_counter, x
 
    jsr se_fetch_byte
    ;snip
 
.endloop:
    inx
    cpx #$06
    bne .loop
 
    jsr se_set_apu
.done:
    rts
    
Next we will modify se_set_apu to copy the temporary APU ports to the real APU ports:

se_set_apu:
    ldy #$0F
.loop:
    cpy #$09
    beq .skip   ;$4009 is unused
    cpy #$0D
    beq .skip   ;$400D is unused
 
    lda soft_apu_ports, y
    sta $4000, y
.skip:
    dey
    bpl .loop   ;stop the loop when Y is goes from $00 -> $FF
 
    rts
    
Now we have to write the subroutine that will populate the temporary APU ports with a stream's data.  This part will get more complicated as we add more features to our sound engine, but for now it's quite simple:

se_set_temp_ports:
    lda stream_channel, x
    asl a
    asl a
    tay
 
    lda stream_vol_duty, x
    sta soft_apu_ports, y       ;vol
 
    lda #$08
    sta soft_apu_ports+1, y     ;sweep
 
    lda stream_note_LO, x
    sta soft_apu_ports+2, y     ;period LO
 
    lda stream_note_HI, x
    sta soft_apu_ports+3, y     ;period HI
    rts
    
We will make the call to se_set_temp_ports after our call to se_fetch_byte, where the old se_set_apu call was before we snipped it out of the loop.  Notice that we don't bother to check the channel before writing the sweep.  se_set_apu takes care of this part for us.  There's no harm in writing these values to RAM, so we'll avoid branching here to simplify the code.

Crackling Sounds
Writing to the 4th port of the Square channels ($4003/$4007) has the side effect of resetting the sequencer.  If we write here too often, we will get a nasty crackling sound out of our Squares.  This is not good.

The way our engine is setup now, we call se_set_apu once per frame.  se_set_apu writes to $4003/$4007, so these ports will get written to once per frame.  This is too often.  We need to find a way to write here less often.  We will do this by cutting out redundant writes.  If the value we want to write this frame is the same as the value written last frame, skip the write.

First we will need to keep track of what was last written to the ports.  This will require some new variables:

sound_sq1_old .rs 1  ;the last value written to $4003
sound_sq2_old .rs 1  ;the last value written to $4007

Whenever we write to one of these ports, we will also write the value to the corresponding sound_port4_old variable.  Saving this value will allow us to compare against it next frame.  To implement this, we will have to unroll our loop in se_set_apu:

se_set_apu:
.square1:
    lda soft_apu_ports+0
    sta $4000
    lda soft_apu_ports+1
    sta $4001
    lda soft_apu_ports+2
    sta $4002
    lda soft_apu_ports+3
    sta $4003
    sta sound_sq1_old       ;save the value we just wrote to $4003
.square2:
    lda soft_apu_ports+4
    sta $4004
    lda soft_apu_ports+5
    sta $4005
    lda soft_apu_ports+6
    sta $4006
    lda soft_apu_ports+7
    sta $4007
    sta sound_sq2_old       ;save the value we just wrote to $4007
.triangle:
    lda soft_apu_ports+8
    sta $4008
    lda soft_apu_ports+10
    sta $400A
    lda soft_apu_ports+11
    sta $400B
.noise:
    lda soft_apu_ports+12
    sta $400C
    lda soft_apu_ports+14
    sta $400E
    lda soft_apu_ports+15
    sta $400F
    rts
    
Now we have a variable that will keep track of the last value written to a channel's 4th port.  The next step is to add a check before we write:

se_set_apu:
.square1:
    lda soft_apu_ports+0
    sta $4000
    lda soft_apu_ports+1
    sta $4001
    lda soft_apu_ports+2
    sta $4002
    lda soft_apu_ports+3
    cmp sound_sq1_old       ;compare to last write
    beq .square2            ;don't write this frame if they were equal
    sta $4003
    sta sound_sq1_old       ;save the value we just wrote to $4003
.square2:
    lda soft_apu_ports+4
    sta $4004
    lda soft_apu_ports+5
    sta $4005
    lda soft_apu_ports+6
    sta $4006
    lda soft_apu_ports+7
    cmp sound_sq2_old
    beq .triangle
    sta $4007
    sta sound_sq2_old       ;save the value we just wrote to $4007
.triangle:
    lda soft_apu_ports+8
    sta $4008
    lda soft_apu_ports+10   ;there is no $4009, so we skip it
    sta $400A
    lda soft_apu_ports+11
    sta $400B
.noise:
    lda soft_apu_ports+12
    sta $400C
    lda soft_apu_ports+14   ;there is no $400D, so we skip it
    sta $400E
    lda soft_apu_ports+15
    sta $400F
    rts
    
Finally we have to consider initialization.  The only case we really have to worry about is the first time a song is played in the game.  Consider what happens if we initialize the sound_sq1_old and sound_sq2_old variables to $00.  We are essentially saying that on startup (RESET) the last byte written to $4003/$4007 was a $00, which isn't true of course.  On startup, no write has ever been made to these ports.  If we initialize to $00, and if the first note of the first song played has a $00 for the high 3 bits of its period, it will get skipped.  That is not what we want.  Instead, we should initialize these variables to some value that will never be written to $4003/$4007, like $FF.  This ensures that the first note(s) played in the game won't be skipped.

sound_init:
    lda #$0F
    sta $4015   ;enable Square 1, Square 2, Triangle and Noise channels
 
    lda #$00
    sta sound_disable_flag  ;clear disable flag
    ;later, if we have other variables we want to initialize, we will do that here.
    lda #$FF
    sta sound_sq1_old
    sta sound_sq2_old
se_silence:
    lda #$30
    sta soft_apu_ports      ;set Square 1 volume to 0
    sta soft_apu_ports+4    ;set Square 2 volume to 0
    sta soft_apu_ports+12   ;set Noise volume to 0
    lda #$80
    sta soft_apu_ports+8     ;silence Triangle
 
    rts
    
Rests

The final topic we will cover this lesson is rests.  A rest is a period of silence in between notes.  Like notes, rests can be of variable length: quarter rest, half rest, whole rest, etc.  In other words a rest is a silent note.

So how will we implement it?  We will handle rests by considering a rest to be special case note.  We will give the rest a dummy period in our note table.  Then, when we fetch a byte from the data stream and determine the byte to be a note, we will add an extra check to see if that note is a rest.  If it is, we will make sure that it shuts up the stream.

First let's add the rest to our note table.  We will give it a dummy period.  It doesn't really matter what value we use.  I'm going to give it a period of $0000.  We will also want to add the rest to our list of note aliases:

note_table:
    .word $07F1, $0780, etc...
    ;....more note table values here
    .word $0000 ;rest.  Last entry
 
;Note: octaves in music traditionally start at C, not A    
A1 = $00    ;the "1" means Octave 1
As1 = $01   ;the "s" means "sharp"
Bb1 = $01   ;the "b" means "flat"  A# == Bb, so same value
B1 = $02
;..... other aliases here
F9 = $5c
Fs9 = $5d
Gb9 = $5d
rest = $5e

Now we can use the symbol "rest" in our music data.  "rest" will evaluate to the value $5E, which falls within our note range ($00-$7F).  When our sound engine encounters a $5E in the data stream, it will pull the period ($0000) from the note table and store it in RAM.  A period of $0000 is actually low enough to silence the square channels, but the triangle channel is still audible at this period so we have more work to do.

Checking for a rest
When we encounter a rest, we will want to tell the sound engine to shut this stream up until the next note.  The rest functions differently from all the other notes, so we will need to make a special check for it in our code.  We will make a subroutine se_check_rest to do this for us:

se_fetch_byte:
    lda stream_ptr_LO, x
    sta sound_ptr
    lda stream_ptr_HI, x
    sta sound_ptr+1
 
    ldy #$00
.fetch:
    lda [sound_ptr], y
    bpl .note                ;if < #$80, it's a Note
    cmp #$A0
    bcc .note_length         ;else if < #$A0, it's a Note Length
.opcode:                     ;else it's an opcode
    ;do Opcode stuff
.note_length:
    ;do Note Length stuff
.note:
    ;do Note stuff
    sty sound_temp1     ;save our index into the data stream
    asl a
    tay
    lda note_table, y
    sta stream_note_LO, x
    lda note_table+1, y
    sta stream_note_HI, x
    ldy sound_temp1     ;restore data stream index

    ;check if it's a rest
    jsr se_check_rest    
.update_pointer:
    iny
    tya
    clc
    adc stream_ptr_LO, x
    sta stream_ptr_LO, x
    bcc .end
    inc stream_ptr_HI, x
.end:
    rts
    
se_check_rest will check to see if the note value is equal to $5E or not.  If it is, we will need to tell the sound engine to silence the stream.  If the note isn't equal to $5E, we can go on our merry way.

How will we silence our stream then?  This is actually a little complicated.  Recall that the stream's volume (stream_vol_duty) is set in the song's header.   se_set_temp_ports copies the value of stream_vol_duty to soft_apu_ports.  If we have se_check_rest modify the stream_vol_duty variable directly (set it to 0 volume), the old volume value disappears.  We won't know what to restore it to when we are done with our rest.  Oh no!

What we will want to do instead is leave stream_vol_duty alone.  We will copy it into soft_apu_ports every frame as usual.  Then, after the copy we will check to see if we are currently resting.  If we are, we will make another write soft_apu_ports with a value that will set the volume to 0.  Make sense?

stream_status
To do this we will need to keep track of our resting status in a variable.  If our sound engine encounters a $5E in the data stream, we'll turn our resting status on.  If it's not, we'll turn our resting status off.  There are only two possibilities: on or off.  Rather than declare a whole new block of variables and waste six bytes of RAM, let's assign one of the bits in our stream_status variable to be our rest indicator:

Stream Status Byte
76543210
      ||
      |+- Enabled (0: stream disabled; 1: enabled)
      +-- Rest (0: not resting; 1: resting)
      
Our new subroutine se_check_rest will be in charge of setting or clearing this bit of the status byte:

se_check_rest:
    lda [sound_ptr], y  ;read the note byte again
    cmp #rest           ;is it a rest? (==$5E)
    bne .not_rest
    lda stream_status, x
    ora #%00000010      ;if so, set the rest bit in the status byte
    bne .store          ;this will always branch.  bne is cheaper than a jmp.
.not_rest:
    lda stream_status, x
    and #%11111101      ;clear the rest bit in the status byte
.store:
    sta stream_status, x
    rts
    
Then we modify se_set_temp_ports to check the rest bit and silence the stream if it is set:

se_set_temp_ports:
    lda stream_channel, x
    asl a
    asl a
    tay
 
    lda stream_vol_duty, x
    sta soft_apu_ports, y       ;vol
 
    lda #$08
    sta soft_apu_ports+1, y     ;sweep
 
    lda stream_note_LO, x
    sta soft_apu_ports+2, y     ;period LO
 
    lda stream_note_HI, x
    sta soft_apu_ports+3, y     ;period HI
 
    ;check the rest flag. if set, overwrite volume with silence value
    lda stream_status, x
    and #%00000010
    beq .done       ;if clear, no rest, so quit
    lda stream_channel, x
    cmp #TRIANGLE   ;if triangle, silence with #$80
    beq .tri        
    lda #$30        ;else, silence with #$30
    bne .store      ;this will always branch.  bne is cheaper than a jmp.
.tri:
    lda #$80
.store:    
    sta soft_apu_ports, y
.done:
    rts
    
That's it.  Now our engine supports rests!  They work just like notes, so their lengths are controlled with note lengths:

song_data:  ;this data has two quarter rests in it.
    .byte half, C2, quarter, rest, eighth, D4, C4, quarter, B3, rest
    
Putting It All Together
Download and unzip the tempo.zip sample files.  Make sure the following files are in the same folder as NESASM3:

    tempo.asm
    sound_engine.asm
    tempo.chr
    note_table.i
    note_length_table.i
    song0.i
    song1.i
    song2.i
    song3.i
    song4.i
    song5.i
    tempo.bat

Double click tempo.bat. That will run NESASM3 and should produce the tempo.nes file. Run that NES file in FCEUXD SP.

Use the controller to select songs and play them.  Controls are as follows:
    
Up: Play
Down: Stop
Right: Next Song/SFX
Left: Previous Song/SFX

Song0 is a silence song.  Not selectable.  tempo.asm "plays" song0 to stop the music when you press down.  See song0.i to find out how it works.
Song1 is last week's evil sounding series of minor thirds, but much faster now thanks to tempo settings.
Song2 is the same short sound effect from last week.
Song3 is a simple descending chord progression.  We saved some bytes in the triangle data using note lengths (compare to last week's file)
Song4 is a new song that showcases variable note lengths and rests.
Song5 is a short sound effect.  It plays 10 notes extremely fast.  Play it over songs and see how it steals the SQ2 channel from the music.

Try creating your own songs and sound effects and add them into the mix.  To add a new song you will need to take the following steps:

1) create a song header and song data (use the included songs as reference).  Don't forget to add tempos for each stream in your header.  Data streams are terminated with $FF.
2) add your header to the song_headers pointer table at the bottom of sound_engine.asm
3) update the constant NUM_SONGS to reflect the new song number total (also at the bottom of sound_engine.asm)

Although not necessary, I recommend keeping your song data in a separate file like I've done with song0.i, song1.i, song2.i and song3.i.  This makes it easier to find the data if you need to edit your song later.  If you do this, don't forget to .include your file.

Next Week: Volume Envelopes

Last Week: Tempo, Note Lengths, Buffering and Rests

This Week: Volume Envelopes

Volume Envelopes

This week we will add volume envelopes to our engine.  A volume envelope is a series of volume values that are applied to a note one frame at a time.  For example, if we had a volume envelope that looked like this:

F E D C 9 5 0

Then whenever we played a note, it would have a volume of F on the first frame, a volume of E on the second frame, then D, then C, then 9, then 5 until it is finally silenced with a volume of 0 on the 7th frame.  Applying this volume envelope on our notes would give them a sharp, short staccato feel.  Conversely, if we had a volume envelope that looked like this:

1 1 2 2 3 3 4 4 7 7 8 8 A A C C D D E E F F F

Each note would start very quietly and fade in to full volume.  Look at this volume envelope:

D D D C B 0 0 0 0 0 0 0 0 6 6 6 5 4 0

Here we start at a high volume (D) and let it ring for 5 frames.  Then we silence the note for 8 frames.  Then the note comes back at a very low volume for 5 frames.  Notes using this volume envelope would sound like they had an faint echo.

As you can see, volume envelopes are pretty cool.  We can get a lot of different sounds out of them.  Let's add them in.

Channels
Volume envelopes are best suited for the square and noise channels where we have full control of the volume.  The triangle channel on the other hand doesn't allow much volume control.  It only has two settings: full blast and off.  We can still apply volume envelopes in a limited way though.  Consider these two volume envelopes:

0F 0E 0D 0C 09 05 00

04 04 05 05 06 06 07 07 08 08 09 09 0A 0A 00

These two envelopes would have a vastly different sound on the square channels, but to the triangle they look like this:

On On On On On On Off
On On On On On On On On On On On On On On Off

You don't get the subtle shifts in volume, but you do get a different length.  We can use volume envelopes that end in 00 to control when the triangle key-off occurs.  Not as cool as full volume control, but still useful.

Defining volume envelopes
First let's define some volume envelopes so we have some data to work with.  We'll use some of the examples from above:

se_ve_1:
    .byte $0F, $0E, $0D, $0C, $09, $05, $00
    .byte $FF
se_ve_2:
    .byte $01, $01, $02, $02, $03, $03, $04, $04, $07, $07
    .byte $08, $08, $0A, $0A, $0C, $0C, $0D, $0D, $0E, $0E
    .byte $0F, $0F
    .byte $FF
se_ve_3:
    .byte $0D, $0D, $0D, $0C, $0B, $00, $00, $00, $00, $00
    .byte $00, $00, $00, $00, $06, $06, $06, $05, $04, $00
    .byte $FF

Notice that I terminated each envelope with $FF.  We need some terminator value so the engine will know when we've reached the end of the envelope.  We could have used any value, but $FF is pretty common.

Next we will make a pointer table that holds the addresses of our volume envelopes:

volume_envelopes:
    .word se_ve_1, se_ve_2, se_ve_3
    
Declaring variables
In order to apply a volume envelope to a particular stream, we will need a variable that tells us which one to use.  We will also need an index variable that tells us our current position within the volume envelope:

stream_ve .rs 6         ;current volume envelope
stream_ve_index .rs 6   ;current position within the volume envelope

stream_ve will tell us which volume envelope to use.  Code-wise, it will act as an index into our pointer table so we know where to read from.  Sound familiar?  It works the same way as "song number" did for loading a song.  We aren't there yet, but here's a peek at how we will use these variables to read from the volume envelopes. (x holds the stream number):

    sty sound_temp1             ;save y because we are about to destroy it.

    lda stream_ve, x            ;which volume envelope?
    asl a                       ;multiply by 2 because we are indexing into a table of addresses (words)
    tay
    lda volume_envelopes, y     ;get the low byte of the address from the pointer table
    sta sound_ptr
    lda volume_envelopes+1, y   ;get the high byte of the address
    sta sound_ptr+1
 
    ldy stream_ve_index, x      ;our current position within the volume envelope.
    lda [sound_ptr], y          ;grab the value.
    ;check against $FF (our termination value)
    ;set the volume
    ;increment stream_ve_index
    ;etc
    
Compare this code to the beginning of the sound_load routine.  Are you starting to see a pattern?
    
Initializing
Whenever we add a new feature, we need to consider how we should initialize it.  Every stream in our music data will potentially have a different volume envelope, so we should add a volume envelope field to our header.  Volume envelopes will deprecate our old "initial volume" field, but we will still need to have duty cycle info, so we'll just rename that field:

main header:
--------+----------------
byte #  | what it tells us
--------+----------------
00      | number of streams
01+     | stream headers (one for each stream)

stream headers:
--------+----------------
byte #  | what it tells us
--------+----------------
00      | which stream (stream number)
01      | status byte
02      | which channel
03      | initial duty (for triangle, set the 7bit)
04      | volume envelope
05-06   | pointer to data stream
07      | initial tempo

To read this data from the header, we will have to insert the following code into our sound_load routine (after reading the duty):

    lda [sound_ptr], y      ;the stream's volume envelope
    sta stream_ve, x
    iny
    
Notes will always start from the beginning of the volume envelope, so we can just initialize stream_ve_index to 0:

    lda #$00
    sta stream_ve_index, x
    
Now we just need to make sure to assign volume envelopes to all the streams in our song data and we're ready to go:

song5_header:
    .byte $01           ;1 stream
 
    .byte SFX_1         ;which stream
    .byte $01           ;status byte (stream enabled)
    .byte SQUARE_2      ;which channel
    .byte $70           ;initial duty (01).  Initial volume deprecated.
    .byte $00           ;the first volume envelope (se_ve_1)
    .word song5_square2 ;pointer to stream
    .byte $FF           ;tempo..very fast tempo

Remember that you can always create descriptive aliases for your volume envelopes if you don't want to remember which number is which:

;volume envelope aliases
ve_short_staccato = $00
ve_fade_in = $01
ve_blip_echo = $02

song5_header:
    .byte $01           ;1 stream
 
    .byte SFX_1         ;which stream
    .byte $01           ;status byte (stream enabled)
    .byte SQUARE_2      ;which channel
    .byte $7F           ;initial duty (01).  Initial volume deprecated.
    .byte ve_short_staccato   ;the first volume envelope (se_ve_1)
    .word song5_square2 ;pointer to stream
    .byte $FF           ;tempo..very fast tempo
    
Using aliases is a good idea because the assembler will give you an error if you mistype your alias.  If you mistype your number, and it is still a valid number, the assembler won't know there's a problem and will assemble it.  This kind of bug in your data can be hard to trace.


Implementing Volume Envelopes

To implement volume envelopes, we need to modify the code where we set the volume.  Instead of using a fixed value like we were doing before, we need to read from our current position in the volume envelope and use that value instead.  Our volume code is starting to get a little complicated, so let's pull it out into its own subroutine.  This will make our code easier to follow:

;----------------------------------------------------
; se_set_temp_ports will copy a stream's sound data to the temporary apu variables
;      input:
;           X: stream number
se_set_temp_ports:
    lda stream_channel, x
    asl a
    asl a
    tay
 
    jsr se_set_stream_volume    ;let's stick all of our volume code into a new subroutine
                                ;less cluttered that way
 
    lda #$08
    sta soft_apu_ports+1, y     ;sweep
 
    lda stream_note_LO, x
    sta soft_apu_ports+2, y     ;period LO
 
    lda stream_note_HI, x
    sta soft_apu_ports+3, y     ;period HI

    rts    

What should our new subroutine se_set_stream_volume do?  First it needs to read a value from our stream's volume envelope.  Then it needs to modify the stream's volume using that value.  Then we need to update our position within the volume envelope.  Finally it needs to check to see if we are resting, and silence the stream if we are (we wrote this code last week).  It looks something like this (new code in red):


se_set_stream_volume:
    sty sound_temp1             ;save our index into soft_apu_ports (we are about to destroy y)
 
    lda stream_ve, x            ;which volume envelope?
    asl a                       ;multiply by 2 because we are indexing into a table of addresses (words)
    tay
    lda volume_envelopes, y     ;get the low byte of the address from the pointer table
    sta sound_ptr               ;put it into our pointer variable
    lda volume_envelopes+1, y   ;get the high byte of the address
    sta sound_ptr+1
 
.read_ve:
    ldy stream_ve_index, x      ;our current position within the volume envelope.
    lda [sound_ptr], y          ;grab the value.
    cmp #$FF
    bne .set_vol                ;if not FF, set the volume
    dec stream_ve_index, x      ;else if FF, go back one and read again
    jmp .read_ve                ;  FF essentially tells us to repeat the last
                                ;  volume value for the remainder of the note
.set_vol:
    sta sound_temp2             ;save our new volume value (about to destroy A)
    lda stream_vol_duty, x      ;get current vol/duty settings
    and #$F0                    ;zero out the old volume
    ora sound_temp2             ;OR our new volume in.

    ldy sound_temp1             ;get our index into soft_apu_ports
    sta soft_apu_ports, y       ;store the volume in our temp port
    inc stream_ve_index, x      ;set our volume envelop index to the next position

.rest_check:
    ;check the rest flag. if set, overwrite volume with silence value
    lda stream_status, x
    and #%00000010
    beq .done                   ;if clear, no rest, so quit
    lda stream_channel, x
    cmp #TRIANGLE               ;if triangle, silence with #$80
    beq .tri                    ;else, silence with #$30
    lda #$30        
    bne .store                  ;this always branches.  bne is cheaper than a jmp
.tri:
    lda #$80
.store:    
    sta soft_apu_ports, y
.done:
    rts
    
After we read a value from our volume envelope, we AND stream_vol_duty with #$F0.  This has the nice effect of clearing the old volume while preserving our squares' duty cycle settings.  But we need to be careful here.  Recall that the triangle channel's on/off status is controlled by the low 7 bits of the port:

TRI_CTRL ($4008)

76543210
||||||||
|+++++++- Value
+-------- Control Flag (0: use internal counters; 1: disable internal counters)

If any of those Value bits are set, the triangle channel will be considered on.  Consider what happens if bit 4, 5 or 6 happen to be set.  In this case, ANDing with #$F0 won't turn the triangle channel off.  If the volume we pull from the volume envelope is 0, it won't silence our triangle channel because bit 4, 5 or 6 will still be set.  If we are careful not to set these bits in our song headers, the problem should never come up.  But for completeness we should fix it:

se_set_stream_volume:
    sty sound_temp1             ;save our index into soft_apu_ports (we are about to destroy y)
 
    lda stream_ve, x            ;which volume envelope?
    asl a                       ;multiply by 2 because we are indexing into a table of addresses (words)
    tay
    lda volume_envelopes, y     ;get the low byte of the address from the pointer table
    sta sound_ptr               ;put it into our pointer variable
    lda volume_envelopes+1, y   ;get the high byte of the address
    sta sound_ptr+1
 
.read_ve:
    ldy stream_ve_index, x      ;our current position within the volume envelope.
    lda [sound_ptr], y          ;grab the value.
    cmp #$FF
    bne .set_vol                ;if not FF, set the volume
    dec stream_ve_index, x      ;else if FF, go back one and read again
    jmp .read_ve                ;  FF essentially tells us to repeat the last
                                ;  volume value for the remainder of the note
.set_vol:
    sta sound_temp2             ;save our new volume value (about to destroy A)
 
    cpx #TRIANGLE               
    bne .squares                ;if not triangle channel, go ahead
    lda sound_temp2
    bne .squares                ;else if volume not zero, go ahead (treat same as squares)
    lda #$80
    bmi .store_vol              ;else silence the channel with #$80
.squares:
    lda stream_vol_duty, x      ;get current vol/duty settings
    and #$F0                    ;zero out the old volume
    ora sound_temp2             ;OR our new volume in.

.store_vol:
    ldy sound_temp1             ;get our index into soft_apu_ports
    sta soft_apu_ports, y       ;store the volume in our temp port
    inc stream_ve_index, x      ;set our volume envelop index to the next position

.rest_check:
    ;check the rest flag. if set, overwrite volume with silence value
    lda stream_status, x
    and #%00000010
    beq .done                   ;if clear, no rest, so quit
    lda stream_channel, x
    cmp #TRIANGLE               ;if triangle, silence with #$80
    beq .tri                    ;else, silence with #$30
    lda #$30        
    bne .store                  ;this always branches.  bne is cheaper than a jmp
.tri:
    lda #$80
.store:    
    sta soft_apu_ports, y
.done:
    rts
    
New notes
The last thing we need to consider is new notes.  When an old note finishes and we start playing a new note, we will want to reset the volume envelope back to the beginning.  This is as easy as setting stream_ve_index to 0 when we read a new note:

se_fetch_byte:
    ;...snip... (setup pointers, read byte, test range, etc)
.note:
    ;do Note stuff
    sty sound_temp1     ;save our index into the data stream
    asl a
    tay
    lda note_table, y
    sta stream_note_LO, x
    lda note_table+1, y
    sta stream_note_HI, x
    ldy sound_temp1     ;restore data stream index
 
    lda #$00
    sta stream_ve_index, x  ;reset the volume envelope.
 
    ;check if it's a rest and modify the status flag appropriately
    jsr se_check_rest    
 
    ;...snip... (update pointer)
    
And now we have volume envelopes.

Putting It All Together
Download and unzip the envelopes.zip sample files.  Make sure the following files are in the same folder as NESASM3:

    envelopes.asm
    sound_engine.asm
    envelopes.chr
    note_table.i
    note_length_table.i
    vol_envelopes.i
    song0.i
    song1.i
    song2.i
    song3.i
    song4.i
    song5.i
    envelopes.bat

Double click envelopes.bat. That will run NESASM3 and should produce the envelopes.nes file. Run that NES file in FCEUXD SP.

Use the controller to select songs and play them.  Controls are as follows:
    
Up: Play
Down: Stop
Right : Next Song/SFX
Left : Previous Song/SFX

Song0 is a silence song.  Not selectable.
Song1 is a boss song from The Guardian Legend, almost the same as the original.
Song2 is the same short sound effect from last week.
Song3 is a song from Dragon Warrior, very close to the original.
Song4 is the same song4 as last week, but volume envelopes allow us to save some bytes by reducing rests.
Song5 is a short sound effect, same as last week.

Try creating your own songs and sound effects and add them into the mix.  To add a new song you will need to take the following steps:

1) create a song header and song data (use the included songs as reference).  Don't forget to select a volume envelope for each stream in your header.  Data streams are terminated with $FF.
2) add your header to the song_headers pointer table at the bottom of sound_engine.asm
3) update the constant NUM_SONGS to reflect the new song number total (also at the bottom of sound_engine.asm)

Try making your own volume envelopes too.  To do so you will need to modify vol_envelopes.i.  Remember that volume envelopes are terminated with $FF.

Next Week: Opcodes, Looping

Last Week: Volume Envelopes

This Week: Opcodes and Looping

Opcodes

So far our sound engine handles two type of data that it reads from music data streams: notes and note lengths.  This is enough to write complex music but of course we are going to want more features.  We will want control over the sound of our notes.  What if we want to change duty cycles midstream?  Or volume envelopes?  Or keys?  What if we want to loop one part of the song four times?  Or loop the entire song continuously?  What if we want to play a sound effect as part of a song?

All of these types of features, features where you are issuing commands to the engine, are going to be done through opcodes (also called control codes or command codes).  An opcode is a value in the data stream that tells the engine to run a specific, specialized subroutine or piece of code.  Most opcodes will have arguments sent along with them.  For example, an opcode that changes a stream's volume envelope will come with an argument that specifies which volume envelope to change to.

We've actually been using an opcode for weeks, I just haven't mentioned it.  It's the opcode that ends a sound, and we've been encoding it in our data streams as $FF.  Here is the code we've been using:

se_fetch_byte:

    ;---snip--- (fetch a byte and range test)

.opcode:                     ;else it's an opcode
    ;do Opcode stuff
    cmp #$FF
    bne .end
    lda stream_status, x    ;if $FF, end of stream, so disable it and silence
    and #%11111110
    sta stream_status, x    ;clear enable flag in status byte
 
    lda stream_channel, x
    cmp #TRIANGLE
    beq .silence_tri        ;triangle is silenced differently from squares and noise
    lda #$30                ;squares and noise silenced with #$30
    bne .silence
.silence_tri:
    lda #$80                ;triangle silenced with #$80
.silence:
    sta stream_vol_duty, x  ;store silence value in the stream's volume variable.
    jmp .update_pointer     ;done
 
    ;---snip--- (do note lengths and notes, update the stream's pointer)
    rts
    
Here we check if the byte read has a value of $FF.  If so we turn the stream off and silence it.  That's an opcode.

It would be pretty messy if every opcode we had was just written straight out like this.  Normally we would pull this code into its own subroutine, like this:

se_fetch_byte:

    ;---snip--- (fetch a byte and range test)

.opcode:                    ;else it's an opcode
    ;do Opcode stuff
    cmp #$FF                ;end sound opcode
    bne .end
 jsr se_op_endsound      ;call the endsound subroutine
    iny
    jmp .fetch              ;grab the next byte in the stream.
 
    ;---snip--- (do note lengths and notes, update the stream's pointer)
    rts
 
se_op_endsound:
    lda stream_status, x    ;end of stream, so disable it and silence
    and #%11111110
    sta stream_status, x    ;clear enable flag in status byte
 
    lda stream_channel, x
    cmp #TRIANGLE
    beq .silence_tri        ;triangle is silenced differently from squares and noise
    lda #$30                ;squares and noise silenced with #$30
    bne .silence
.silence_tri:
    lda #$80                ;triangle silenced with #$80
.silence:
    sta stream_vol_duty, x  ;store silence value in the stream's volume variable.
    rts
    
The .opcode branch is much shorter now.  If we wanted to add more opcodes, we could just add some more compares:

.opcode:
    ;do Opcode stuff
    cmp #$FF            ;is it the end sound opcode?
    bne .not_FF
    jsr se_op_endsound  ;if so, call the end sound subroutine
    jmp .end            ;and finish
.not_FF:
    cmp #$FE            ;else is it the loop opcode?
    bne .not_FE
    jsr se_op_loop      ;if so, call the loop subroutine
    jmp .opcode_done
.not_FE:
    cmp #$FD            ;else is it the change volume envelope opcode?
    bne .not_FD
    jsr se_op_change_ve ;if so, call the change volume envelope subroutine
    jmp .opcode_done
.not_FD:
.opcode_done:
    iny                 ;update index to next byte in the data stream
    jmp .fetch          ;go fetch another byte
    

This will work, but it's ugly.  The more opcodes we add to our engine, the more checks we need to make.  What if we have 20 opcodes?  Do we really want to do that many compares?  It's a waste of ROM space and cycles.

Tables
Anytime you find yourself in a situation where you are doing a lot of CMPs on one value, the answer is to use a lookup table.  It will simplify everything!  We've done it already with notes, note lengths, song numbers and volume envelopes.  Could you imagine trying to get a note's period without using the lookup table?  It would look like this:

Is the note an A1?  If so, use this period, else
Is the note an A#1?  If so, use this period, else
Is the note a B1?  If so, use this period, else
Is the note a C2?  If so, use this period, else
... (about 100 more checks)
Is the note an F#9? If so, use this period, else
Is the note a rest?  If so, use this period

That's just crazy.  It would be hundreds of lines of unreadable code and you'd run into branch-range errors too.  When we use a lookup table, the code is simplified to this:

.note:
    ;do Note stuff
    sty sound_temp1     ;save our index
    asl a
    tay
    lda note_table, y
    sta stream_note_LO, x
    lda note_table+1, y
    sta stream_note_HI, x
    ldy sound_temp1     ;restore data stream index
    
Much cleaner.  Again, I can't stress it enough: if you find yourself doing lots of CMPs on a single value, use a table instead!
    
With notes and note lengths we used a straight lookup table of values.  With song numbers and volume envelopes we used a special type of lookup table called a pointer table, which stored data addresses.  For opcodes we have two choices.  We can use something called a jump table or we can use an RTS table.  They are almost the same and the difference in performance between the two methods is negligible so for most programmers it's a matter of personal preference.  

I prefer RTS tables myself, but we're going to use jump tables because they are easier to explain and understand.

Jump Tables
Ok, here's our problem:  Our sound engine has opcodes.  A lot of them, let's say 10 or more.  Each opcode has its own subroutine.  When our sound engine reads an opcode byte from the data stream, we want to avoid a long list of CMP and BNE instructions to select the right subroutine.  How do we do that?   We use a jump table.

A jump table is similar to a pointer table: it is a table of addresses.  But whereas a pointer table holds addresses that point to the start of data, a jump table holds addresses that point to the start of code (ie, the start of subroutines).  For example, suppose we have some subroutines:

sub_a:
    lda #$00
    ldx #$FF
    rts
 
sub_b:
    clc
    adc #$03
    rts
 
sub_c:
    sec
    sbc #$03
    rts
    
Here is how a jump table would look using these subroutines:

sub_jump_table:
    .word sub_a, sub_b, sub_c
    
Hey, that's pretty easy.  We just use the subroutine label and the assembler will translate that into the address where the subroutine starts.  Let's make a jump table for our sound opcode subroutines:

se_op_endsound:
    ;do stuff
    rts
 
se_op_infinite_loop:
    ;do stuff
    rts
 
se_op_change_ve:
    ;do stuff
    rts
 
;etc..  more subroutines

;this is our jump table
sound_opcodes:
    .word se_op_endsound
    .word se_op_infinite_loop
    .word se_op_change_ve
    ;etc, one entry per subroutine
    
Cool.  We have a jump table now.  So how do we use it?

Indirect Jumping
The 6502 let's us do some cool things.  One of those things is called an indirect jump.  An indirect jump let's you stick a destination address into a zero-page pointer variable and jump there.  It works like this:

    .rsset $0000
;first declare a pointer variable somewhere in the zero-page
jmp_ptr .rs 2  ;2 bytes because an address is always a word

    lda #$00
    sta jmp_ptr
    lda #$80
    sta jmp_ptr+1
    jmp [jmp_ptr] ;will jump to $8000
    
Here we stick an address ($8000, lo byte first) into our jmp_ptr variable.  Then we do an indirect jump by using the JMP instruction followed by a pointer variable in brackets:

    jmp [jmp_ptr] ;indirect jump
    
This instruction translates into English as "Jump to the address that is stored in jmp_ptr and jmp_ptr+1".  It's extrememly useful.  We can stick any address we want in there:
    
    lda #$00
    sta jmp_ptr
    lda #$C0
    sta jmp_ptr+1
    jmp [jmp_ptr] ;will jump to $C000
    
We could read an address from ROM and use that if we wanted to, for example our reset vector:
    
    lda $FFFC
    sta jmp_ptr
    lda $FFFD
    sta jmp_ptr+1
    jmp [jmp_ptr] ;will jump to our reset routine
    
And we can use it in combination with our jump table:

    lda sound_opcodes, y    ;read low byte of address from jump table
    sta jmp_ptr
    lda sound_opcodes+1, y  ;read high byte
    sta jmp_ptr+1
    jmp [jmp_ptr]   ;will jump to whatever address we pulled from the table.
    
Pretty powerful.  We can dynamically jump to any section of code we want!
    
Implementation
So we know how to build a jump table and we know how to do an indirect jump.  Let's tie it all together and stick it into our sound engine.  Let's start with se_fetch_byte.  se_fetch_byte reads a byte from the data stream and range-checks it to see if it is a note, note length or opcode.  Recall that notes have a byte range of $00-$7F.  Note lengths have a range of $80-$9F.  The opcode byte range is $A0-$FF:

se_fetch_byte:
    lda stream_ptr_LO, x
    sta sound_ptr
    lda stream_ptr_HI, x
    sta sound_ptr+1
 
    ldy #$00
    lda [sound_ptr], y
    bpl .note                ;if < #$80, it's a Note
    cmp #$A0
    bcc .note_length         ;else if < #$A0, it's a Note Length
.opcode:                     ;else ($A0-$FF) it's an opcode
    ;do Opcode stuff
.note_length:
    ;do note length stuff
.note:
    ;do note stuff
    
So we need to assign our opcodes to values between $A0 and $FF.  Just as with notes and note lengths, the opcode byte we read from the data stream will be used as a table index (after subtracting $A0), so we will assign our opcodes in the same order as our table:

sound_opcodes:
    .word se_op_endsound            ;this should be $A0
    .word se_op_infinite_loop       ;this should be $A1
    .word se_op_change_ve           ;this should be $A2
    ;etc, 1 entry per subroutine

;these are aliases to use in the sound data.
endsound = $A0
loop = $A1              ;be careful of conflicts here.  this might be too generic.  maybe song_loop is better
volume_envelope = $A2

Now let's alter se_fetch_byte to take care of our opcodes:

se_fetch_byte:
    lda stream_ptr_LO, x
    sta sound_ptr
    lda stream_ptr_HI, x
    sta sound_ptr+1
 
    ldy #$00
.fetch:
    lda [sound_ptr], y
    bpl .note                ;if < #$80, it's a Note
    cmp #$A0
    bcc .note_length         ;else if < #$A0, it's a Note Length
.opcode:                     ;else ($A0-$FF) it's an opcode
    ;do Opcode stuff
    jsr se_opcode_launcher   ;launch our opcode!!!
    iny                      ;next position in the data stream
    lda stream_status, x
    and #%00000001
    bne .fetch               ;after our opcode is done, grab another byte unless the stream is disabled
    rts                      ; in which case we quit  (explained below)
.note_length:
    ;do note length stuff
.note:
    ;do note stuff
    
I added a call to a subroutine called se_opcode_launcher and a little branch.  Not a big change is it?  But there's an important detail here.  se_opcode_launcher will be a short, simple subroutine that will read from the jump table and perform an indirect jump.  It looks like this:

se_opcode_launcher:
    sty sound_temp1         ;save y register, because we are about to destroy it
    sec
    sbc #$A0                ;turn our opcode byte into a table index by subtracting $A0
                            ;   $A0->$00, $A1->$01, $A2->$02, etc.  Tables index from $00.
    asl a                   ;multiply by 2 because we index into a table of addresses (words)
    tay
    lda sound_opcodes, y    ;get low byte of subroutine address
    sta jmp_ptr
    lda sound_opcodes+1, y  ;get high byte
    sta jmp_ptr+1
    ldy sound_temp1         ;restore our y register
    iny                     ;set to next position in data stream (assume an argument)
    jmp [jmp_ptr]           ;indirect jump to our opcode subroutine
    
Short and simple.  So why did I wrap this code in its own subroutine?  Why not just stick this code as-is in the .opcode branch of se_fetch_byte?  Because we need a place to return to.

The JSR and RTS instructions work as a pair.  They go hand in hand.  They need each other.  Without going into too much detail, this is what goes on behind the scenes:

JSR sticks a return address on the stack and jumps to a subroutine.  One way to look at it is to think of JSR as a JMP that remembers where it started from.
RTS pops the return address off the stack and jumps there. 

So JSR leaves a treasure map for RTS to pick up and follow later.  The key point here is that RTS expects a return address to be waiting for it on the stack.  

Now our opcode subroutines all end in an RTS instruction.  Do you see the potential problem here?

We call our opcode subroutines using an indirect jump.  This requires us to use a JMP instruction, not a JSR instruction.  A JMP instruction doesn't remember where it started from.  No return address is pushed onto the stack with a JMP instruction.  So when we jump to our opcode subroutine and hit the RTS instruction at the end, there is no return address waiting for us!  The RTS will pull whatever random values happen to be on the stack at the time and jump there.  We'll end up somewhere random and our program will surely crash!

To fix this, we wrap our indirect jump in a subroutine, se_opcode_launcher.  We call it with a JSR instruction, completing the JSR/RTS pair:

    jsr se_opcode_launcher  ;this jsr will let us remember where we came from
    
This JSR instruction will stick a return address on the stack for us.  Then inside se_opcode_launcher we perform our indirect jump to our desired opcode subroutine.  Now when we hit that RTS instruction at the end of the opcode subroutine we have a return address waiting for us on the stack.  Our program returns back to where we started.  We are safe.

Opcode Subroutines
With our opcode launcher written, we are all set up to make opcodes.  We already have one written: the endsound opcode.  This is the opcode we will use to terminate sound effects.  Sound effects don't loop continuously like songs do, so they need to be stopped.  Let's take a look again:

se_op_endsound:
    lda stream_status, x    ;end of stream, so disable it and silence
    and #%11111110
    sta stream_status, x    ;clear enable flag in status byte
 
    lda stream_channel, x
    cmp #TRIANGLE
    beq .silence_tri        ;triangle is silenced differently from squares and noise
    lda #$30                ;squares and noise silenced with #$30
    bne .silence            ; (this will always branch.  bne is cheaper than a jmp)
.silence_tri:
    lda #$80                ;triangle silenced with #$80
.silence:
    sta stream_vol_duty, x  ;store silence value in the stream's volume variable.

    rts
    
This opcode is special.  It's the reason for the check after the call to se_opcode_launcher:

se_fetch_byte:
    ;---snip---
.opcode:                     ;else ($A0-$FF) it's an opcode
    ;do Opcode stuff
    jsr se_opcode_launcher
    iny                      ;next position in the data stream
    lda stream_status, x
    and #%00000001
    bne .fetch               ;after our opcode is done, grab another byte unless the stream is disabled
    rts                      ; in which case we quit  (explained below)
 
    ;---snip---
    
Normally, we want se_fetch_byte to keep fetching bytes until it hits a note.  Recall that with note lengths we jumped back to .fetch after setting the new note length.  This is because after setting the length of the note, we needed to know WHAT note to play.  So we fetch another byte.  The same thing is true of opcodes.  If we change the volume envelope with an opcode, great!  But we still need to know what note to play next.  If we use an opcode to switch our square's duty cycle, great!  But we still need to know what note to play next.  If we use an opcode to loop back to the beginning of the song, that's great!  But we still need to read that first note of the song.  This is why we jump back to fetch a byte after we run an opcode.

The ONE exception to this rule is when we end a sound effect.  We are terminating the sound effect completely, so there is no next note.  We don't want to fetch something that isn't there, so we need to skip the jump.  That's why we check the status byte after we run the opcode.  If the stream is disabled by the endsound opcode, we are finished.  Otherwise, fetch another byte.

Looping
The next opcode in our list is the loop opcode.  This is the opcode that we will stick at the end of every song to tell the sound engine to play the song again, and again and again.  It is actually quite easy to implement.  It takes a 2-byte argument, which is the address to loop back to.  The subroutine looks like this:

se_op_infinite_loop:
    lda [sound_ptr], y      ;read LO byte of the address argument from the data stream
    sta stream_ptr_LO, x    ;save as our new data stream position
    iny
    lda [sound_ptr], y      ;read HI byte of the address argument from the data stream
    sta stream_ptr_HI, x    ;save as our new data stream position data stream position
 
    sta sound_ptr+1         ;update the pointer to reflect the new position.
    lda stream_ptr_LO, x
    sta sound_ptr
    ldy #$FF                ;after opcodes return, we do an iny.  Since we reset  
                            ;the stream buffer position, we will want y to start out at 0 again.
    rts
    
The first thing to notice about this subroutine is that it reads two bytes from the data stream.  This is the address argument that gets passed along with the opcode.  To make it clear, let's look at some example sound data:

song1_square1:
    .byte eighth ;set note length to eighth notes
    .byte C5, E5, G5, C6, E6, G6, C5, Eb5, G5, C6, Eb6, half, G6 ;play some notes
    .byte loop          ;this alias evaluates to $A1, the loop opcode
    .word song1_square1 ;this evaluates to the address of the song1_square1 label
                        ;ie, the address we want to loop to.
                        
After the "loop" opcode comes a word which is the address to loop back to.  In this example I chose to loop back to the beginning of the stream data.

So what does our loop opcode do?  It reads the first byte of this address argument (the low byte) and stores it in stream_ptr_LO.  Then it reads the second byte of the address argument (the high byte) and stores it in stream_ptr_HI.  These are the variables that keep track of our data stream position!  The loop opcode just changes these values to some address that we specify.  Not too complicated at all.  The last step is to update the actual pointer (sound_ptr) so that the next byte we read from the data stream will be the first note we looped back to.

In the example sound data above I looped back to the beginning of the stream data, but there's nothing stopping me from looping somewhere else:

song1_square1:
;intro, don't loop this part
    .byte quarter
    .byte C4, C4, C4, C4
.loop_point:    ;this is where we will loop back to.
    .byte eighth ;set note length to eighth notes
    .byte C5, E5, G5, C6, E6, G6, C5, Eb5, G5, C6, Eb6, half, G6
    .byte loop          ;this alias evaluates to $A1, the loop opcode
    .word .loop_point ;this evaluates to the address of the .loop_point label
                        ;ie, the address we want to loop to.
                        
Technically we can also "loop" to a forward position, in which case it's actually more like a jump than a loop.  That's all a loop is really: a jump... backwards.

Changing Volume Envelopes
Let's write the opcode subroutine to change volume envelopes.  This one is even easier.  It takes one argument, which will be which volume envelope to switch to:

se_op_change_ve:
    lda [sound_ptr], y      ;read the argument
    sta stream_ve, x        ;store it in our volume envelope variable
    lda #$00
    sta stream_ve_index, x  ;reset volume envelope index to the beginning
    rts
    
That's it!

Changing Duty Cycles
Now let's add an opcode that will change the duty cycle for a square stream.  This one also takes one argument: which duty cycle to switch to.

se_op_duty:
    lda [sound_ptr], y      ;read the argument (which duty cycle to change to)
    sta stream_vol_duty, x  ;store it.
    rts
    
Done!  Now we have the subroutine, but we still need to add it to our jump table:

sound_opcodes:
    .word se_op_endsound            ;this should be $A0
    .word se_op_loop                ;this should be $A1
    .word se_op_change_ve           ;this should be $A2
    .word se_op_duty                ;this should be $A3
    ;etc, 1 entry per subroutine

;these are aliases to use in the sound data.
endsound = $A0
loop = $A1
volume_envelope = $A2
duty = $A3

And it's ready to use:

song0_square1:
;intro, don't loop this part
    .byte quarter
    .byte C4, C4, C4, C4
.loop_point:                            ;this is where we will loop back to.
    .byte duty, $B0                     ;change the duty cycle
    .byte volume_envelope, ve_blip_echo ;change the volume envelope
    .byte eighth                        ;set note length to eighth notes
    .byte C5, E5, G5, C6, E6, G6        ;play some notes
 
    .byte duty, $30                     ;change the duty cycle
    .byte volume_envelope, ve_short_staccato    ;change volume envelope
    .byte C5, Eb5, G5, C6, Eb6, half, G6    ;play some eighth notes and a half note
 
    .byte loop                          ;loop to .loop_point
    .word .loop_point
    
Readability
sound_engine.asm is getting pretty bulky with all these subroutines.  It will only get bigger as we add more opcodes.  It's nice to have all of our opcodes together in one place, but it's annoying to have to scroll around to find them.  So let's pull all of our opcodes into their own file: sound_opcodes.asm.  Then, at the bottom of sound_engine.asm, we can .include it:

    .include "sound_opcodes.asm" ;our opcode subroutines, jump table and aliases
    .include "note_table.i" ;period lookup table for notes
    .include "note_length_table.i"
    .include "vol_envelopes.i"
    .include "song0.i"  ;holds the data for song 0 (header and data streams)
    .include "song1.i"  ;holds the data for song 1
    .include "song2.i"
    .include "song3.i"
    .include "song4.i"
    .include "song5.i"
    .include "song6.i"  ;oooh.. new song!
    
I gave it the extension .asm because it contains code as well as data, and I like to be able to tell at a glance what files have what in them.  Now whenever we want to add new opcodes, or tweak old ones, we have them nice and compact in their own file.

Updating Sound Data
Whenever we add new things to our sound engine, we have to think about how it will affect our old sound data.  This week we added opcodes, which will change our songs and sound effects terminate.  Before we were terminating them with $FF.  This won't work anymore because $FF doesn't do anything.  For songs, we should terminate with "loop" followed by an address to loop to.  With sound effects we should terminate with the opcode "endsound".  See the included songs and sound effects for examples.

RTS Tables
We talked about jump tables and indirect jumping this week.  Another method for doing the same thing involves something called an RTS table and the RTS Trick.  I won't cover it in these tutorials, but if you are curious to know how this works you can read this nesdev wiki article I wrote about the RTS Trick.


Putting It All Together
Download and unzip the opcodes.zip sample files.  Make sure the following files are in the same folder as NESASM3:

    opcodes.asm
    sound_engine.asm
    sound_opcodes.asm
    opcodes.chr
    note_table.i
    note_length_table.i
    vol_envelopes.i
    song0.i
    song1.i
    song2.i
    song3.i
    song4.i
    song5.i
    song6.i
    opcodes.bat

Double click opcodes.bat. That will run NESASM3 and should produce the opcodes.nes file. Run that NES file in FCEUXD SP.

Use the controller to select songs and play them.  Controls are as follows:
    
Up: Play
Down: Stop
Right: Next Song/SFX
Left: Previous Song/SFX

Song0 is a silence song.  Not selectable.
Song1 is a boss song from The Guardian Legend.  Now it loops!
Song2 is the same short sound effect from last week.  Terminated with endsound.
Song3 is a song from Dragon Warrior.  Now it loops!
Song4 is the same song4 as last week, but now it loops!
Song5 is a short sound effect, terminated with the endsound opcode.
Song6 should be familiar to readers of this forum.  Do you recognize it?  It utilizes opcodes for changing duty cycles and volume envelopes.  Plus it loops!

Try adding your own songs and sound effects in.  Try to add your own opcodes too.  Here's some ideas for opcodes:

1. Trigger a sound effect mid-song
2. Implement duty cycle envelopes (similar to volume envelopes).  Then make an opcode that allows you to change it.
3. Finite loops

Next Week: more opcode fun.  Finite Loops, Changing Keys and Autom... .