Commented the heck out of this thing, to put my thoughts in order if nothing else.

Outputs/CRT.cpp

@@ -16,18 +16,19 @@ static const int syncCapacityLineChargeThreshold = 3;
 static const int millisecondsHorizontalRetraceTime = 16;
 static const int scanlinesVerticalRetraceTime = 26;
 
-#define kEmergencyRetraceTime	(_expected_next_hsync + _hsync_error_window)
-
 using namespace Outputs;
 
 CRT::CRT(int cycles_per_line, int height_of_display, int number_of_buffers, ...)
 {
+	// store fundamental display configuration properties
 	_height_of_display = height_of_display;
 	_cycles_per_line = cycles_per_line;
 
-	_horizontalOffset = 0.0f;
-	_verticalOffset = 0.0f;
+	// generate timing values implied by the given arbuments
+	_hsync_error_window = cycles_per_line >> 5;
 
+	// generate buffers for signal storage as requested — format is
+	// number of buffers, size of buffer 1, size of buffer 2...
 	_numberOfBuffers = number_of_buffers;
 	_bufferSizes = new int[_numberOfBuffers];
 	_buffers = new uint8_t *[_numberOfBuffers];
@@ -41,16 +42,26 @@ CRT::CRT(int cycles_per_line, int height_of_display, int number_of_buffers, ...)
 	}
 	va_end(va);
 
+	// reset pointer into output buffers
 	_write_allocation_pointer = 0;
+
+	// reset the run buffer pointer
+	_run_pointer = 0;
+
+	// reset raster position
+	_horizontalOffset = 0.0f;
+	_verticalOffset = 0.0f;
+
+	// reset flywheel sync
 	_expected_next_hsync = cycles_per_line;
-	_hsync_error_window = cycles_per_line >> 5;
 	_horizontal_counter = 0;
+
+	// reset the vertical charge capacitor
 	_sync_capacitor_charge_level = 0;
 
+	// start off not in horizontal sync, not receiving a sync signal
 	_is_receiving_sync = false;
 	_is_in_hsync = false;
-
-	_run_pointer = 0;
 }
 
 CRT::~CRT()
