Utility Functions

Functions
LIBX52UTIL_API int	libx52util_convert_utf8_string (const uint8_t *input, uint8_t *output, size_t *len)
	Convert UTF8 string to X52 character map.

MFD line scrolling
Step a 16-cell window over a virtual tape of X52 MFD display bytes (same encoding as libx52_set_text / libx52util_convert_utf8_string output). Cell count follows convert semantics (multi-byte glyphs use multiple cells). Default wrap: unless LIBX52UTIL_SCROLL_SINGLE_PASS is set, each libx52util_scroll_next() advances the window modulo the tape period so the marquee loops until libx52util_scroll_reset() or libx52util_scroll_free(). These routines are not thread-safe; callers must serialize access to a given libx52util_scroll_state.
enum	libx52util_scroll_flags { }
	Bitwise flags for libx52util_scroll_new(). More...
typedef struct libx52util_scroll	libx52util_scroll_state
LIBX52UTIL_API int	libx52util_scroll_new (libx52util_scroll_state **state, const uint8_t *utf8_string, libx52util_scroll_flags flags)
	Allocate scroll state from a UTF-8 string.
LIBX52UTIL_API void	libx52util_scroll_free (libx52util_scroll_state **state)
	Free scroll state.
LIBX52UTIL_API int	libx52util_scroll_reset (libx52util_scroll_state *state)
	Rewind the scroll window to the initial position.
LIBX52UTIL_API int	libx52util_scroll_next (libx52util_scroll_state *state, uint8_t display[16])
	Emit the next 16-byte MFD line for the current window.

Detailed Description

These functions simplify some of the data handling for MFD & LED control.

Typedef Documentation

libx52util_scroll_state

typedef struct libx52util_scroll libx52util_scroll_state

Opaque scroll state allocated by libx52util_scroll_new().

Enumeration Type Documentation

libx52util_scroll_flags

enum libx52util_scroll_flags

Bitwise flags for libx52util_scroll_new().

Combine enumerator values with |. Each enumerator is a distinct power of two.

Enumerator
LIBX52UTIL_SCROLL_IN	Virtual prefix of 16 ASCII spaces before converted text (scroll-in).
LIBX52UTIL_SCROLL_OUT	Virtual suffix of 16 ASCII spaces after converted text (scroll-out).
LIBX52UTIL_SCROLL_LTR	Horizontal direction opposite the default ticker (default advances the window so content appears to move left; with this flag, content moves right).
LIBX52UTIL_SCROLL_SINGLE_PASS	Disable looping: after one full cycle over distinct window positions, the window clamps at the end; further libx52util_scroll_next() returns -EAGAIN until libx52util_scroll_reset() or libx52util_scroll_new(). Without this flag, the window wraps continuously. Implies LIBX52UTIL_SCROLL_OUT.

Function Documentation

libx52util_convert_utf8_string()

LIBX52UTIL_API int libx52util_convert_utf8_string	(	const uint8_t *	input,
		uint8_t *	output,
		size_t *	len
	)

Convert UTF8 string to X52 character map.

This function takes in a UTF-8 string and converts it to the character map used by the X52Pro MFD. Unrecognized characters are silently dropped.

Parameters

[in]	input	Input string in UTF-8. Must be NUL-terminated
[out]	output	Output buffer
[in,out]	len	Length of output buffer

Returns

0 on success, -EINVAL on invalid parameters, -E2BIG if the buffer filled up before converting the entire string.

libx52util_scroll_free()

LIBX52UTIL_API void libx52util_scroll_free

(

libx52util_scroll_state **

state

)

Free scroll state.

If state is non-NULL and *state is non-NULL, frees *state and sets *state to NULL. If state is NULL, no operation is performed.

libx52util_scroll_new()

LIBX52UTIL_API int libx52util_scroll_new	(	libx52util_scroll_state **	state,
		const uint8_t *	utf8_string,
		libx52util_scroll_flags	flags
	)

Allocate scroll state from a UTF-8 string.

Converts utf8_string with libx52util_convert_utf8_string() using an internal 256-byte output buffer. Converted length is in display cells, same as libx52util_convert_utf8_string()'s output length.

Parameters

[out]	state	Receives the new state; must not be NULL.
[in]	utf8_string	NUL-terminated UTF-8 input; must not be NULL.
[in]	flags	Bitwise OR of libx52util_scroll_flags values.

Returns

0 if the full string fit the internal buffer; -E2BIG if conversion stopped early but *state is still a valid object for scroll_next/reset/free (truncated prefix only). On -EINVAL or -ENOMEM, *state is left unchanged. -EINVAL: NULL state, NULL utf8_string, or invalid argument use. -ENOMEM: allocation failed.

If the converted text length is at most 16 cells, or the full virtual tape (optional 16-space prefix + text + optional 16-space suffix) is at most 16 cells long, there is no window motion: libx52util_scroll_next() returns 0 once with a padded line, then -EAGAIN without advancing.

libx52util_scroll_next()

LIBX52UTIL_API int libx52util_scroll_next	(	libx52util_scroll_state *	state,
		uint8_t	display[16]
	)

Emit the next 16-byte MFD line for the current window.

Writes up to 16 display bytes into display (ASCII space padding where the window extends past the virtual tape). Returns 0 when the new frame differs from the last frame returned with 0; updates the last-emitted snapshot and advances the internal window for the following call. Returns -EAGAIN when the candidate frame equals that last snapshot: display is not modified, the snapshot is unchanged, but the window index still advances (wrap or single-pass clamp) so uniform runs eventually change at boundaries.

When there is no scrolling (see libx52util_scroll_new): the first call returns 0; later calls return -EAGAIN without advancing the window.

Parameters

[in]	state	Scroll state; must not be NULL.
[out]	display	16-byte output buffer; must not be NULL.

Returns

0 on a new visible frame, -EAGAIN when unchanged or static repeat, -EINVAL if state or display is NULL.

libx52util_scroll_reset()

LIBX52UTIL_API int libx52util_scroll_reset

(

libx52util_scroll_state *

state

)

Rewind the scroll window to the initial position.

Parameters

[in]

state

Scroll state from libx52util_scroll_new().

Returns

0 on success, -EINVAL if state is NULL.