vmupro_utils.h File Reference

VMUPro Utility Functions. More...

#include "stdint.h"
#include "stdbool.h"
#include <stddef.h>

Go to the source code of this file.

Data Structures
struct	vmupro_emubrowser_settings_t
	Settings structure for the emulator browser. More...

Functions
void	vmupro_sleep_ms (uint32_t milliseconds)
	Sleep for a specified number of milliseconds.
uint64_t	vmupro_get_time_us (void)
	Get current time in microseconds.
void	vmupro_delay_us (uint64_t delay_us)
	Delay for a specified number of microseconds.
void	vmupro_delay_ms (uint64_t delay_ms)
	Delay for a specified number of milliseconds.
int	vmupro_snprintf (char *buffer, size_t size, const char *format,...)
	Safe string formatting function.
void *	vmupro_malloc (size_t size)
	Memory allocation with SPIRAM preference.
int	vmupro_emubrowser_init (vmupro_emubrowser_settings_t settings)
	Initialize the emulator browser.
void	vmupro_emubrowser_render_contents (char *launchfile)
	Render the emulator browser and get selected file.

Detailed Description

VMUPro Utility Functions.

This header provides utility functions for the VMUPro SDK. It includes common helper functions for timing, delays, and other general-purpose operations.

Author

8BitMods

Version

1.0.0

Date

2025-06-17

Copyright

Copyright (c) 2025 APPCAKE Limited. Distributed under the MIT License.

Definition in file vmupro_utils.h.

Function Documentation

vmupro_delay_ms()

void vmupro_delay_ms

(

uint64_t

delay_ms

)

Delay for a specified number of milliseconds.

Blocks execution for the specified duration in milliseconds. This function provides millisecond precision timing control.

Parameters

delay_ms

Duration to delay in milliseconds

Note

Uses millisecond precision (less precise than vmupro_delay_us)

If delay_ms is 0, the function returns immediately

Useful for less timing-critical applications

// Simple periodic updates
while (running) {
    update_logic();
    vmupro_delay_ms(100); // Wait 100ms between updates
}
 
// Precise timing with microsecond conversion
vmupro_delay_ms(50); // Wait 50 milliseconds

vmupro_delay_us()

void vmupro_delay_us

(

uint64_t

delay_us

)

Delay for a specified number of microseconds.

Blocks execution for the specified duration in microseconds. This function provides precise timing control for frame rate limiting and delays.

Parameters

delay_us

Duration to delay in microseconds

Note

More precise than vmupro_sleep_ms() for timing-critical applications

If delay_us is 0, the function returns immediately

Uses high-resolution timing for accurate delays

// Frame rate limiting to 60 FPS
uint64_t frame_duration_us = 1000000 / 60; // 16666 microseconds per frame
 
while (game_running) {
    uint64_t frame_start = vmupro_get_time_us();
    
    // Render frame
    render_game_frame();
    
    // Calculate remaining time for this frame
    uint64_t elapsed = vmupro_get_time_us() - frame_start;
    if (elapsed < frame_duration_us) {
        vmupro_delay_us(frame_duration_us - elapsed);
    }
}

vmupro_emubrowser_init()

int vmupro_emubrowser_init

(

vmupro_emubrowser_settings_t

settings

)

Initialize the emulator browser.

Initializes the emulator file browser with the specified settings. This must be called before using vmupro_emubrowser_render_contents().

Parameters

settings

Browser configuration settings

Returns

0 on success, -1 on failure

Note

The browser instance is a singleton - only one can exist at a time

All string pointers in settings must remain valid during browser usage

vmupro_emubrowser_settings_t settings = {
    .title = "Select ROM",
    .rootPath = "/storage/roms/",
    .filterExtension = ".nes"
};
if (vmupro_emubrowser_init(settings) == 0) {
    // Browser initialized successfully
}

vmupro_emubrowser_render_contents()

void vmupro_emubrowser_render_contents

(

char *

launchfile

)

Render the emulator browser and get selected file.

Displays the file browser interface and allows the user to navigate and select a file. The function blocks until the user makes a selection or cancels the operation.

Parameters

[out]

launchfile

Buffer to receive the selected file path Must be at least 256 bytes in size

Note

The browser must be initialized with vmupro_emubrowser_init() first

If user cancels, launchfile will contain an empty string

The returned path is relative to the root path specified in settings

char selected_file[256];
vmupro_emubrowser_render_contents(selected_file);
if (strlen(selected_file) > 0) {
    // User selected a file
    printf("Selected: %s\n", selected_file);
} else {
    // User cancelled
}

vmupro_get_time_us()

uint64_t vmupro_get_time_us

(

void

)

Get current time in microseconds.

Returns the current system time in microseconds since boot. This function provides high-resolution timing for precise measurements.

Returns

Current time in microseconds (64-bit unsigned integer)

Note

Time starts from 0 at system boot

Provides microsecond precision for accurate timing

Useful for performance measurement and frame timing

// Measure execution time
uint64_t start_time = vmupro_get_time_us();
 
// ... do some work ...
 
uint64_t end_time = vmupro_get_time_us();
uint64_t elapsed = end_time - start_time;
vmupro_log(VMUPRO_LOG_INFO, "TIMING", "Operation took %llu microseconds", elapsed);

vmupro_malloc()

void * vmupro_malloc

(

size_t

size

)

Memory allocation with SPIRAM preference.

Allocates memory with preference for SPIRAM (external RAM) when available. Falls back to internal RAM if SPIRAM allocation fails or is unavailable. This provides better memory utilization by using external RAM for large allocations.

Parameters

size	Number of bytes to allocate

Returns

Pointer to allocated memory on success, NULL on failure

Note

Memory allocated with this function should be freed with standard free()

SPIRAM access is slower than internal RAM but provides more capacity

Use this for large buffers, graphics data, or non-performance-critical allocations

uint8_t* buffer = (uint8_t*)vmupro_malloc(1024);
if (buffer) {
    // Use buffer...
    free(buffer);
}

vmupro_sleep_ms()

void vmupro_sleep_ms

(

uint32_t

milliseconds

)

Sleep for a specified number of milliseconds.

Suspends the current task/thread for the specified duration. This function provides a blocking delay that can be used for timing control in applications.

Parameters

milliseconds

The number of milliseconds to sleep (maximum 1000ms per call)

Note

This function will block the calling thread for the specified duration

The actual sleep duration may be slightly longer due to system scheduling

Maximum sleep duration is 1000ms per call. For longer delays, call multiple times

vmupro_snprintf()

int vmupro_snprintf	(	char *	buffer,
		size_t	size,
		const char *	format,
			...
	)

Safe string formatting function.

Formats and stores a string in a buffer with guaranteed null-termination. This is a safe alternative to sprintf that prevents buffer overflows.

Parameters

buffer	Destination buffer for the formatted string
size	Size of the destination buffer
format	Format string (printf-style)
...	Variable arguments for the format string

Returns

Number of characters that would have been written (excluding null terminator), or negative value on error

Note

The output is always null-terminated if size > 0

If the formatted string exceeds the buffer size, it will be truncated

A warning is logged if truncation occurs

char buffer[100];
int score = 1234;
vmupro_snprintf(buffer, sizeof(buffer), "Score: %d", score);