sprite_composer.h File Reference

Layout compositing, affine transformations, and frame rendering engine. More...

#include "common.h"
#include "ppm.h"
#include "ncer.h"
#include "nanr.h"
#include "nmcr.h"
#include "nmar.h"
#include "ncgr.h"
#include "nclr.h"
#include "coords.h"

Go to the source code of this file.

Data Structures
struct	GlobalOam
	Assembled global OAM record with complete transformations applied. More...
struct	ComposerTransform
	Affine transformation parameters passed down during scene orchestration. More...

Typedefs
typedef struct GlobalOam	GlobalOam
	Assembled global OAM record with complete transformations applied. More...
typedef struct ComposerTransform	ComposerTransform
	Affine transformation parameters passed down during scene orchestration. More...

Functions
void	Composer_ClearPixels (RgbaColor *pixels, int width, int height)
	Fills the RGBA canvas with transparent pixels. More...
void	Composer_ComputeBounds (const NcerFile *ncer, const NanrFile *nanr, const NmcrMap *map, int tick, int *out_min_x, int *out_min_y, int *out_max_x, int *out_max_y, const CoordFile *coords)
	Calculates the extreme bounding box coordinates for a specific animation frame tick. More...
void	Composer_ComputeBoundsWithTransform (const NcerFile *ncer, const NanrFile *nanr, const NmcrMap *map, int tick, int *out_min_x, int *out_min_y, int *out_max_x, int *out_max_y, const CoordFile *coords, const ComposerTransform *parent_transform)
	Bounding box calculator with parent timeline transformations. More...
void	Composer_ComputeBoundsRange (const NcerFile *ncer, const NanrFile *nanr, const NmcrMap *map, int start_frame, int frame_count, int *out_min_x, int *out_min_y, int *out_max_x, int *out_max_y, const CoordFile *coords, int delay_cs)
	Calculates bounding box encapsulating a full range of animation frames. More...
int	Composer_RenderFrameIndexed (const NcerFile *ncer, const NanrFile *nanr, const NmcrMap *map, const NcgrImage *ncgr, const NclrPalette *palette, int tick, int tile_stride, int min_x, int min_y, int width, int height, int margin, u8 *out_indices, const CoordFile *coords)
	Composites a frame into an indexed 8-bit color-indexed layout canvas. More...
int	Composer_RenderFrameIndexedWithTransform (const NcerFile *ncer, const NanrFile *nanr, const NmcrMap *map, const NcgrImage *ncgr, const NclrPalette *palette, int tick, int tile_stride, int min_x, int min_y, int width, int height, int margin, u8 *out_indices, const CoordFile *coords, const ComposerTransform *parent_transform)
	Composites a transformed frame into an 8bpp color-indexed layout canvas. More...
int	Composer_RenderFrameRgba (const NcerFile *ncer, const NanrFile *nanr, const NmcrMap *map, const NcgrImage *ncgr, const NclrPalette *palette, int tick, int tile_stride, const char *label, RgbaColor **out_pixels, int *out_width, int *out_height, const CoordFile *coords)
	Renders a composite frame directly into a 32-bit RGBA pixel array. More...
int	Composer_CropIndexedFrames (const u8 *frames, int frame_count, int width, int height, u8 **out_frames, int *out_width, int *out_height)
	Crops transparent margins from index-compiled spritesheet animation loops. More...
void	Composer_ComputeUnionBounds (const NcerFile *ncer, const NanrFile *nanr, const NmcrMap *map_a, int map_a_frame_count, const NmcrMap *map_b, int map_b_frame_count, int *out_min_x, int *out_min_y, int *out_max_x, int *out_max_y, const CoordFile *coords, int delay_cs)
	Computes combined bounding box that fits two animation sets sharing a unified canvas space. More...
int	Composer_RenderComposedAnimation (const NcerFile *ncer, const NanrFile *nanr, const NmcrMap *idle_map, const NmcrMap *break_map, const NcgrImage *ncgr, const NclrPalette *palette, int idle_repetitions, int tile_stride, int margin, u8 **out_frames, int *out_frame_count, int *out_width, int *out_height, const CoordFile *coords, int delay_cs)
	Renders a complete loop merging a base idle animation and a break sequence. More...
