High-level orchestration API for Nintendo DS Pokemon Black/White asset extraction. More...

#include <stddef.h>
#include "gif_pipeline.h"

Data Structures
struct	AnimaExtractOptions
	Configuration parameters for a batch extraction pipeline run. More...

struct	AnimaIdlePreview
	Raw RGBA frame buffer container used by both CLI rendering and GUI preview components. More...

struct	AnimaPreviewOptions
	Configuration context specifying target variant rendering parameters. More...

struct	AnimaPreviewAssetInfo
	Metadata record detailing a discovered asset available for preview and export. More...

Macros
#define	ANIMA_PATH_BUFFER_SIZE 4096

#define	ANIMA_BW_TILE_STRIDE 32

#define	ANIMA_COMPOSITE_MARGIN 8

#define	ANIMA_POKEGRA_PATH "/a/0/0/4"

#define	ANIMA_MAX_PREVIEW_ASSETS 96

#define	ANIMA_PREVIEW_ASSET_NAME_SIZE 96

Typedefs
typedef enum AnimaPreviewAssetType	AnimaPreviewAssetType
	Categorization of discoverable/renderable assets for a species. More...

typedef struct AnimaExtractOptions	AnimaExtractOptions
	Configuration parameters for a batch extraction pipeline run. More...

typedef struct AnimaIdlePreview	AnimaIdlePreview
	Raw RGBA frame buffer container used by both CLI rendering and GUI preview components. More...

typedef struct AnimaPreviewOptions	AnimaPreviewOptions
	Configuration context specifying target variant rendering parameters. More...

typedef struct AnimaPreviewAssetInfo	AnimaPreviewAssetInfo
	Metadata record detailing a discovered asset available for preview and export. More...

Enumerations
enum	AnimaPreviewAssetType { ANIMA_PREVIEW_ASSET_IDLE_GIF = 0 , ANIMA_PREVIEW_ASSET_SPRITESHEET_PNG = 1 , ANIMA_PREVIEW_ASSET_STATIC_IDLE_PNG = 2 , ANIMA_PREVIEW_ASSET_IDLE_BREAK_GIF = 3 , ANIMA_PREVIEW_ASSET_COMPOSED_GIF = 4 , ANIMA_PREVIEW_ASSET_NMAR_ANIMATION_GIF = 5 , ANIMA_PREVIEW_ASSET_NMCR_MAP_GIF = 6 }
	Categorization of discoverable/renderable assets for a species. More...

Functions
void	AnimaExtractOptions_Init (AnimaExtractOptions *options)
	Initialises default options for extraction. More...

int	AnimaBackend_ExtractPokemon (const char rom_path, int species, const char out_dir, const AnimaExtractOptions *options)
	Performs a full asset extraction pipeline for a specific Pokemon species. More...

int	AnimaBackend_BuildFrontNormalGifPath (const char out_dir, char buffer, size_t buffer_size)
	Helper to generate output path for front normal battle idle GIF. More...

int	AnimaBackend_BuildFrontNormalIdleBreakGifPath (const char out_dir, char buffer, size_t buffer_size)
	Helper to generate output path for front normal idle break battle GIF. More...

int	AnimaBackend_BuildFrontNormalStaticPath (const char out_dir, char buffer, size_t buffer_size)
	Helper to generate output path for static normal front static preview PNG. More...

int	AnimaBackend_HasFemaleSprite (const char *rom_path, int species)
	Verifies whether the specified species contains dedicated gender variant graphics. More...

int	AnimaBackend_LoadIdlePreview (const char rom_path, int species, AnimaIdlePreview out_preview)
	High-level loader to construct a basic idle preview (Base front normal). More...

int	AnimaBackend_LoadIdlePreviewExt (const char rom_path, int species, const AnimaPreviewOptions opts, AnimaIdlePreview *out_preview)
	Extended loader for basic idle previews targeting custom shiny, perspective, or form variables. More...

void	AnimaIdlePreview_Free (AnimaIdlePreview *preview)
	Deallocates memory within an AnimaIdlePreview container. More...

int	AnimaBackend_LoadSpritesheetPreview (const char rom_path, int species, AnimaIdlePreview out_preview)
	High-level loader to build the spritesheet PNG preview buffer (Base front normal). More...

