Exposes functions for the media output handler. More...

#include <notcurses/notcurses.h>
#include <stdbool.h>

Data Structures
struct	loaded_visual_s
	Structure to represent a loaded visual. More...

Typedefs
typedef enum media_blitter	media_blitter_t
	Media blitter options (rendering method)
typedef struct loaded_visual_s	loaded_visual_t
	Structure to represent a loaded visual.

Enumerations
enum	scale_type_t { SCALE_NONE , SCALE_PRESERVE , SCALE_STRETCH , SCALE_CELL , SCALE_FULLSCREEN }
enum	media_type_t { MEDIA_PNG , MEDIA_GIF , MEDIA_MP4 , MEDIA_UNSUPPORTED }
enum	media_blitter { MEDIA_BLITTER_DEFAULT = NCBLIT_DEFAULT , MEDIA_BLITTER_ASCII = NCBLIT_1x1 , MEDIA_BLITTER_HALF = NCBLIT_2x1 , MEDIA_BLITTER_QUAD = NCBLIT_2x2 , MEDIA_BLITTER_BRAILLE = NCBLIT_BRAILLE , MEDIA_BLITTER_PIXEL = NCBLIT_PIXEL }
	Media blitter options (rendering method) More...

Functions
bool	init_media_output (void)
	Initialize the media output handler.
void	shutdown_media_output (void)
	Shutdown the media output handler.
void	media_cleanup (void)
void	destroy_media (loaded_visual_t *media)
	Frees the memory associated with a loaded media resource.
bool	refresh_media_display (void)
	Force a refresh of the media display.
loaded_visual_t *	load_media (const char *filename)
	load a media resource from file they can be different types (PNG, GIF, MP4)
loaded_visual_t *	ready_media (const char *filename, int x, int y, int height, int width, scale_type_t scale_type)
	Prepares a media resource for display.
bool	unload_media (const char *filename)
	Unload a specific media resource.
bool	preload_media (const char *filename)
	Preload a media file into memory.
bool	reload_media_after_resize (void)
	Reload media after terminal resize.
bool	media_output_render (loaded_visual_t *media)
	Display a loaded media file on its assigned plane.
bool	media_output_render_next_frame (loaded_visual_t *media)
	Display the next frame of an animation or video.
bool	media_output_can_display_images (void)
	Check if the notcurses implementation supports image loading.
bool	media_output_can_display_videos (void)
	Check if the notcurses implementation supports video loading.
void	setup_scaling_options (loaded_visual_t *visual, scale_type_t scale_type, int target_width, int target_height)
	Enable different scaling options for the loaded visual.
bool	directory_exists (const char *path)
	checks if a directory exists
media_type_t	get_file_type (const char *filename)
	Get the media type based on the file extension.
bool	is_file_extension (const char filename, const char extension)
	Check if a filename has a specific extension.
char *	build_filepath (const char *filename, media_type_t media_type)
	Build a file path for the specified media type.

Detailed Description

Exposes functions for the media output handler.

Definition in file media_output_handler.h.

Typedef Documentation

◆ loaded_visual_t

typedef struct loaded_visual_s loaded_visual_t

Structure to represent a loaded visual.

This is an opaque structure that encapsulates a Notcurses visual.

Enumeration Type Documentation

◆ media_blitter

enum media_blitter

Media blitter options (rendering method)

Definition at line 31 of file media_output_handler.h.

                           {
    MEDIA_BLITTER_DEFAULT = NCBLIT_DEFAULT,// Use terminal's best option
    MEDIA_BLITTER_ASCII = NCBLIT_1x1,      // Use ASCII only
    MEDIA_BLITTER_HALF = NCBLIT_2x1,       // Use half blocks (▀ ▄)
    MEDIA_BLITTER_QUAD = NCBLIT_2x2,       // Use quadrant blocks (▖ ▗ ▘ ▙)
    MEDIA_BLITTER_BRAILLE = NCBLIT_BRAILLE,// Use braille (⠀⠁⠂⠃...)
    MEDIA_BLITTER_PIXEL = NCBLIT_PIXEL,    // Use pixel graphics if available
} media_blitter_t;