int	Composer_RenderComposedAnimationTimeline (const NcerFile *ncer, const NanrFile *nanr, const NmcrFile *nmcr, const NmarFile *nmar, const NmcrMap *idle_map, const NmcrMap *break_map, int idle_animation_index, int break_animation_index, const NcgrImage *ncgr, const NclrPalette *palette, int idle_repetitions, int tile_stride, int margin, u8 **out_frames, int *out_frame_count, int *out_width, int *out_height, const CoordFile *coords, int delay_cs)
	Timeline-driven composed loop renderer that applies full parent translation transforms. More...
int	Composer_ComputeIdleRepetitions (const NanrFile *nanr, const NmcrMap *idle_map)
	Computes optimal number of idle loops before transition so loop length is ~3 seconds. More...
int	Composer_ComputeNmarIdleRepetitions (const NmarFile *nmar, int animation_index)
	Timeline-driven optimal idle loops counter before playing break sequence. More...

Detailed Description

Layout compositing, affine transformations, and frame rendering engine.

This module performs sprite compositing (OAM blitting) by reading cell layout tables (NCER), mapping tiles (NCGR) and palettes (NCLR), applying animation keyframes (NANR), and combining multi-sprite scene positioning records (NMCR) and timeline events (NMAR).

Typedef Documentation

ComposerTransform

typedef struct ComposerTransform ComposerTransform

Affine transformation parameters passed down during scene orchestration.

GlobalOam

typedef struct GlobalOam GlobalOam

Assembled global OAM record with complete transformations applied.

Function Documentation

Composer_ClearPixels()

void Composer_ClearPixels	(	RgbaColor *	pixels,
		int	width,
		int	height
	)

Fills the RGBA canvas with transparent pixels.

Parameters

pixels	Target pixel buffer.
width	Canvas width.
height	Canvas height.

Composer_ComputeBounds()

void Composer_ComputeBounds	(	const NcerFile *	ncer,
		const NanrFile *	nanr,
		const NmcrMap *	map,
		int	tick,
		int *	out_min_x,
		int *	out_min_y,
		int *	out_max_x,
		int *	out_max_y,
		const CoordFile *	coords
	)

Calculates the extreme bounding box coordinates for a specific animation frame tick.

Parameters

ncer	Parsed Cell file.
nanr	Parsed Animation sequence.
map	Screen layout composite map.
tick	Current animation frame index/tick.
out_min_x	Output for minimum horizontal bound.
out_min_y	Output for minimum vertical bound.
out_max_x	Output for maximum horizontal bound.
out_max_y	Output for maximum vertical bound.
coords	Battle coordinates offset configuration (unused in placement checks).

Composer_ComputeBoundsRange()

void Composer_ComputeBoundsRange	(	const NcerFile *	ncer,
		const NanrFile *	nanr,
		const NmcrMap *	map,
		int	start_frame,
		int	frame_count,
		int *	out_min_x,
		int *	out_min_y,
		int *	out_max_x,
		int *	out_max_y,
		const CoordFile *	coords,
		int	delay_cs
	)

Calculates bounding box encapsulating a full range of animation frames.

Parameters

ncer	Cell metadata.
nanr	Animation sequence.
map	Map layout.
start_frame	Beginning index.
frame_count	Amount of frames to scan.
out_min_x	Output minimum horizontal coordinate.
out_min_y	Output minimum vertical coordinate.
out_max_x	Output maximum horizontal coordinate.
out_max_y	Output maximum vertical coordinate.
coords	Coordinate metadata anchors.
delay_cs	Base frame duration delay in centiseconds.

Composer_ComputeBoundsWithTransform()

void Composer_ComputeBoundsWithTransform	(	const NcerFile *	ncer,
		const NanrFile *	nanr,
		const NmcrMap *	map,
		int	tick,
		int *	out_min_x,
		int *	out_min_y,
		int *	out_max_x,
		int *	out_max_y,
		const CoordFile *	coords,
		const ComposerTransform *	parent_transform
	)

Bounding box calculator with parent timeline transformations.

Parameters

ncer	Cell details.
nanr	Animation details.
map	Map layout.
tick	Animation frame tick.
out_min_x	Minimum X coordinate bound output.
out_min_y	Minimum Y coordinate bound output.
out_max_x	Maximum X coordinate bound output.
out_max_y	Maximum Y coordinate bound output.
coords	Battle coordinates.
parent_transform	Active parent scaling and rotation matrices.