int	AnimaBackend_LoadSpritesheetPreviewExt (const char rom_path, int species, const AnimaPreviewOptions opts, AnimaIdlePreview *out_preview)
	Extended spritesheet preview builder with complete variant option mappings. More...

int	AnimaBackend_LoadIdleBreakPreview (const char rom_path, int species, AnimaIdlePreview out_preview)
	High-level loader to build the idle break variant preview buffer. More...

int	AnimaBackend_LoadIdleBreakPreviewExt (const char rom_path, int species, const AnimaPreviewOptions opts, AnimaIdlePreview *out_preview)
	Extended idle break preview builder supporting shiny and perspective parameters. More...

int	AnimaBackend_LoadComposedPreview (const char rom_path, int species, int idle_repetitions, AnimaIdlePreview out_preview)
	High-level loader to build unified composed idle-to-break animation loop. More...

int	AnimaBackend_LoadComposedPreviewExt (const char rom_path, int species, int idle_repetitions, const AnimaPreviewOptions opts, AnimaIdlePreview *out_preview)
	Extended composed idle-to-break preview builder supporting complete variant selections. More...

int	AnimaBackend_LoadNmarAnimationPreviewExt (const char rom_path, int species, int animation_index, const AnimaPreviewOptions opts, AnimaIdlePreview *out_preview)
	Builds custom NMAR-selected animation preview from direct timeline records. More...

int	AnimaBackend_LoadNmcrMapPreviewExt (const char rom_path, int species, int map_index, const AnimaPreviewOptions opts, AnimaIdlePreview *out_preview)
	Builds direct static NMCR-selected composite layout preview frame. More...

int	AnimaBackend_ListPreviewAssets (const char rom_path, int species, const AnimaPreviewOptions opts, AnimaPreviewAssetInfo out_assets, int max_assets, int out_count)
	Scans active Nitro headers in Pokegra member block to discover and populate all available assets. More...

int	AnimaBackend_ExportCurrentAsset (const char rom_path, int species, int preview_mode, const AnimaPreviewOptions opts, const char *out_path)
	Renders and exports the active target preview buffer to a local file. More...

Detailed Description

High-level orchestration API for Nintendo DS Pokemon Black/White asset extraction.

This module coordinates NDS ROM filesystem reading, NARC parsing, LZ decompression, and calling the sub-parsers (NCGR, NCLR, NCER, NANR, NMCR, NMAR) to assemble and export sprite sheets, static previews, composed animations, and manifests.

Macro Definition Documentation

◆ ANIMA_BW_TILE_STRIDE

#define ANIMA_BW_TILE_STRIDE 32

Hardcoded width stride of NCGR tiles for Gen 5 Pokegra NARCs.

◆ ANIMA_COMPOSITE_MARGIN

#define ANIMA_COMPOSITE_MARGIN 8

Safety margin in pixels around composed canvas rendering bounds.

◆ ANIMA_MAX_PREVIEW_ASSETS

#define ANIMA_MAX_PREVIEW_ASSETS 96

Maximum amount of discoverable and previewable assets per species.

◆ ANIMA_PATH_BUFFER_SIZE

#define ANIMA_PATH_BUFFER_SIZE 4096

Buffer size for absolute and relative paths.

◆ ANIMA_POKEGRA_PATH

#define ANIMA_POKEGRA_PATH "/a/0/0/4"

Virtual NDS path to Pokegra NARC archive inside Black/White filesystem.

◆ ANIMA_PREVIEW_ASSET_NAME_SIZE

#define ANIMA_PREVIEW_ASSET_NAME_SIZE 96

Maximum label size of discovered preview assets.

Typedef Documentation

◆ AnimaExtractOptions

typedef struct AnimaExtractOptions AnimaExtractOptions

Configuration parameters for a batch extraction pipeline run.

◆ AnimaIdlePreview

typedef struct AnimaIdlePreview AnimaIdlePreview

Raw RGBA frame buffer container used by both CLI rendering and GUI preview components.

◆ AnimaPreviewAssetInfo

typedef struct AnimaPreviewAssetInfo AnimaPreviewAssetInfo

Metadata record detailing a discovered asset available for preview and export.

◆ AnimaPreviewAssetType