◆ media_type_t

enum media_type_t

Definition at line 21 of file media_output_handler.h.

             {
    MEDIA_PNG,
    MEDIA_GIF,
    MEDIA_MP4,
    MEDIA_UNSUPPORTED
} media_type_t;

◆ scale_type_t

enum scale_type_t

Definition at line 12 of file media_output_handler.h.

             {
    SCALE_NONE,     // No scaling, use original size
    SCALE_PRESERVE, // Scale preserving aspect ratio
    SCALE_STRETCH,  // Stretch to exact dimensions
    SCALE_CELL,     // Scale to fit in a single cell
    SCALE_FULLSCREEN// Scale to fill the entire screen
} scale_type_t;

Function Documentation

◆ build_filepath()

char * build_filepath	(	const char *	filename,
		media_type_t	media_type )

Build a file path for the specified media type.

Parameters

filename	File name to build the path for
media_type	Type of media (PNG, GIF, MP4)

Returns: Pointer to the constructed file path

Definition at line 433 of file media_output_handler.c.

                                                                    {
    // Allocate memory for the path
    char* filepath = malloc(MAX_PATH_LEN);
    if (!filepath) {
        log_msg(ERROR, "media_output", "Failed to allocate memory for file path");
        return NULL;
    }
 
    // Build the path based on the media media_type
    const char* subdir = "";
    switch (media_type) {
        case MEDIA_PNG:
            subdir = "png/";
            break;
        case MEDIA_GIF:
            subdir = "gif/";
            break;
        case MEDIA_MP4:
            subdir = "mp4/";
            break;
        default:
            break;
    }
 
    // Construct the full path
    snprintf(filepath, MAX_PATH_LEN, "%s%s%s", MEDIA_PATH, subdir, filename);
 
    return filepath;
}

◆ destroy_media()

void destroy_media ( loaded_visual_t * media )

Frees the memory associated with a loaded media resource.

Parameters

media Pointer to the loaded media instance to destroy

Definition at line 76 of file media_output_handler.c.

                                           {
    free_media_resource(media);
}

◆ directory_exists()

bool directory_exists ( const char * path )

checks if a directory exists

Parameters

path	Path to the directory

Returns: success or failure

◆ get_file_type()

media_type_t get_file_type ( const char * filename )

Get the media type based on the file extension.

Parameters

filename File name to check

Returns: Media type (PNG, GIF, MP4, or UNSUPPORTED)

Definition at line 403 of file media_output_handler.c.

                                                 {
    if (is_file_extension(filename, ".png")) {
        return MEDIA_PNG;
    } else if (is_file_extension(filename, ".gif")) {
        return MEDIA_GIF;
    } else if (is_file_extension(filename, ".mp4")) {
        return MEDIA_MP4;
    } else {
        log_msg(ERROR, "media_output", "Unsupported file extension for: %s", filename);
        return MEDIA_UNSUPPORTED;
    }
}

◆ init_media_output()

bool init_media_output ( void )

Initialize the media output handler.

Must be called after the common output handler is initialized.

Returns: true on success, false on failure

Definition at line 37 of file media_output_handler.c.

                             {
    if (!nc) {
        log_msg(ERROR, "media_output", "Null Notcurses instance provided");
        return false;
    }
 
    if (!stdplane) {
        log_msg(ERROR, "media_output", "Null standard plane provided");
        return false;
    }
 
    // Initialize resources array
    memset(resources, 0, sizeof(resources));
    resource_count = 0;
 
    // Ensure the media directory exists
    //TODO: implement directory_exists function
    /*if (!directory_exists(MEDIA_PATH)) {
        log_msg(ERROR, "media_output", "Failed to ensure media directory exists");
    }*/
 
    return true;
}

◆ is_file_extension()

bool is_file_extension	(	const char *	filename,
		const char *	extension )

Check if a filename has a specific extension.

Parameters

