The eventual video output will be a series of PPM files at a resolution of 384 × 288, intended to be viewed at 50 frames per second. This represents the output that would be seen on a television that was adjusted to display as much of the picture as possible, right up to the edge of the active picture area but not including any of the blanking interval. In reality, most televisions cropped the picture to varying degrees and not always equally on each side, which means that our output will have a larger border area than would have been typically seen on a domestic television. However, to produce this visible picture area accurate we need to consider the dimensions of the full video signal including the blanking periods, as we need to calculate and then discard this part of the signal.

The horizontal blanking period of the signal is 12 microseconds, making the 'active' portition of the signal 64 - 12 = 52 microseconds. Since we want 384 'active' pixels across each line, we multiply 384 by 64 and divide by 52 to get 472. This is the total numbers of 'pixels' we have to consider when modelling the complete video signal including the blanking periods.

For reference, using the line frequency of 15600 Hz in place of 15625 Hz in the calculation would give us a value of 473, just one pixel more, so the difference really is small enough to ignore for all practical purposes.

In the same way that the vertical blanking interval covers the first lines of the frame, so the horizontal blanking interval covers the beginning of each scan line, so to get our 384 pixels, we simply use pixels 88 - 471 of each line, and discard pixels 0 - 87.

Now that we have our 384 × 288 pixel framebuffer representing the visible part of the television display, we need to work out whereabouts within that framebuffer the active area of 256 × 192 pixels of the spectrum's display falls, and where the border area falls.

Basically, we centre it. Each 256 pixel line of the Spectrum's display can be drawn on pixels 64-319, and we can start the 192 vertical lines at Y co-ordinate 48, measured from the top. In fact the Spectrum puts it at 40, but we'll use 48, because it looks better centered for the purposes of our video effect. Feel free to change this value to 40 if you so desire.

This function output_frame should be fairly self-explanatory. We pass it a pointer to a framebuffer, and it writes that data to disk with a ppm header which specifies fixed dimensions of 384 × 288, in 24-bit color. Filenames will be numbered from 0000 to 9999, which is plenty as we will only be writing up to about 3000 frames in total.

We start current_frame counting at -1 because we want to discard the first frame written by output_frame. The reason for this will become obvious when we look at the next function. Note that we declare output_frame as a static variable. The value only ever needs to be used within this function, but we need it to be maintained between each call.

This function is called with the address of the 352 × 288 output framebuffer, a 'beam position' value, and red, green, and blue pixel values to plot. The 'beam position' is simply a linear offset into the 472 × 312 overscanned area that we are simulating. We don't store framebuffer data for this larger area, but we have to take into account that the continually sweeping beam spends some of it's time within it.

The first two compiler macros convert the linear beam position into X and Y co-ordinates in the 472 × 312 space. These are checked to see whether we are in the overscan or blanking period. If we are, then we do nothing and return 1. The return value of 1 is not used by the calling function, but might be useful for debugging.

Next we check whether the beam position is within the border area, where the raster bars should be drawn, or whether it's in the central image area, in which case we again do nothing and just return. This function set_beam_pixel, only deals with drawing the raster bars, and leaves the task of drawing content in the central display area to another function.

This is trivial, but it's worth taking a look at exactly what is going on inside this function, as the principles will be similar for the other two video generation functions that we're about to see.

We call video_silence with the address of the framebuffer, and the current beam position. We also specify the time to output a steady white border in T-states, the clock time of the z80 cpu. Remember that the central screen area of 256 × 192 pixels need not be pure white, this function is only concerned with the generation of the border color. We'll also use this function at the end of the sequence to hold the central image on screen for viewing without any raster bars.

This will output exactly 49 ppm files. It doesn't output 50 as you might expect, because the data for the last frame was written to the framebuffer, but output_frame was not called because we didn't try to write the first pixel of the next frame.

Just like with video_silence, we call video_leader with the address of the framebuffer, the current beam position, and the duration of leader that we want. This time the duration is in seconds. This was an arbitrary choice, we could just as well have used T-states here, but when creating effects I tend to think in terms of seconds rather than T-states.