Composer_ComputeIdleRepetitions()

int Composer_ComputeIdleRepetitions	(	const NanrFile *	nanr,
		const NmcrMap *	idle_map
	)

Computes optimal number of idle loops before transition so loop length is ~3 seconds.

Parameters

nanr	Animation frames sequence.
idle_map	Default battle idle map.

Returns

Repetitions value (clamped between 1 and 10).

Composer_ComputeNmarIdleRepetitions()

int Composer_ComputeNmarIdleRepetitions	(	const NmarFile *	nmar,
		int	animation_index
	)

Timeline-driven optimal idle loops counter before playing break sequence.

Parameters

nmar	Timeline track details.
animation_index	Labeled idle animation timeline track index.

Returns

Repetitions count (clamped 1 to 10).

Composer_ComputeUnionBounds()

void Composer_ComputeUnionBounds	(	const NcerFile *	ncer,
		const NanrFile *	nanr,
		const NmcrMap *	map_a,
		int	map_a_frame_count,
		const NmcrMap *	map_b,
		int	map_b_frame_count,
		int *	out_min_x,
		int *	out_min_y,
		int *	out_max_x,
		int *	out_max_y,
		const CoordFile *	coords,
		int	delay_cs
	)

Computes combined bounding box that fits two animation sets sharing a unified canvas space.

Parameters

ncer	Cell details.
nanr	Animation details.
map_a	First map configuration.
map_a_frame_count	Frame count of map A.
map_b	Second map configuration.
map_b_frame_count	Frame count of map B.
out_min_x	Output minimum X bound.
out_min_y	Output minimum Y bound.
out_max_x	Output maximum X bound.
out_max_y	Output maximum Y bound.
coords	Coordinate metadata anchors.
delay_cs	Base timeline centisecond step.

Composer_CropIndexedFrames()

int Composer_CropIndexedFrames	(	const u8 *	frames,
		int	frame_count,
		int	width,
		int	height,
		u8 **	out_frames,
		int *	out_width,
		int *	out_height
	)

Crops transparent margins from index-compiled spritesheet animation loops.

Parameters

frames	Multi-frame sequential 8bpp color buffer.
frame_count	Number of frames inside the buffer.
width	Raw source canvas width.
height	Raw source canvas height.
out_frames	Newly allocated cropped multi-frame indexed buffer output.
out_width	Width of the cropped bounding box.
out_height	Height of the cropped bounding box.

Returns

0 on success; negative on invalid bounds or memory exception.

Composer_RenderComposedAnimation()

int Composer_RenderComposedAnimation	(	const NcerFile *	ncer,
		const NanrFile *	nanr,
		const NmcrMap *	idle_map,
		const NmcrMap *	break_map,
		const NcgrImage *	ncgr,
		const NclrPalette *	palette,
		int	idle_repetitions,
		int	tile_stride,
		int	margin,
		u8 **	out_frames,
		int *	out_frame_count,
		int *	out_width,
		int *	out_height,
		const CoordFile *	coords,
		int	delay_cs
	)

Renders a complete loop merging a base idle animation and a break sequence.

Parameters

ncer	Cell tables.
nanr	Animation sequences.
idle_map	Battle idle composite map.
break_map	Battle break candidate map.
ncgr	Tile pixels.
palette	Palette data.
idle_repetitions	Pre-calculated iterations of the idle loop before playing break.
tile_stride	Target tile stride.
margin	Safety boundary padding.
out_frames	Newly allocated cropped multi-frame indexed index buffer.
out_frame_count	Frame count of generated loop.
out_width	Bounded canvas width.
out_height	Bounded canvas height.
coords	Coordinates anchors.
delay_cs	Centisecond duration.

Returns

0 on success; negative on rendering failure.

Composer_RenderComposedAnimationTimeline()

int Composer_RenderComposedAnimationTimeline	(	const NcerFile *	ncer,
		const NanrFile *	nanr,
		const NmcrFile *	nmcr,
		const NmarFile *	nmar,
		const NmcrMap *	idle_map,
		const NmcrMap *	break_map,
		int	idle_animation_index,
		int	break_animation_index,
		const NcgrImage *	ncgr,
		const NclrPalette *	palette,
		int	idle_repetitions,
		int	tile_stride,
		int	margin,
		u8 **	out_frames,
		int *	out_frame_count,
		int *	out_width,
		int *	out_height,
		const CoordFile *	coords,
		int	delay_cs
	)