filename	File name to check
extension	Extension to check for

Returns: true if the file has the specified extension, false otherwise

Definition at line 417 of file media_output_handler.c.

                                                                    {
    if (!filename || !extension) {
        return false;
    }
 
    size_t filename_len = strlen(filename);
    size_t ext_len = strlen(extension);
 
    if (filename_len < ext_len) {
        return false;
    }
 
    return strncasecmp(filename + filename_len - ext_len, extension, ext_len) == 0;
}

◆ load_media()

loaded_visual_t * load_media ( const char * filename )

load a media resource from file they can be different types (PNG, GIF, MP4)

Parameters

filename File name to load

Returns: Pointer to a loaded visual instance

Definition at line 99 of file media_output_handler.c.

                                                  {
    // Validate parameters
    if (!filename) {
        log_msg(ERROR, "media_output", "Invalid filename for load_media");
        return NULL;
    }
 
    media_type_t media_type = get_file_type(filename);
 
    // Build the full file path
    char* filepath = build_filepath(filename, media_type);
    if (!filepath) {
        return NULL;
    }
 
    // Check if we already have this resource loaded
    for (int i = 0; i < resource_count; i++) {
        if (strcmp(resources[i].path, filepath) == 0) {
            free(filepath);
            return &resources[i];// Return existing resource
        }
    }
 
    // Make sure we have space for a new resource
    if (resource_count >= MAX_RESOURCES) {
        // Could implement a LRU cache here, but for simplicity, just fail
        free(filepath);
        return NULL;
    }
 
    // Load the visual from file with detailed error handling
    struct ncvisual* visual = ncvisual_from_file(filepath);
    if (!visual) {
        log_msg(ERROR, "media_output", "Failed to load media: %s (check if file exists)", filepath);
        return NULL;
    }
 
    // Allocate a new resource
    loaded_visual_t* resource = &resources[resource_count];
    if (!resource) {
        log_msg(ERROR, "media_output", "Failed to allocate memory for loaded visual");
        ncvisual_destroy(visual);
        return NULL;
    }
    resource_count++;
 
    // Initialize the structure
    memset(resource, 0, sizeof(loaded_visual_t));
    resource->visual = visual;
    resource->plane = NULL;// Will be created when displayed
 
    // Set resource properties
    resource->media_type = media_type;
    resource->is_loaded = true;
    resource->is_playing = false;
    resource->path = strdup(filepath);
    if (!resource->path) {
        log_msg(ERROR, "media_output", "Failed to store path");
        ncvisual_destroy(visual);
        resource_count--;
        free(filepath);
        return NULL;
    }
 
    // Get visual dimensions
    struct ncvisual_options vopts = {0};
    struct ncvgeom geom = {0};
    int geo_ret = ncvisual_geom(nc, visual, &vopts, &geom);
 
    if (geo_ret) {
        log_msg(WARNING, "media_output", "Failed to get visual geometry, using default dimensions");
        // Use defaults if we can't get the dimensions
        resource->og_width = 20; // Default width
        resource->og_height = 20;// Default height
    } else {
        // Store dimensions with detailed logging
        if (geom.pixx <= 0 || geom.pixy <= 0) {
            log_msg(WARNING, "media_output", "Invalid media dimensions: %dx%d, using defaults",
                    geom.pixx, geom.pixy);
            resource->og_width = 20; // Default width
            resource->og_height = 20;// Default height
        } else {
            resource->og_width = geom.pixx; // Width in pixels
            resource->og_height = geom.pixy;// Height in pixels
        }
    }
 
    // set attributes based on media media_type
    switch (media_type) {
        case MEDIA_PNG:
            resource->frames = 1;// Single frame for static images
            break;
        case MEDIA_GIF:
            // Count frames by decoding the whole GIF
            resource->frames = 0;
            while (ncvisual_decode(visual) != 1) {
                resource->frames++;
            }
            // Reset to first frame
            ncvisual_destroy(visual);
            resource->visual = ncvisual_from_file(filepath);
            if (!resource->visual) {
                log_msg(ERROR, "media_output", "Failed to reload GIF after frame counting");
                free(resource->path);
                resource_count--;
                free(filepath);
                return NULL;
            }
            break;
        case MEDIA_MP4:
            // MP4 handling would go here
            log_msg(ERROR, "media_output", "MP4 loading not implemented yet");
            ncvisual_destroy(visual);
            resource_count--;
            free(resource->path);
            break;
        default:
            log_msg(ERROR, "media_output", "Unsupported media media_type");
            ncvisual_destroy(visual);
            free(filepath);
            return NULL;
    }
 
    free(filepath);
    return resource;
}