typedef enum AnimaPreviewAssetType AnimaPreviewAssetType

Categorization of discoverable/renderable assets for a species.

◆ AnimaPreviewOptions

typedef struct AnimaPreviewOptions AnimaPreviewOptions

Configuration context specifying target variant rendering parameters.

Enumeration Type Documentation

◆ AnimaPreviewAssetType

enum AnimaPreviewAssetType

Categorization of discoverable/renderable assets for a species.

Enumerator
ANIMA_PREVIEW_ASSET_IDLE_GIF	Standard animated battle idle GIF.
ANIMA_PREVIEW_ASSET_SPRITESHEET_PNG	Recomposed tile sheet containing indexed sprite frames.
ANIMA_PREVIEW_ASSET_STATIC_IDLE_PNG	First idle frame static high-quality PNG.
ANIMA_PREVIEW_ASSET_IDLE_BREAK_GIF	Secondary/rare idle animation played after repeated cycles.
ANIMA_PREVIEW_ASSET_COMPOSED_GIF	Combined timeline loop merging repetitions of idle + break.
ANIMA_PREVIEW_ASSET_NMAR_ANIMATION_GIF	Arbitrary direct NMAR labeled animation index preview.
ANIMA_PREVIEW_ASSET_NMCR_MAP_GIF	Direct rendering of individual NMCR sprite maps.

Function Documentation

◆ AnimaBackend_BuildFrontNormalGifPath()

int AnimaBackend_BuildFrontNormalGifPath	(	const char *	out_dir,
		char *	buffer,
		size_t	buffer_size
	)

Helper to generate output path for front normal battle idle GIF.

Parameters

out_dir	Root output directory.
buffer	Output path container.
buffer_size	Size of destination path buffer.

Returns: 0 on success; negative on buffer overflow.

◆ AnimaBackend_BuildFrontNormalIdleBreakGifPath()

int AnimaBackend_BuildFrontNormalIdleBreakGifPath	(	const char *	out_dir,
		char *	buffer,
		size_t	buffer_size
	)

Helper to generate output path for front normal idle break battle GIF.

Parameters

out_dir	Root output directory.
buffer	Output path container.
buffer_size	Size of destination path buffer.

Returns: 0 on success; negative on buffer overflow.

◆ AnimaBackend_BuildFrontNormalStaticPath()

int AnimaBackend_BuildFrontNormalStaticPath	(	const char *	out_dir,
		char *	buffer,
		size_t	buffer_size
	)

Helper to generate output path for static normal front static preview PNG.

Parameters

out_dir	Root output directory.
buffer	Output path container.
buffer_size	Size of destination path buffer.

Returns: 0 on success; negative on buffer overflow.

◆ AnimaBackend_ExportCurrentAsset()

int AnimaBackend_ExportCurrentAsset	(	const char *	rom_path,
		int	species,
		int	preview_mode,
		const AnimaPreviewOptions *	opts,
		const char *	out_path
	)

Renders and exports the active target preview buffer to a local file.

Parameters

rom_path	Path to the Pokemon Black/White .nds ROM.
species	National Dex ID.
preview_mode	Selected preview type matching AnimaPreviewAssetType.
opts	Rendering configurations.
out_path	Path to output destination file (PNG or GIF).

Returns: 0 on success; negative on write or export failure.

◆ AnimaBackend_ExtractPokemon()

int AnimaBackend_ExtractPokemon	(	const char *	rom_path,
		int	species,
		const char *	out_dir,
		const AnimaExtractOptions *	options
	)

Performs a full asset extraction pipeline for a specific Pokemon species.

Parameters

rom_path	Path to the Pokemon Black/White .nds ROM.
species	National Dex ID of the Pokemon (1 to 649).
out_dir	Root directory where asset files will be exported.
options	Extraction parameters selecting formats and blocks.

Returns: 0 on success; negative values indicate internal parsing/write failures.

◆ AnimaBackend_HasFemaleSprite()

int AnimaBackend_HasFemaleSprite	(	const char *	rom_path,
		int	species
	)

Verifies whether the specified species contains dedicated gender variant graphics.

Parameters

rom_path	Path to the Pokemon Black/White .nds ROM.
species	National Dex ID of the Pokemon.