Timeline-driven composed loop renderer that applies full parent translation transforms.

Parameters

ncer	Cell layouts.
nanr	Animation sequences.
nmcr	Direct layouts map file.
nmar	High-level animation timeline tracks.
idle_map	Default idle map.
break_map	Labeled break map.
idle_animation_index	Labeled idle NMAR index.
break_animation_index	Labeled break NMAR index.
ncgr	Indexed tile sheet.
palette	Color palettes.
idle_repetitions	Desired loops of idle sequence.
tile_stride	NCGR stride.
margin	Bounding padding.
out_frames	Pointer to cropped multi-frame index buffer output.
out_frame_count	Frame count of compiled timeline loop.
out_width	Width of bounding canvas.
out_height	Height of bounding canvas.
coords	Coordinates anchors.
delay_cs	Timeline time step.

Returns

0 on success; negative on rendering failure.

Composer_RenderFrameIndexed()

int Composer_RenderFrameIndexed	(	const NcerFile *	ncer,
		const NanrFile *	nanr,
		const NmcrMap *	map,
		const NcgrImage *	ncgr,
		const NclrPalette *	palette,
		int	tick,
		int	tile_stride,
		int	min_x,
		int	min_y,
		int	width,
		int	height,
		int	margin,
		u8 *	out_indices,
		const CoordFile *	coords
	)

Composites a frame into an indexed 8-bit color-indexed layout canvas.

Parameters

ncer	Cells file.
nanr	Animations sequence.
map	Layout mapping.
ncgr	Character tile image data.
palette	Palettes array.
tick	Active frame tick.
tile_stride	Target tile stride (e.g. 32).
min_x	Minimum horizontal coordinate anchor.
min_y	Minimum vertical coordinate anchor.
width	Target canvas rendering width.
height	Target canvas rendering height.
margin	Pixel safety margin size.
out_indices	Preallocated output buffer to receive color index bytes.
coords	Coordinate metadata.

Returns

0 on success; negative on rendering exception.

Composer_RenderFrameIndexedWithTransform()

int Composer_RenderFrameIndexedWithTransform	(	const NcerFile *	ncer,
		const NanrFile *	nanr,
		const NmcrMap *	map,
		const NcgrImage *	ncgr,
		const NclrPalette *	palette,
		int	tick,
		int	tile_stride,
		int	min_x,
		int	min_y,
		int	width,
		int	height,
		int	margin,
		u8 *	out_indices,
		const CoordFile *	coords,
		const ComposerTransform *	parent_transform
	)

Composites a transformed frame into an 8bpp color-indexed layout canvas.

Parameters

ncer	Cells file.
nanr	Animations file.
map	Map layout.
ncgr	Tile pixels.
palette	Palettes bank.
tick	Active tick.
tile_stride	NCGR stride.
min_x	Horizontal canvas rendering offset.
min_y	Vertical canvas rendering offset.
width	Canvas width.
height	Canvas height.
margin	Canvas safety padding.
out_indices	Output destination buffer for indexed color mapping.
coords	Coordinates anchors.
parent_transform	Active timeline transforms.

Returns

0 on success; negative on rendering failure.

Composer_RenderFrameRgba()

int Composer_RenderFrameRgba	(	const NcerFile *	ncer,
		const NanrFile *	nanr,
		const NmcrMap *	map,
		const NcgrImage *	ncgr,
		const NclrPalette *	palette,
		int	tick,
		int	tile_stride,
		const char *	label,
		RgbaColor **	out_pixels,
		int *	out_width,
		int *	out_height,
		const CoordFile *	coords
	)

Renders a composite frame directly into a 32-bit RGBA pixel array.

Parameters

ncer	Cell details.
nanr	Animation frames.
map	Map configurations.
ncgr	Tile pixels.
palette	Palette registers.
tick	Frame tick index.
tile_stride	NCGR tile width stride.
label	Debug output identifier.
out_pixels	Pointer filled with newly allocated RGBA pixel buffer on success.
out_width	Width of generated RGBA frame.
out_height	Height of generated RGBA frame.
coords	Coordinate metadata anchors.

Returns

0 on success; negative on rendering exception.