An important variable here, which is local to this function but will be used for the same purpose in several other functions is 'm'. This contains a boolean value indicating the current state of the tape output port, basically whether the square wave is 'up', or, 'down'. Remember that the exact phase doesn't matter at all, all that matters is where the 'edges' of the signal fall, the transitions from one state to the next. When m is zero, we output a cyan color to the border area, (green and blue on, red off), and when m is one, we output red.

As explained in the comments that start this block of code, each pulse lasts for 2168 T-states, and that corresponds to 4560.9 pixels being passed by our virtual beam sweeping across the 472 × 312 framebuffer. We round this figure to 4561, and output 808 sets of pulses for each second of leader requested.

The value of m is toggled within the loop by checking if n % 4561 = 0. It's very important indeed that we pay attention to the loops that do this, to avoid several types of error being introduced.

We also need to be sure that we are consistent if we are going to let the next part of the logic inherit the ending state of m. Either we need to toggle m after outputting the final value of the first step, such that the second step inherits it's correct starting value, or alternatively we need to avoid toggling m after outputting tht final value of the first step, and do it at the beginning of the next step. Doing both would doubly invert m leaving it unchanged, and we would then have two consecutive pulses with the same sense, which is wrong.

In the case of an off by one error like this, the difference in the visual waveforms would be almost impossible to notice, but the output would be wrong. More importantly, though, when we come to generate the audio waveform, the same error would likely introduce a brief click and an extra edge to the square wave. This would cause the waveform to fail loading on a real Spectrum.

For this reason, also, we ensure that we always create an odd number of pilot tone pulses. The construct (duration_seconds*808)|1 achieves this by setting the least significant bit. This in turn ensures that we end with the last pulse of the pilot tone having been in the mark state, with m=1, and can generate the first pulse of the sync tone with m=0, which is faithful to the original. If we created an even number of pilot tone pulses, then we would end with m=0, and would either have to invert the sync pulses, or generate an inaccurate waveform.

Of course, none of this matters for the purposes of creating a video effect, but similar issues may well arise in other programming projects that you take on, so it's a good example to point out.

We call this function with the usual framebuffer pointer and beam position, but instead of a duration we just supply a single byte to use as the data to create the waveform. We convert the T-state timing values into numbers of pixels using the same formula as before, and shift each bit sequentially into the most significant bit to read it out.

When run, this will generate 159 ppm frames, starting briefly with a white screen, followed by two seconds of the pilot tone, a total of 19 bytes of data represented by the blue and yellow bars, and finally more white screen.

Looking carefully at frame 105, we can actually see all of the waveforms at the same time. The top of the screen shows the end of the pilot tone, with it's equally spaced red and cyan bars. Then we see the short unequal pulses of the sync, the first cyan pulse being slightly shorter than the second red one, and below that we can see the data bits. The first two bytes we encoded were 0 and 3, where 0 is the flag byte indicating that the data that follows is actually a header, and 3 is the first byte of the header itself. In binary, these bytes would be 00000000 00000011. Counting the pairs of yellow and blue bars down the screen, we can indeed see that there are 14 thin pairs, followed by two wider pairs. Those are our first two bytes successfully encoded!

The header is quite simple. As previously mentioned, the first byte is technically not part of the header, as a corresponding byte is found before the block of user data, except that it's 0xff rather than 0x00. The 0x03 byte indicates that the user data in the following data block is an arbitrary dump of memory contents, rather than, for example, a basic program. The following ten bytes are, unsurprisingly, the filename. After this we have three more 16-bit values in little-endian format, the length of the data, the memory address to load it at, and finally an arbitrary 0x8000, (0x00 0x80 in little endian format), as this third parameter is not used for blocks of code.

In this part of the project, we've written functions to simulate the movement of the video beam across the screen, and output ppm files for each frame. We've also successfully encoded pilot tones and a small amount of binary data in the form of the header.