◆ media_cleanup()

void media_cleanup ( void )

Definition at line 66 of file media_output_handler.c.

                         {
    // Free all loaded resources
    for (int i = 0; i < resource_count; i++) {
        if (resources[i].is_loaded) {
            free_media_resource(&resources[i]);
        }
    }
    resource_count = 0;
}

◆ media_output_can_display_images()

bool media_output_can_display_images ( void )

Check if the notcurses implementation supports image loading.

Returns: true if supported, false otherwise

◆ media_output_can_display_videos()

bool media_output_can_display_videos ( void )

Check if the notcurses implementation supports video loading.

Returns: true if supported, false otherwise

◆ media_output_render()

bool media_output_render ( loaded_visual_t * media )

Display a loaded media file on its assigned plane.

Parameters

media Pointer to a loaded media instance

Returns: true on success, false on failure

◆ media_output_render_next_frame()

bool media_output_render_next_frame ( loaded_visual_t * media )

Display the next frame of an animation or video.

Parameters

media Pointer to a loaded media instance

Returns: true on success, false on failure or end of media

◆ preload_media()

bool preload_media ( const char * filename )

Preload a media file into memory.

Parameters

filename File name to preload

Returns: true on success, false on failure

◆ ready_media()

loaded_visual_t * ready_media	(	const char *	filename,
		int	x,
		int	y,
		int	height,
		int	width,
		scale_type_t	scale_type )

Prepares a media resource for display.

Parameters

filename	File name to load
x	X coordinate in terminal cells
y	Y coordinate in terminal cells
height	Height in terminal cells
width	Width in terminal cells (0 for auto)
scale_type	Scaling type to apply

Returns: Pointer to a loaded visual instance

Definition at line 226 of file media_output_handler.c.

                                                                                                                 {
    // Validate parameters
    if (!filename) {
        log_msg(ERROR, "media_output", "Null filename for display_media");
        return NULL;
    }
 
    // Allow height=0 for fullscreen and preserving aspect ratio
    if (height < 0) {
        log_msg(ERROR, "media_output", "Invalid height (%d) for display_media", height);
        return NULL;
    }
 
    // Load the media
    loaded_visual_t* resource = load_media(filename);
    if (!resource || !resource->is_loaded) {
        log_msg(ERROR, "media_output", "Failed to load media: %s", filename);
        return NULL;
    }
 
    // Set up scaling
    setup_scaling_options(resource, scale_type, width, height);
 
    // Set coordinates
    resource->options.y = y;
    resource->options.x = x;
 
    // Clean up existing plane if needed
    if (resource->plane) {
        ncplane_erase(resource->plane);// Clear contents first
        notcurses_render(nc);          // Update display
        ncplane_destroy(resource->plane);
        resource->plane = NULL;
    }
 
    return resource;
}

◆ refresh_media_display()

bool refresh_media_display ( void )

Force a refresh of the media display.

Returns: bool indicating success or failure

Definition at line 81 of file media_output_handler.c.

                                 {
    //TODO: fix
 
    // Force a redraw of the terminal with error checking
    bool result = notcurses_render(nc);
 
    if (!result) {
        log_msg(ERROR, "media_output", "Failed to refresh media display");
    }
 
    return result;
}

◆ reload_media_after_resize()

bool reload_media_after_resize ( void )

Reload media after terminal resize.

Returns: true on success, false on failure