Returns: 1 if female-specific member sprites exist; 0 otherwise.

◆ AnimaBackend_ListPreviewAssets()

int AnimaBackend_ListPreviewAssets	(	const char *	rom_path,
		int	species,
		const AnimaPreviewOptions *	opts,
		AnimaPreviewAssetInfo *	out_assets,
		int	max_assets,
		int *	out_count
	)

Scans active Nitro headers in Pokegra member block to discover and populate all available assets.

Parameters

rom_path	Path to the Pokemon Black/White .nds ROM.
species	National Dex ID.
opts	Discovery configurations (side, gender, form, shiny context).
out_assets	Array pointer to populate with discovered asset info.
max_assets	Capacity limit of the out_assets array.
out_count	Output pointer filled with total count of discovered assets.

Returns: 0 on success; negative on parsing failure.

◆ AnimaBackend_LoadComposedPreview()

int AnimaBackend_LoadComposedPreview	(	const char *	rom_path,
		int	species,
		int	idle_repetitions,
		AnimaIdlePreview *	out_preview
	)

High-level loader to build unified composed idle-to-break animation loop.

Parameters

rom_path	Path to the Pokemon Black/White .nds ROM.
species	National Dex ID.
idle_repetitions	Pre-calculated or target number of idle iterations before break.
out_preview	Output container.

Returns: 0 on success; negative on failure.

◆ AnimaBackend_LoadComposedPreviewExt()

int AnimaBackend_LoadComposedPreviewExt	(	const char *	rom_path,
		int	species,
		int	idle_repetitions,
		const AnimaPreviewOptions *	opts,
		AnimaIdlePreview *	out_preview
	)

Extended composed idle-to-break preview builder supporting complete variant selections.

Parameters

rom_path	Path to the Pokemon Black/White .nds ROM.
species	National Dex ID.
idle_repetitions	Target number of idle iterations before break.
opts	Rendering configurations.
out_preview	Output container.

Returns: 0 on success; negative on failure.

◆ AnimaBackend_LoadIdleBreakPreview()

int AnimaBackend_LoadIdleBreakPreview	(	const char *	rom_path,
		int	species,
		AnimaIdlePreview *	out_preview
	)

High-level loader to build the idle break variant preview buffer.

Parameters

rom_path	Path to the Pokemon Black/White .nds ROM.
species	National Dex ID.
out_preview	Output container.

Returns: 0 on success; negative on failure.

◆ AnimaBackend_LoadIdleBreakPreviewExt()

int AnimaBackend_LoadIdleBreakPreviewExt	(	const char *	rom_path,
		int	species,
		const AnimaPreviewOptions *	opts,
		AnimaIdlePreview *	out_preview
	)

Extended idle break preview builder supporting shiny and perspective parameters.

Parameters

rom_path	Path to the Pokemon Black/White .nds ROM.
species	National Dex ID.
opts	Rendering configurations.
out_preview	Output container.

Returns: 0 on success; negative on failure.

◆ AnimaBackend_LoadIdlePreview()

int AnimaBackend_LoadIdlePreview	(	const char *	rom_path,
		int	species,
		AnimaIdlePreview *	out_preview
	)

High-level loader to construct a basic idle preview (Base front normal).

Parameters

rom_path	Path to the Pokemon Black/White .nds ROM.
species	National Dex ID.
out_preview	Output container to hold RGBA buffer.

Returns: 0 on success; negative on parsing/decompress errors.

◆ AnimaBackend_LoadIdlePreviewExt()

int AnimaBackend_LoadIdlePreviewExt	(	const char *	rom_path,
		int	species,
		const AnimaPreviewOptions *	opts,
		AnimaIdlePreview *	out_preview
	)

Extended loader for basic idle previews targeting custom shiny, perspective, or form variables.

Parameters

rom_path	Path to the Pokemon Black/White .nds ROM.
species	National Dex ID.
opts	Rendering configurations.
out_preview	Output container to hold RGBA buffer.

Returns: 0 on success; negative on failure.

◆ AnimaBackend_LoadNmarAnimationPreviewExt()

int AnimaBackend_LoadNmarAnimationPreviewExt	(	const char *	rom_path,
		int	species,
		int	animation_index,
		const AnimaPreviewOptions *	opts,
		AnimaIdlePreview *	out_preview
	)