@@ -122,12 +133,18 @@ CRT::SyncEvent CRT::advance_to_next_sync_event(bool hsync_is_requested, bool vsy
 
 void CRT::advance_cycles(int number_of_cycles, bool hsync_requested, const bool vsync_charging, const CRTRun::Type type, const char *data_type)
 {
+	// this is safe to keep locally because it accumulates over this run of cycles only
 	int buffer_offset = 0;
 
 	while(number_of_cycles) {
+
+		// get the next sync event and its timing; hsync request is instantaneous (being edge triggered) so
+		// set it to false for the next run through this loop (if any)
 		int next_run_length;
 		SyncEvent next_event = advance_to_next_sync_event(hsync_requested, vsync_charging, number_of_cycles, &next_run_length);
+		hsync_requested = false;
 
+		// get a run from the allocated list, allocating more if we're about to overrun
 		if(_run_pointer >= _all_runs.size())
 		{
 			_all_runs.resize((_all_runs.size() * 2)+1);
@@ -136,17 +153,20 @@ void CRT::advance_cycles(int number_of_cycles, bool hsync_requested, const bool
 		CRTRun *nextRun = &_all_runs[_run_pointer];
 		_run_pointer++;
 
+		// set the type, initial raster position and type of this run
 		nextRun->type = type;
 		nextRun->start_point.dst_x = _horizontalOffset;
 		nextRun->start_point.dst_y = _verticalOffset;
+		nextRun->data_type = data_type;
 
+		// if this is a data or level run then store a starting data position
 		if(type == CRTRun::Type::Data || type == CRTRun::Type::Level)
 		{
 			nextRun->start_point.src_x = (_write_target_pointer + buffer_offset) & (bufferWidth - 1);
 			nextRun->start_point.dst_x = (_write_target_pointer + buffer_offset) / bufferWidth;
 		}
-		nextRun->data_type = data_type;
 
+		// advance the raster position as dictated by current sync status
 		if (_vretrace_counter > 0)
 		{
 			_verticalOffset = std::max(0.0f, _verticalOffset - (float)number_of_cycles / (float)(scanlinesVerticalRetraceTime * _cycles_per_line));
@@ -165,36 +185,50 @@ void CRT::advance_cycles(int number_of_cycles, bool hsync_requested, const bool
 			_horizontalOffset = std::min(1.0f, _horizontalOffset + (float)((((64 - millisecondsHorizontalRetraceTime) * _cycles_per_line) >> 6) * number_of_cycles) / (float)_cycles_per_line);
 		}
 
+		// store the final raster position
 		nextRun->end_point.dst_x = _horizontalOffset;
 		nextRun->end_point.dst_y = _verticalOffset;
+
+		// if this is a data run then advance the buffer pointer
 		if(type == CRTRun::Type::Data)
 		{
 			buffer_offset += next_run_length;
 		}
+
+		// if this is a data or level run then store the end point
 		if(type == CRTRun::Type::Data || type == CRTRun::Type::Level)
 		{
 			nextRun->end_point.src_x = (_write_target_pointer + buffer_offset) & (bufferWidth - 1);
 			nextRun->end_point.dst_x = (_write_target_pointer + buffer_offset) / bufferWidth;
 		}
 
-		hsync_requested = false;
-
+		// decrement the number of cycles left to run for and increment the
+		// horizontal counter appropriately
 		number_of_cycles -= next_run_length;
 		_horizontal_counter += next_run_length;
+
+		// either charge or deplete the vertical retrace capacitor (making sure it stops at 0)
 		if (vsync_charging)
 			_sync_capacitor_charge_level += next_run_length;
 		else
 			_sync_capacitor_charge_level = std::max(_sync_capacitor_charge_level - next_run_length, 0);
 
+		// decrement the vertical retrace counter, making sure it stops at 0
 		_vretrace_counter = std::max(_vretrace_counter - next_run_length, 0);
 
+		// react to the incoming event...
 		switch(next_event) {
-			default:		break;
+
+			// start of hsync: zero the scanline counter, note that we're now in
+			// horizontal sync, increment the lines-in-this-frame counter
 			case SyncEvent::StartHSync:
 				_horizontal_counter = 0;
 				_is_in_hsync = true;
 				_hsync_counter++;
 			break;
+
+			// end of horizontal sync: update the flywheel's velocity, note that we're no longer
+			// in horizontal sync
 			case SyncEvent::EndHSync:
 				if (!_did_detect_hsync) {
 					_expected_next_hsync = (_expected_next_hsync + (_hsync_error_window >> 1) + _cycles_per_line) >> 1;
@@ -202,16 +236,23 @@ void CRT::advance_cycles(int number_of_cycles, bool hsync_requested, const bool
 				_did_detect_hsync = false;
 				_is_in_hsync = false;
 			break;
+
+			// start of vertical sync: reset the lines-in-this-frame counter,
+			// load the retrace counter with the amount of time it'll take to retrace
 			case SyncEvent::StartVSync:
 				_vretrace_counter = scanlinesVerticalRetraceTime * _cycles_per_line;
 				_hsync_counter = 0;
 			break;
 
+			// end of vertical sync: tell the delegate that we finished vertical sync,
+			// releasing all runs back into the common pool
 			case SyncEvent::EndVSync:
 				if(_delegate != nullptr)
 					_delegate->crt_did_start_vertical_retrace_with_runs(&_all_runs[0], _run_pointer);
 				_run_pointer = 0;
 			break;
+
+			default:		break;
 		}
 	}
 }
@@ -225,9 +266,12 @@ void CRT::set_crt_delegate(CRTDelegate *delegate)
 
 #pragma mark - stream feeding methods
 
+/*
+	These all merely channel into advance_cycles, supplying appropriate arguments
+*/
 void CRT::output_sync(int number_of_cycles)
 {
-	bool _hsync_requested = !_is_receiving_sync;
+	bool _hsync_requested = !_is_receiving_sync;	// ensure this really is edge triggered; someone calling output_sync twice in succession shouldn't trigger it twice
 	_is_receiving_sync = true;
 	advance_cycles(number_of_cycles, _hsync_requested, true, CRTRun::Type::Sync, nullptr);
 }