CLK/Components/AY38910/AY38910.hpp

//
//  AY-3-8910.hpp
//  Clock Signal
//
//  Created by Thomas Harte on 14/10/2016.
//  Copyright 2016 Thomas Harte. All rights reserved.
//

#pragma once

#include "../../Outputs/Speaker/Implementation/BufferSource.hpp"
#include "../../Concurrency/AsyncTaskQueue.hpp"

#include "../../Reflection/Struct.hpp"

namespace GI::AY38910 {

/*!
	A port handler provides all input for an AY's two 8-bit ports, and may optionally receive
	active notification of changes in output.

	Machines with an AY without ports or with nothing wired to them need not supply a port handler.
	Machines that use the AY ports as output but for which polling for changes is acceptable can
	instead use AY38910.get_port_output.
*/
class PortHandler {
public:
	/*!
		Requests the current input on an AY port.

		@param port_b @c true if the input being queried is Port B. @c false if it is Port A.
	*/
	virtual uint8_t get_port_input([[maybe_unused]] bool port_b) {
		return 0xff;
	}

	/*!
		Sets the current output on an AY port.

		@param port_b @c true if the output being posted is Port B. @c false if it is Port A.
		@param value the value now being output.
	*/
	virtual void set_port_output([[maybe_unused]] bool port_b, [[maybe_unused]] uint8_t value) {}
};

/*!
	Names the control lines used as input to the AY, which uses CP1600 bus semantics.
*/
enum ControlLines {
	BC1		= (1 << 0),
	BC2		= (1 << 1),
	BDIR	= (1 << 2)
};

enum class Personality {
	/// Provides 16 volume levels to envelopes.
	AY38910,
	/// Provides 32 volume levels to envelopes.
	YM2149F
};

/*!
	Provides emulation of an AY-3-8910 / YM2149, which is a three-channel sound chip with a
	noise generator and a volume envelope generator, which also provides two bidirectional
	interface ports.

	This AY has an attached mono or stereo mixer.
*/
template <bool stereo> class AY38910SampleSource {
public:
	/// Creates a new AY38910.
	AY38910SampleSource(Personality, Concurrency::AsyncTaskQueue<false> &);
	AY38910SampleSource(const AY38910SampleSource &) = delete;

	/// Sets the value the AY would read from its data lines if it were not outputting.
	void set_data_input(uint8_t r);

	/// Gets the value that would appear on the data lines if only the AY is outputting.
	uint8_t get_data_output() const;

	/// Sets the current control line state, as a bit field.
	void set_control_lines(ControlLines control_lines);

	/// Strobes the reset line.
	void reset();

	/// Sets the current value of the reset line.
	void set_reset(bool reset);

	/*!
		Gets the value that would appear on the requested interface port if it were in output mode.
		@parameter port_b @c true to get the value for Port B, @c false to get the value for Port A.
	*/
	uint8_t get_port_output(bool port_b) const;

	/*!
		Sets the port handler, which will receive a call every time the AY either wants to sample
		input or else declare new output. As a convenience, current port output can be obtained
		without installing a port handler via get_port_output.
	*/
	void set_port_handler(PortHandler *);

	/*!
		Enables or disables stereo output; if stereo output is enabled then also sets the weight of each of the AY's
		channels in each of the output channels.

		If a_left_ = b_left = c_left = a_right = b_right = c_right = 1.0 then you'll get output that's effectively mono.

		a_left = 0.0, a_right = 1.0 will make A full volume on the right output, and silent on the left.

		a_left = 0.5, a_right = 0.5 will make A half volume on both outputs.
	*/
	void set_output_mixing(float a_left, float b_left, float c_left, float a_right = 1.0, float b_right = 1.0, float c_right = 1.0);

	// Sample generation.
	typename Outputs::Speaker::SampleT<stereo>::type level() const;
	void advance();
	bool is_zero_level() const;
	void set_sample_volume_range(std::int16_t range);

private:
	Concurrency::AsyncTaskQueue<false> &task_queue_;

	bool reset_ = false;

	int selected_register_ = 0;
	uint8_t registers_[16]{};
	uint8_t output_registers_[16]{};

	int tone_periods_[3]{};
	int tone_counters_[3]{};
	int tone_outputs_[3]{};

	int noise_period_ = 0;
	int noise_counter_ = 0;
	int noise_shift_register_ = 0xffff;
	int noise_output_ = 0;

	int envelope_period_ = 0;
	int envelope_divider_ = 0;
	int envelope_position_ = 0, envelope_position_mask_ = 0;
	int envelope_shapes_[16][64];
	int envelope_overflow_masks_[16];

	int volumes_[32];

	enum ControlState {
		Inactive,
		LatchAddress,
		Read,
		Write
	} control_state_;

	void select_register(uint8_t r);
	void set_register_value(uint8_t value);
	uint8_t get_register_value() const;

	uint8_t data_input_, data_output_;

	typename Outputs::Speaker::SampleT<stereo>::type output_volume_;

	void update_bus();
	PortHandler *port_handler_ = nullptr;
	void set_port_output(bool port_b);

	void evaluate_output_volume();

	// Output mixing control.
	uint8_t a_left_ = 255, a_right_ = 255;
	uint8_t b_left_ = 255, b_right_ = 255;
	uint8_t c_left_ = 255, c_right_ = 255;

	friend struct State;
};

/// Defines a default AY to be the sample source with a master divider of 4;
/// real AYs have a divide-by-8 step built in but YMs apply only a divide by 4.
///
/// The implementation of AY38910SampleSource combines those two worlds
/// by always applying a divide by four and scaling other things as appropriate.
template <bool stereo> struct AY38910:
	public AY38910SampleSource<stereo>,
	public Outputs::Speaker::SampleSource<AY38910<stereo>, stereo, 4> {

	// Use the same constructor as `AY38910SampleSource` (along with inheriting
	// the rest of its interface).
	using AY38910SampleSource<stereo>::AY38910SampleSource;
};

/*!
	Provides helper code, to provide something closer to the interface exposed by many
	AY-deploying machines of the era.
*/
struct Utility {
	template <typename AY> static void write(AY &ay, bool is_data_write, uint8_t data) {
		ay.set_control_lines(
			GI::AY38910::ControlLines(GI::AY38910::BDIR | GI::AY38910::BC2 | (is_data_write ? 0 : GI::AY38910::BC1))
		);
		ay.set_data_input(data);
		ay.set_control_lines(GI::AY38910::ControlLines(0));
	}

	template <typename AY> static void select_register(AY &ay, uint8_t reg) {
		write(ay, false, reg);
	}

	template <typename AY> static void write_data(AY &ay, uint8_t reg) {
		write(ay, true, reg);
	}

	template <typename AY> static uint8_t read(AY &ay) {
		ay.set_control_lines(GI::AY38910::ControlLines(GI::AY38910::BC2 | GI::AY38910::BC1));
		const uint8_t result = ay.get_data_output();
		ay.set_control_lines(GI::AY38910::ControlLines(0));
		return result;
	}

};

struct State: public Reflection::StructImpl<State> {
	uint8_t registers[16]{};
	uint8_t selected_register = 0;

	// TODO: all audio-production thread state.

	State() {
		if(needs_declare()) {
			DeclareField(registers);
			DeclareField(selected_register);
		}
	}

	template <typename AY> void apply(AY &target) {
		// Establish emulator-thread state
		for(uint8_t c = 0; c < 16; c++) {
			target.select_register(c);
			target.set_register_value(registers[c]);
		}
		target.select_register(selected_register);
	}
};

}