Builds custom NMAR-selected animation preview from direct timeline records.

Parameters

rom_path	Path to the Pokemon Black/White .nds ROM.
species	National Dex ID.
animation_index	Direct NMAR animation timeline sequence index.
opts	Rendering configurations.
out_preview	Output container.

Returns: 0 on success; negative on failure.

◆ AnimaBackend_LoadNmcrMapPreviewExt()

int AnimaBackend_LoadNmcrMapPreviewExt	(	const char *	rom_path,
		int	species,
		int	map_index,
		const AnimaPreviewOptions *	opts,
		AnimaIdlePreview *	out_preview
	)

Builds direct static NMCR-selected composite layout preview frame.

Parameters

rom_path	Path to the Pokemon Black/White .nds ROM.
species	National Dex ID.
map_index	Direct NMCR map record index.
opts	Rendering configurations.
out_preview	Output container.

Returns: 0 on success; negative on failure.

◆ AnimaBackend_LoadSpritesheetPreview()

int AnimaBackend_LoadSpritesheetPreview	(	const char *	rom_path,
		int	species,
		AnimaIdlePreview *	out_preview
	)

High-level loader to build the spritesheet PNG preview buffer (Base front normal).

Parameters

rom_path	Path to the Pokemon Black/White .nds ROM.
species	National Dex ID.
out_preview	Output container.

Returns: 0 on success; negative on failure.

◆ AnimaBackend_LoadSpritesheetPreviewExt()

int AnimaBackend_LoadSpritesheetPreviewExt	(	const char *	rom_path,
		int	species,
		const AnimaPreviewOptions *	opts,
		AnimaIdlePreview *	out_preview
	)

Extended spritesheet preview builder with complete variant option mappings.

Parameters

rom_path	Path to the Pokemon Black/White .nds ROM.
species	National Dex ID.
opts	Rendering configurations.
out_preview	Output container.

Returns: 0 on success; negative on failure.

◆ AnimaExtractOptions_Init()

void AnimaExtractOptions_Init ( AnimaExtractOptions * options )

Initialises default options for extraction.

Parameters

options Pointer to options struct to populate.

◆ AnimaIdlePreview_Free()

void AnimaIdlePreview_Free ( AnimaIdlePreview * preview )

Deallocates memory within an AnimaIdlePreview container.

Parameters

preview Pointer to preview struct to clean.

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ ANIMA_BW_TILE_STRIDE

◆ ANIMA_COMPOSITE_MARGIN

◆ ANIMA_MAX_PREVIEW_ASSETS

◆ ANIMA_PATH_BUFFER_SIZE

◆ ANIMA_POKEGRA_PATH

◆ ANIMA_PREVIEW_ASSET_NAME_SIZE

Typedef Documentation

◆ AnimaExtractOptions

◆ AnimaIdlePreview

◆ AnimaPreviewAssetInfo

◆ AnimaPreviewAssetType

◆ AnimaPreviewOptions

Enumeration Type Documentation

◆ AnimaPreviewAssetType

Function Documentation

◆ AnimaBackend_BuildFrontNormalGifPath()

◆ AnimaBackend_BuildFrontNormalIdleBreakGifPath()

◆ AnimaBackend_BuildFrontNormalStaticPath()

◆ AnimaBackend_ExportCurrentAsset()

◆ AnimaBackend_ExtractPokemon()

◆ AnimaBackend_HasFemaleSprite()

◆ AnimaBackend_ListPreviewAssets()

◆ AnimaBackend_LoadComposedPreview()

◆ AnimaBackend_LoadComposedPreviewExt()

◆ AnimaBackend_LoadIdleBreakPreview()

◆ AnimaBackend_LoadIdleBreakPreviewExt()

◆ AnimaBackend_LoadIdlePreview()

◆ AnimaBackend_LoadIdlePreviewExt()

◆ AnimaBackend_LoadNmarAnimationPreviewExt()

◆ AnimaBackend_LoadNmcrMapPreviewExt()

◆ AnimaBackend_LoadSpritesheetPreview()

◆ AnimaBackend_LoadSpritesheetPreviewExt()

◆ AnimaExtractOptions_Init()

◆ AnimaIdlePreview_Free()