mirror of
https://github.com/TomHarte/CLK.git
synced 2024-12-27 01:31:42 +00:00
361 lines
14 KiB
C++
361 lines
14 KiB
C++
//
|
|
// CRT.hpp
|
|
// Clock Signal
|
|
//
|
|
// Created by Thomas Harte on 19/07/2015.
|
|
// Copyright 2015 Thomas Harte. All rights reserved.
|
|
//
|
|
|
|
#ifndef CRT_hpp
|
|
#define CRT_hpp
|
|
|
|
#include <array>
|
|
#include <cstdint>
|
|
#include <limits>
|
|
#include <memory>
|
|
|
|
#include "../ScanTarget.hpp"
|
|
#include "Internals/Flywheel.hpp"
|
|
|
|
namespace Outputs {
|
|
namespace CRT {
|
|
|
|
class CRT;
|
|
|
|
class Delegate {
|
|
public:
|
|
virtual void crt_did_end_batch_of_frames(CRT *crt, int number_of_frames, int number_of_unexpected_vertical_syncs) = 0;
|
|
};
|
|
|
|
/*! Models a class 2d analogue output device, accepting a serial stream of data including syncs
|
|
and generating the proper set of output spans. Attempts to act and react exactly as a real
|
|
TV would have to things like irregular or off-spec sync, and includes logic properly to track
|
|
colour phase for colour composite video.
|
|
*/
|
|
class CRT {
|
|
private:
|
|
// The incoming clock lengths will be multiplied by @c time_multiplier_; this increases
|
|
// precision across the line.
|
|
int time_multiplier_ = 1;
|
|
|
|
// Two flywheels regulate scanning; the vertical will have a range much greater than the horizontal;
|
|
// the output divider is what that'll need to be divided by to reduce it into a 16-bit range as
|
|
// posted on to the scan target.
|
|
std::unique_ptr<Flywheel> horizontal_flywheel_, vertical_flywheel_;
|
|
int vertical_flywheel_output_divider_ = 1;
|
|
int cycles_since_horizontal_sync_ = 0;
|
|
Display::ScanTarget::Scan::EndPoint end_point(uint16_t data_offset);
|
|
|
|
struct Scan {
|
|
enum Type {
|
|
Sync, Level, Data, Blank, ColourBurst
|
|
} type = Scan::Blank;
|
|
int number_of_cycles = 0, number_of_samples = 0;
|
|
uint8_t phase = 0, amplitude = 0;
|
|
};
|
|
void output_scan(const Scan *scan);
|
|
|
|
uint8_t colour_burst_amplitude_ = 30;
|
|
int colour_burst_phase_adjustment_ = 0xff;
|
|
|
|
int64_t phase_denominator_ = 1;
|
|
int64_t phase_numerator_ = 0;
|
|
int64_t colour_cycle_numerator_ = 1;
|
|
bool is_alernate_line_ = false, phase_alternates_ = false, should_be_alternate_line_ = false;
|
|
|
|
void advance_cycles(int number_of_cycles, bool hsync_requested, bool vsync_requested, const Scan::Type type, int number_of_samples);
|
|
Flywheel::SyncEvent get_next_vertical_sync_event(bool vsync_is_requested, int cycles_to_run_for, int *cycles_advanced);
|
|
Flywheel::SyncEvent get_next_horizontal_sync_event(bool hsync_is_requested, int cycles_to_run_for, int *cycles_advanced);
|
|
|
|
Delegate *delegate_ = nullptr;
|
|
int frames_since_last_delegate_call_ = 0;
|
|
|
|
bool is_receiving_sync_ = false; // @c true if the CRT is currently receiving sync (i.e. this is for edge triggering of horizontal sync); @c false otherwise.
|
|
bool is_accumulating_sync_ = false; // @c true if a sync level has triggered the suspicion that a vertical sync might be in progress; @c false otherwise.
|
|
bool is_refusing_sync_ = false; // @c true once a vertical sync has been detected, until a prolonged period of non-sync has ended suspicion of an ongoing vertical sync.
|
|
int sync_capacitor_charge_threshold_ = 0; // Charges up during times of sync and depletes otherwise; needs to hit a required threshold to trigger a vertical sync.
|
|
int cycles_of_sync_ = 0; // The number of cycles since the potential vertical sync began.
|
|
int cycles_since_sync_ = 0; // The number of cycles since last in sync, for defeating the possibility of this being a vertical sync.
|
|
|
|
int cycles_per_line_ = 1;
|
|
|
|
Outputs::Display::ScanTarget *scan_target_ = &Outputs::Display::NullScanTarget::singleton;
|
|
Outputs::Display::ScanTarget::Modals scan_target_modals_;
|
|
static constexpr uint8_t DefaultAmplitude = 41; // Based upon a black level to maximum excursion and positive burst peak of: NTSC: 882 & 143; PAL: 933 & 150.
|
|
|
|
#ifndef NDEBUG
|
|
size_t allocated_data_length_ = std::numeric_limits<size_t>::min();
|
|
#endif
|
|
|
|
public:
|
|
/*! Constructs the CRT with a specified clock rate, height and colour subcarrier frequency.
|
|
The requested number of buffers, each with the requested number of bytes per pixel,
|
|
is created for the machine to write raw pixel data to.
|
|
|
|
@param cycles_per_line The clock rate at which this CRT will be driven, specified as the number
|
|
of cycles expected to take up one whole scanline of the display.
|
|
|
|
@param clocks_per_pixel_greatest_common_divisor The GCD of all potential lengths of a pixel
|
|
in terms of the clock rate given as @c cycles_per_line.
|
|
|
|
@param height_of_display The number of lines that nominally form one field of the display, rounded
|
|
up to the next whole integer.
|
|
|
|
@param colour_cycle_numerator Specifies the numerator for the per-line frequency of the colour subcarrier.
|
|
|
|
@param colour_cycle_denominator Specifies the denominator for the per-line frequency of the colour subcarrier.
|
|
The colour subcarrier is taken to have colour_cycle_numerator/colour_cycle_denominator cycles per line.
|
|
|
|
@param vertical_sync_half_lines The expected length of vertical synchronisation (equalisation pulses aside),
|
|
in multiples of half a line.
|
|
|
|
@param data_type The format that the caller will use for input data.
|
|
*/
|
|
CRT(int cycles_per_line,
|
|
int clocks_per_pixel_greatest_common_divisor,
|
|
int height_of_display,
|
|
Outputs::Display::ColourSpace colour_space,
|
|
int colour_cycle_numerator,
|
|
int colour_cycle_denominator,
|
|
int vertical_sync_half_lines,
|
|
bool should_alternate,
|
|
Outputs::Display::InputDataType data_type);
|
|
|
|
/*! Constructs a monitor-style CRT — one that will take only an RGB or monochrome signal, and therefore has
|
|
no colour space or colour subcarrier frequency. This monitor will automatically map colour bursts to the black level.
|
|
*/
|
|
CRT(int cycles_per_line,
|
|
int clocks_per_pixel_greatest_common_divisor,
|
|
int height_of_display,
|
|
int vertical_sync_half_lines,
|
|
Outputs::Display::InputDataType data_type);
|
|
|
|
/*! Exactly identical to calling the designated constructor with colour subcarrier information
|
|
looked up by display type.
|
|
*/
|
|
CRT(int cycles_per_line,
|
|
int minimum_cycles_per_pixel,
|
|
Outputs::Display::Type display_type,
|
|
Outputs::Display::InputDataType data_type);
|
|
|
|
/*! Resets the CRT with new timing information. The CRT then continues as though the new timing had
|
|
been provided at construction. */
|
|
void set_new_timing(
|
|
int cycles_per_line,
|
|
int height_of_display,
|
|
Outputs::Display::ColourSpace colour_space,
|
|
int colour_cycle_numerator,
|
|
int colour_cycle_denominator,
|
|
int vertical_sync_half_lines,
|
|
bool should_alternate);
|
|
|
|
/*! Resets the CRT with new timing information derived from a new display type. The CRT then continues
|
|
as though the new timing had been provided at construction. */
|
|
void set_new_display_type(
|
|
int cycles_per_line,
|
|
Outputs::Display::Type display_type);
|
|
|
|
/*! Changes the type of data being supplied as input.
|
|
*/
|
|
void set_new_data_type(Outputs::Display::InputDataType data_type);
|
|
|
|
/*! Sets the CRT's intended aspect ratio — 4.0/3.0 by default.
|
|
*/
|
|
void set_aspect_ratio(float aspect_ratio);
|
|
|
|
/*! Output at the sync level.
|
|
|
|
@param number_of_cycles The amount of time to putput sync for.
|
|
*/
|
|
void output_sync(int number_of_cycles);
|
|
|
|
/*! Output at the blanking level.
|
|
|
|
@param number_of_cycles The amount of time to putput the blanking level for.
|
|
*/
|
|
void output_blank(int number_of_cycles);
|
|
|
|
/*! Outputs the first written to the most-recently created run of data repeatedly for a prolonged period.
|
|
|
|
@param number_of_cycles The number of cycles to repeat the output for.
|
|
*/
|
|
void output_level(int number_of_cycles);
|
|
|
|
/*! Declares that the caller has created a run of data via @c begin_data that is at least @c number_of_samples
|
|
long, and that the first @c number_of_samples should be spread over @c number_of_cycles.
|
|
|
|
@param number_of_cycles The amount of data to output.
|
|
|
|
@param number_of_samples The number of samples of input data to output.
|
|
|
|
@see @c begin_data
|
|
*/
|
|
void output_data(int number_of_cycles, size_t number_of_samples);
|
|
|
|
/*! A shorthand form for output_data that assumes the number of cycles to output for is the same as the number of samples. */
|
|
void output_data(int number_of_cycles) {
|
|
output_data(number_of_cycles, size_t(number_of_cycles));
|
|
}
|
|
|
|
/*! Outputs a colour burst.
|
|
|
|
@param number_of_cycles The length of the colour burst.
|
|
|
|
@param phase The initial phase of the colour burst in a measuring system with 256 units
|
|
per circle, e.g. 0 = 0 degrees, 128 = 180 degrees, 256 = 360 degree.
|
|
|
|
@param amplitude The amplitude of the colour burst in 1/255ths of the amplitude of the
|
|
positive portion of the wave.
|
|
*/
|
|
void output_colour_burst(int number_of_cycles, uint8_t phase, bool is_alternate_line = false, uint8_t amplitude = DefaultAmplitude);
|
|
|
|
/*! Outputs a colour burst exactly in phase with CRT expectations using the idiomatic amplitude.
|
|
|
|
@param number_of_cycles The length of the colour burst;
|
|
*/
|
|
void output_default_colour_burst(int number_of_cycles, uint8_t amplitude = DefaultAmplitude);
|
|
|
|
/*! Sets the current phase of the colour subcarrier used by output_default_colour_burst.
|
|
|
|
@param phase The normalised instantaneous phase. 0.0f is the start of a colour cycle, 1.0f is the
|
|
end of a colour cycle, 0.25f is a quarter of the way through a colour cycle, etc.
|
|
*/
|
|
void set_immediate_default_phase(float phase);
|
|
|
|
/*! Attempts to allocate the given number of output samples for writing.
|
|
|
|
The beginning of the most recently allocated area is used as the start
|
|
of data written by a call to @c output_data; it is acceptable to write and to
|
|
output less data than the amount requested but that may be less efficient.
|
|
|
|
Allocation should fail only if emulation is running significantly below real speed.
|
|
|
|
@param required_length The number of samples to allocate.
|
|
@returns A pointer to the allocated area if room is available; @c nullptr otherwise.
|
|
*/
|
|
inline uint8_t *begin_data(std::size_t required_length, std::size_t required_alignment = 1) {
|
|
const auto result = scan_target_->begin_data(required_length, required_alignment);
|
|
#ifndef NDEBUG
|
|
// If data was allocated, make a record of how much so as to be able to hold the caller to that
|
|
// contract later. If allocation failed, don't constrain the caller. This allows callers that
|
|
// allocate on demand but may allow one failure to hold for a longer period — e.g. until the
|
|
// next line.
|
|
allocated_data_length_ = result ? required_length : std::numeric_limits<size_t>::max();
|
|
#endif
|
|
return result;
|
|
}
|
|
|
|
/*! Sets the gamma exponent for the simulated screen. */
|
|
void set_input_gamma(float gamma);
|
|
|
|
enum CompositeSourceType {
|
|
/// The composite function provides continuous output.
|
|
Continuous,
|
|
/// The composite function provides discrete output with four unique values per colour cycle.
|
|
DiscreteFourSamplesPerCycle
|
|
};
|
|
|
|
/*! Provides information about the type of output the composite sampling function provides, discrete or continuous.
|
|
|
|
This is necessary because the CRT implementation samples discretely and therefore can use fewer intermediate
|
|
samples if it can exactly duplicate the sampling rate and placement of the composite sampling function.
|
|
|
|
A continuous function is assumed by default.
|
|
|
|
@param type The type of output provided by the function supplied to `set_composite_sampling_function`.
|
|
@param offset_of_first_sample The relative position within a full cycle of the colour subcarrier at which the
|
|
first sample falls. E.g. 0.125 means "at 1/8th of the way through the complete cycle".
|
|
*/
|
|
void set_composite_function_type(CompositeSourceType type, float offset_of_first_sample = 0.0f);
|
|
|
|
/*! Nominates a section of the display to crop to for output. */
|
|
void set_visible_area(Outputs::Display::Rect visible_area);
|
|
|
|
/*! @returns The rectangle describing a subset of the display, allowing for sync periods. */
|
|
Outputs::Display::Rect get_rect_for_area(
|
|
int first_line_after_sync,
|
|
int number_of_lines,
|
|
int first_cycle_after_sync,
|
|
int number_of_cycles,
|
|
float aspect_ratio) const;
|
|
|
|
/*! Sets the CRT delegate; set to @c nullptr if no delegate is desired. */
|
|
inline void set_delegate(Delegate *delegate) {
|
|
delegate_ = delegate;
|
|
}
|
|
|
|
/*! Sets the scan target for CRT output. */
|
|
void set_scan_target(Outputs::Display::ScanTarget *);
|
|
|
|
/*!
|
|
Gets current scan status, with time based fields being in the input scale — e.g. if you're supplying
|
|
86 cycles/line and 98 lines/field then it'll return a field duration of 86*98.
|
|
*/
|
|
Outputs::Display::ScanStatus get_scaled_scan_status() const;
|
|
|
|
/*! Sets the display type that will be nominated to the scan target. */
|
|
void set_display_type(Outputs::Display::DisplayType);
|
|
|
|
/*! Gets the last display type provided to set_display_type. */
|
|
Outputs::Display::DisplayType get_display_type() const;
|
|
|
|
/*! Sets the offset to apply to phase when using the PhaseLinkedLuminance8 input data type. */
|
|
void set_phase_linked_luminance_offset(float);
|
|
|
|
/*! Sets the input data type. */
|
|
void set_input_data_type(Outputs::Display::InputDataType);
|
|
|
|
/*! Sets the output brightness. */
|
|
void set_brightness(float);
|
|
};
|
|
|
|
/*!
|
|
Provides a CRT delegate that will will observe sync mismatches and, when an appropriate threshold is crossed,
|
|
ask its receiver to try a different display frequency.
|
|
*/
|
|
template <typename Receiver> class CRTFrequencyMismatchWarner: public Outputs::CRT::Delegate {
|
|
public:
|
|
CRTFrequencyMismatchWarner(Receiver &receiver) : receiver_(receiver) {}
|
|
|
|
void crt_did_end_batch_of_frames(Outputs::CRT::CRT *, int number_of_frames, int number_of_unexpected_vertical_syncs) final {
|
|
frame_records_[frame_record_pointer_ % frame_records_.size()].number_of_frames = number_of_frames;
|
|
frame_records_[frame_record_pointer_ % frame_records_.size()].number_of_unexpected_vertical_syncs = number_of_unexpected_vertical_syncs;
|
|
++frame_record_pointer_;
|
|
|
|
if(frame_record_pointer_*2 >= frame_records_.size()*3) {
|
|
int total_number_of_frames = 0;
|
|
int total_number_of_unexpected_vertical_syncs = 0;
|
|
for(const auto &record: frame_records_) {
|
|
total_number_of_frames += record.number_of_frames;
|
|
total_number_of_unexpected_vertical_syncs += record.number_of_unexpected_vertical_syncs;
|
|
}
|
|
|
|
if(total_number_of_unexpected_vertical_syncs >= total_number_of_frames >> 1) {
|
|
reset();
|
|
receiver_.register_crt_frequency_mismatch();
|
|
}
|
|
}
|
|
}
|
|
|
|
void reset() {
|
|
for(auto &record: frame_records_) {
|
|
record.number_of_frames = 0;
|
|
record.number_of_unexpected_vertical_syncs = 0;
|
|
}
|
|
}
|
|
|
|
private:
|
|
Receiver &receiver_;
|
|
struct FrameRecord {
|
|
int number_of_frames = 0;
|
|
int number_of_unexpected_vertical_syncs = 0;
|
|
};
|
|
std::array<FrameRecord, 4> frame_records_;
|
|
size_t frame_record_pointer_ = 0;
|
|
};
|
|
|
|
}
|
|
}
|
|
|
|
#endif /* CRT_cpp */
|