MARS MIDI Player - Technical Design Document

Transcription

1 MARS MIDI Player - Technical Design Document Convert from *.mid to *.luke 1. Get a selection of MIDI files you wish to play 2. Open up MIDI to Text v17.exe and load in the MIDI files you want, making sure all relevant options or chosen, then press Convert. This will then create some.mt files: 3. Open up CustomFileFormatConverter.exe and select which.mt files you want to convert to.luke files: 4. Now you should have the relevant.luke files, which can be played in MARS: Page 1 of 9

2 Structure of Code Readability The code was written to be as simple to read and edit as possible. The first thing that happens in the program is it jumps to a label called EntryPoint, which is where everything else is called from. The code is also heavily commented so that it is clear to see what is happening where. Getting user input When the code first starts it pops up a dialog box which prompts the user to enter a file name. If the user presses Cancel on this box then the program ends, they then type in the name of the file. This returns a string which has a new line character at the end. This new line character has to be gotten rid of before the string can be used, as file names do not have new line characters at the end of them. The first thing to do is to load the address of where the file name is being stored. This is done before entering the loop: This method does involve using the stack, which is explained below. After loading the return address on the stack, the character which we are currently checking is loaded into $t5 and then the character of a new line is loaded into $t6. Page 2 of 9

3 This is done so that they can be compared: If these characters are not the same then a byte is added onto the address pointer of the character we are looking at, so it now points at the new character in the string: Then it will jump back to the top of the sub routine and it will repeat: If it did locate the character then it will jump to the section which replaces the new line character with a null terminator: The string is now null terminated. The final things to do are load the return address back and jump back to where we were called from: Using the stack As it uses sub routines for everything I had to implement using the stack into the code. Every time it enters a sub routine it will move the stack pointer along by 4 and then push the return address onto the stack: The sub routine will then carry on as normal, and is able to safely call as many sub routines from within itself. Then at the end it loads a word back off the stack and into $ra, decrease the stack pointer by 4 again. Then it will use the Jump return command to jump to the address stored in $ra, which is the point this sub routine was called from: Page 3 of 9

4 Each sub routine is responsible for managing its own part of the stack, so that it doesn t get confusing if it was adjusting the stack in different places. I chose to use this method in every sub routine so that I could move code around without having to worry if it will return correctly or if the return address will be overwritten. Storing everything in words Everything in a.luke file is stored in as little space as possible. When it is read into memory at run time everything is stored in a word (4 bytes). This is done for ease of loading and debugging, as memory addresses are sorted into 4 byte words in MARS. Polyphony Polyphony is playing several sets of notes at once. My midi player does this by using syscall 37, which returns straight after the note starts playing, rather than using syscall 33 which waits until the note is finished playing before returning. To stop all notes in the song from being played straight away a sleep timer is used to pause the loop until the start time of the next note. To sleep I used syscall 32: Sleep time is calculated in the C# converter by subtracting the current note s start time from the next note s start time. Clearing memory at the end The first time a song plays all memory we ve been allocated on the heap is already set to zero, then we store a byte in there and move along 4 spaces to where the next word begins. This loop loads in the first 3 bytes of note information and stores them in 3 separate words: Page 4 of 9

5 $t7 is what memory address we are currently pointing at. The loop loads reads in a single byte, stores it at $t7 and then $t7 is moved along 4 bytes. Doing this means it is stored clearly in memory and easy to read: The user then has the option of playing another song at the end, if the user selects yes then the whole process of allocating memory on the heap etc. is repeated. However, this time memory isn t guaranteed to be set to all zeros, as we had previously filled it with data. Then if you were to store a single byte in memory, previous data could affect and change the value which we wanted to store. To solve this, at the end of a song, all memory we have used is cleared to zeros: The value of 0 is loaded into every memory address that we have used, clearing it out ready to safely play the next song. Playing a new song afterwards The user is given an option to play another song after their first song has started playing: This is done using syscall 50. If the user presses No or Cancel then the program will end, if the user presses Yes, then the program will jump to the beginning of EntryPoint, which has the same effect of restarting the program. The whole thing runs again and the user is able to play a new song straight after their first. The program knows if a user presses yes because the syscall will return a value of 0 in register $a0. Page 5 of 9

6 File Type (*.luke) Explained Above is a screenshot of a.luke file with boxes highlighting the different sections. Red box The first 4 bytes of the file stores the total number of bytes that will need to be stored on the heap. Previously I had it so that the MIPS code opened up the.luke file and read through the entire thing just to count how many bytes it needed to allocate on the heap. It then had to open the file again and read through it to collect actual data. This was quite unnecessary, so I just got it to store the amount of bytes needed in the file. Green box The next 4 bytes is the total amount of notes in the file, this is used for collecting all note information from the file, and then used again when playing the notes, to make sure that we are using the correct amount of notes. Purple box This is where channel data is stored. The first byte is how many channels are going to be set in this file (n), then the following n bytes is the value of each channel. So for example in the image above, the first byte is 0A which is 10 in decimal, then the following 10 bytes are channel data for channels 0 9. There is more information on why I chose this method below. Page 6 of 9

7 Blue box This is note information, and the rest of the file from this point on is all note information. The first three pieces of note information are Pitch, Channel and Velocity, which are all stored in a single byte. The next two values are Duration and Sleep Time, which are stored in 2 bytes each. When storing the information in the red and green box I chose to use 4 bytes numbers so that songs which are large would still be able to play, rather than limiting to having to be less than a specific size. The method of storing channel data was chosen to maximise space saving. Rather than storing all 16 channels for every song regardless of whether or not it uses them, it only stores channels which are going to be used. There were two ways of doing this: storing the channel number and then the value to set it to, or storing the channel numbers in order from There are positives and negatives for both ways of storing data in those methods. With the first one, if a song is using a lot of channels then it would be using up more space for the same amount of information compared to the second method. However a negative for the second method was if a song used channels 0, 1 and 9, then channel information would have to be stored for all the channels in-between too. I chose the second method because for songs which use lots of channels it is a better use of space in the second method. C# Converter The converter takes.mt files, which are generated by Dominic Bodman s Midi to Text. The C# converter starts reading lines and using the character to split the strings into different sections: Line 7 is always channel data, so that is loaded into a list first, using a simple for loop on the split data (i is the line we are currently on): Every line after channel data is then a new note, so all note data is then loaded in: Page 7 of 9

8 So, now we have all the channel and note data stored in the C# converter. The next step is to write this to a file. But before it does that it has to get rid of channels at the end which aren t being used. This loops around the channel data, starting from the far right of the list, and removes all channels which are -1, as that means they are not in use. If it comes across a channel which is not -1 then it breaks out of the loop, as the channels which do not need to be written have been gotten rid of. Currently channel data is being stored as ints, but in the file they are stored as unsigned bytes. As the channel data may still contain -1 s, it has to loop around and change any of these to 0. The data is then ready for being written to the file: The first thing that gets written to the file is the amount of bytes that the midi player will have to allocate on the heap: Page 8 of 9

9 This value is then written into the file, along with total number of notes and number of channels: After this, channel data is then written to the file. It uses a for loop as the amount of data it has to write varies between files: Next to come is note data, which is done in a loop as the amount of notes also changes depending on the song being played: It is written in the order of Pitch, Channel, Velocity (volume) and Duration of the note. Sleep Time is calculated by subtracting the next note s start time by the current note s start time. This means that all timings in.luke files are relative to the previous note, saving file space instead of having to write out the full start time. If the note is the last in the list then sleep time is set straight to 0. The writer is then closed, and the.luke file is finished. Page 9 of 9