Clock Function

API for features of the Clock Maple Function More...

Topics
	VMU Buttons
	VMU button masks

Buzzer
Methods for tone generation.
int	vmu_beep_raw (maple_device_t *dev, uint32_t beep)
	Make a VMU beep (low-level).
int	vmu_beep_waveform (maple_device_t *dev, uint8_t period1, uint8_t duty_cycle1, uint8_t period2, uint8_t duty_cycle2)
	Play VMU Buzzer tone.

Date/Time
Methods for managing date and time.
int	vmu_set_datetime (maple_device_t *dev, time_t unix)
	Set the date and time on the VMU.
int	vmu_get_datetime (maple_device_t *dev, time_t *unix)
	Get the date and time on the VMU.

Input
Methods for polling button states.
void	vmu_set_buttons_enabled (int enable)
	Enable/Disable polling for VMU input.
int	vmu_get_buttons_enabled (void)
	Check whether polling for VMU input has been enabled.

Detailed Description

API for features of the Clock Maple Function

The Clock Maple function provides a high-level API for the following functionality:

• buzzer tone generation
• date/time management
• input/button status

Function Documentation

vmu_beep_raw()

int vmu_beep_raw	(	maple_device_t *	dev,
		uint32_t	beep )

Make a VMU beep (low-level).

This function sends a raw beep to a VMU, causing the speaker to emit a tone noise.

Note

See http://dcemulation.org/phpBB/viewtopic.php?f=29&t=97048 for the original information about beeping.

Warning

This function is submitting raw, encoded values to the VMU. For a more user-friendly API built around generating simple tones, see vmu_beep_waveform().

Parameters

dev	The device to attempt to beep.
beep	The tone to generate. Byte values are as follows: period of square wave 1 duty cycle of square wave 1 period of square wave 2 (ignored by standard mono VMUs) duty cycle of square wave 2 (ignored by standard mono VMUs)

Return values

MAPLE_EOK	On success.
MAPLE_EAGAIN	If the command couldn't be sent. Try again later.
MAPLE_ETIMEOUT	If the command timed out while blocking.

See also

vmu_beep_waveform

vmu_beep_waveform()

int vmu_beep_waveform	(	maple_device_t *	dev,
		uint8_t	period1,
		uint8_t	duty_cycle1,
		uint8_t	period2,
		uint8_t	duty_cycle2 )

Play VMU Buzzer tone.

Sends two different square waves to generate tone(s) on the VMU. Each waveform is configured as shown by the following diagram. On a standard VMU, there is only one piezoelectric buzzer, so waveform 2 is ignored; however, the parameters do support dual-channel stereo in case such a VMU ever does come along.

                       Period
               +---------------------+
               |                     |
HIGH __________            __________
               |          |          |          |
               |          |          |          |
               |__________|          |__________|
LOW
                          |          |
                          +----------+
                           Duty Cycle

                     WAVEFORM

To stop an active tone, one can simply generate a flat wave, such as by submitting both values as 0s.

Warning

Any submitted waveform which has a duty cycle of greater than or equal to its period will result in an invalid waveform being generated and is going to mute or end the tone.

Note

Note that there are no units given for the waveform, so any 3rd party VMU is free to use any base clock rate, potentially resulting in different frequencies (or tones) being generated for the same parameters on different devices.

On the VMU-side, this tone is generated using the VMU's Timer1 peripheral as a pulse generator, which is then fed into its piezoelectric buzzer. The calculated range of the standard VMU, given its 6MHz CF clock running with a divisor of 6 is driving the Timer1 counter, is approximately 3.9KHz-500Khz; however, due to physical characteristics of the buzzer, not every frequency can be produced at a decent volume, so it's recommended that you test your values, using the KOS example found at /examples/dreamcast/vmu/beep.

Parameters

dev	The VMU device to play the tone on
period1	The period or total interval of the first waveform
duty_cycle1	The duty cycle or active interval of the first waveform
period2	The period or total interval of the second waveform (ignored by standard first-party VMUs).
duty_cycle2	The duty cycle or active interval of the second waveform (ignored by standard first-party VMUs).

Return values

MAPLE_EOK	On success.
MAPLE_EAGAIN	If the command couldn't be sent. Try again later.
MAPLE_ETIMEOUT	If the command timed out while blocking.

vmu_get_buttons_enabled()

int vmu_get_buttons_enabled

(

void

)

Check whether polling for VMU input has been enabled.

This function is used to check whether per-frame polling of the VMU's button states has been enabled in the driver.

Note

Polling for VMU input is disabled by default to reduce unnecessary Maple BUS traffic.

See also

vmu_set_buttons_enabled

vmu_get_datetime()

int vmu_get_datetime	(	maple_device_t *	dev,
		time_t *	unix )

Get the date and time on the VMU.

This function gets the VMU's date and time values as a single standard C Unix timestamp.

Note

This is the VMU equivalent of calling time(unix).

Parameters

dev	The device to write to.
unix	Seconds since Unix epoch (set to -1 upon failure)

Return values

MAPLE_EOK	On success.
MAPLE_ETIMEOUT	If the command timed out while blocking.
MAPLE_EFAIL	On errors other than timeout.

See also

vmu_set_datetime

vmu_set_buttons_enabled()

void vmu_set_buttons_enabled

(

int

enable

)

Enable/Disable polling for VMU input.

This function is used to either enable or disable polling the VMU buttons' states for input each frame.

Note

These buttons are not usually accessible to the player; however, several devices, such as the ASCII pad, the arcade pad, and the Retro Fighters controller leave the VMU partially exposed, so that these buttons remain accessible, allowing them to be used as extended controller inputs.

Polling for VMU input is disabled by default to reduce unnecessary Maple BUS traffic.

See also

vmu_get_buttons_enabled

vmu_set_datetime()

int vmu_set_datetime	(	maple_device_t *	dev,
		time_t	unix )

Set the date and time on the VMU.

This function sets the VMU's date and time values to the given standard C Unix timestamp.

Parameters

dev	The device to write to.
unix	Seconds since Unix epoch

Return values

MAPLE_EOK	On success.
MAPLE_ETIMEOUT	If the command timed out while blocking.
MAPLE_EFAIL	On errors other than timeout.

See also

vmu_get_datetime