◆ setup_scaling_options()

void setup_scaling_options	(	loaded_visual_t *	visual,
		scale_type_t	scale_type,
		int	target_width,
		int	target_height )

Enable different scaling options for the loaded visual.

Parameters

visual	Pointer to the loaded visual instance
scale_type	Scaling type to apply
target_width	Width to scale to
target_height	Height to scale to

Definition at line 333 of file media_output_handler.c.

                                                                {
    // Clear options first
    memset(&visual->options, 0, sizeof(visual->options));
 
    // Apply scaling based on type
    switch (scale_type) {
        case SCALE_PRESERVE:
            // Scale preserving aspect ratio
            visual->options.scaling = NCSCALE_SCALE;
            // When using NCSCALE_SCALE, a zero value for lenx/leny means auto-scale
            visual->options.leny = target_height > 0 ? target_height : 0;
            visual->options.lenx = target_width > 0 ? target_width : 0;
            break;
 
        case SCALE_STRETCH:
            // Stretch to exact dimensions
            if (target_width > 0 && target_height > 0) {
                visual->options.scaling = NCSCALE_STRETCH;
                visual->options.leny = target_height;
                visual->options.lenx = target_width;
            } else {
                // Fall back to no scaling if dimensions are invalid
                visual->options.scaling = NCSCALE_NONE;
            }
            break;
 
        case SCALE_CELL:
            // Scale to fit in a single cell
            visual->options.scaling = NCSCALE_SCALE;
            visual->options.leny = 1;
            visual->options.lenx = 1;
            break;
 
        case SCALE_FULLSCREEN:
            // Scale to fit the entire terminal
            visual->options.scaling = NCSCALE_STRETCH;
            // Get terminal dimensions
            int screen_width, screen_height;
            if (get_screen_dimensions(&screen_width, &screen_height)) {
                visual->options.leny = screen_height;
                visual->options.lenx = screen_width;
            } else {
                // Fallback to original dimensions
                visual->options.leny = visual->og_height;
                visual->options.lenx = visual->og_width;
                log_msg(WARNING, "media_output", "Could not get screen dimensions, using original size");
            }
            break;
 
        case SCALE_NONE:
        default:
            // No scaling
            visual->options.scaling = NCSCALE_NONE;
            break;
    }
 
    // Set blitter to a reliable one
    visual->options.blitter = NCBLIT_2x1;
}

◆ shutdown_media_output()

void shutdown_media_output ( void )

Shutdown the media output handler.

Cleans up resources used by the media output handler.

Definition at line 62 of file media_output_handler.c.

                                 {
    media_cleanup();
}

◆ unload_media()

bool unload_media ( const char * filename )

Unload a specific media resource.

Parameters

filename File name to unload

Returns: true on success, false on failure

Definition at line 269 of file media_output_handler.c.

                                        {
    if (!filename) {
        return false;
    }
 
    // Look for the resource in our cache
    for (int i = 0; i < resource_count; i++) {
        if (strcmp(resources[i].path, filename) == 0) {
            free_media_resource(&resources[i]);
 
            // Shift other resources if this isn't the last one
            if (i < resource_count - 1) {
                memmove(&resources[i], &resources[i + 1], (resource_count - i - 1) * sizeof(loaded_visual_t));
            }
 
            resource_count--;
            return true;
        }
    }
 
    return false;
}

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ loaded_visual_t

Enumeration Type Documentation

◆ media_blitter

◆ media_type_t

◆ scale_type_t

Function Documentation

◆ build_filepath()

◆ destroy_media()

◆ directory_exists()

◆ get_file_type()

◆ init_media_output()

◆ is_file_extension()

◆ load_media()

◆ media_cleanup()

◆ media_output_can_display_images()

◆ media_output_can_display_videos()

◆ media_output_render()

◆ media_output_render_next_frame()

◆ preload_media()

◆ ready_media()

◆ refresh_media_display()

◆ reload_media_after_resize()

◆ setup_scaling_options()

◆ shutdown_media_output()

◆ unload_media()