cdlv API reference

Refer to sample.c and res/sample/sample.cdlv for a documented sample desktop app with SDL2.

Core

cdlv_error

typedef enum {
    cdlv_ok,               // No error
    cdlv_memory_error,     // Dynamic memory allocation returned NULL
    cdlv_file_error,       // File system returned error when trying to access file
    cdlv_read_error,       // Error detected while reading file
    cdlv_video_error,      // Error detected while decoding video
    cdlv_parse_error,      // Error detected in parsed script file
    cdlv_fatal_error,      // Unrecoverable error
    cdlv_callback_error,   // User callback returned with error value
} cdlv_error;

Enum that is returned from most of cdlv's functions.

cdlv

typedef struct cdlv {
    cdlv_log_config log_config;       // Logging callbacks set by user
    cdlv_error_config error_config;   // Error callbacks set by user
    cdlv_image_config image_config;   // Image callbacks set by user
    cdlv_video_config video_config;   // Video callbacks set by user
    cdlv_user_config user_config;     // User action callbacks set by user

    bool end;                         // Whether script has ended

    cdlv_dict* scenes;                // Dictionary of scenes read from script
    uint16_t scene_count;             // Count of scenes in script

    uint16_t current_line;            // Current line of scenes text
    uint16_t current_scene_index;     // Current scene's index
    void* current_scene;              // Pointer to current scene
    void* current_bg;                 // Pointer to current background resource

    char* resources_path;             // Global resources path read from script
    cdlv_dict* resources;             // Dictionary of global resources
} cdlv;

Base struct. cdlv's handler or manager - however you want to call it.

cdlv_set_script

cdlv_error cdlv_set_script(cdlv* base, const char* path);

Initialize cdlv base structure:

• Allocate data structures
• Open and parse script file into data structures
• Load global resources

Parameters:

• base - a pointer to cdlv base
• path - string with script file path

cdlv_unset_script

cdlv_error cdlv_unset_script(cdlv* base);

Unload and free all allocated resources from script (global and current scene's).

Parameters:

• base - a pointer to cdlv base

cdlv_render

cdlv_error cdlv_render(cdlv* base);

Call rendering callbacks based on current resource.

Parameters:

• base - a pointer to cdlv base

cdlv_user_update

cdlv_error cdlv_user_update(cdlv* base);

Update script to next line and handle it's behavior. Calls user update callback.

Parameters:

• base - a pointer to cdlv base

Callbacks

cdlv_log_*

typedef void (*cdlv_log_callback)(char* buf);
typedef struct cdlv_log_config {
    cdlv_log_callback callback;   // Called when cdlv wants to log information
    char* buffer;                 // Buffer to use in callback
    size_t buffer_size;           // Buffer's size
} cdlv_log_config;

Example:

static inline void log_cb(char* buf) {
    printf("cdlv: %s\n", buf);
}

cdlv_error_*

typedef void (*cdlv_error_callback)(cdlv_error error, void* user_data);
typedef struct cdlv_error_config {
    cdlv_error_callback callback;   // Called when cdlv_error is returned
    void* user_data;                // User data
} cdlv_error_config;

Example:

static inline void error_cb(cdlv_error error, void* user_data) {
    if(error == cdlv_ok) return;
    switch(error) {
        case cdlv_ok: printf("CDLV OK\n"); break;
        case cdlv_memory_error:	   puts("CDLV Memory error"); break;
        case cdlv_file_error:       puts("CDLV File error"); break;
        case cdlv_read_error:       puts("CDLV Read error"); break;
        case cdlv_parse_error:      puts("CDLV Parse error"); break;
        case cdlv_video_error:      puts("CDLV Video error"); break;
        case cdlv_fatal_error:      puts("CDLV Fatal error"); break;
        case cdlv_callback_error:   puts("Callback provided by user returned with error"); break;
    }
    exit(1);
}

cdlv_image_*

typedef void* (*cdlv_image_load_cb)(const char* path, void* user_data);
typedef void (*cdlv_image_render_cb)(void* image, void* user_data);
typedef void (*cdlv_image_free_cb)(void* image);
typedef struct cdlv_image_config {
    cdlv_image_load_cb load_callback;       // Called when allocating image resource
    cdlv_image_render_cb render_callback;   // Called when rendering image
    cdlv_image_free_cb free_callback;       // Called when freeing image resource
    void* user_data;                        // User data
} cdlv_image_config;

Example:

static inline void* image_load_cb(const char* path, void* user_data) {
    SDL_Renderer* renderer = (SDL_Renderer*)user_data;
    SDL_Texture* texture = IMG_LoadTexture(renderer, path);
    if(!texture) return NULL;
    return texture;
}

static inline void image_render_cb(void* image, void* user_data) {
    SDL_Renderer* renderer = (SDL_Renderer*)user_data;
    SDL_Texture* texture = (SDL_Texture*)image;
    SDL_RenderCopy(renderer, texture, NULL, NULL);
}

static inline void image_free_cb(void* image) {
    SDL_Texture* texture = (SDL_Texture*)image;
    SDL_DestroyTexture(texture);
}

cdlv_video_*

typedef void* (*cdlv_video_load_cb)(const uint64_t width, const uint64_t height, void* user_data);
typedef void (*cdlv_video_update_cb)(cdlv_yuv_plane plane, cdlv_yuv_pitch pitch, void* texture, void* user_data);
typedef void (*cdlv_video_free_cb)(void* texture);
typedef struct cdlv_video_config {
    cdlv_video_load_cb load_callback;       // Called when allocating texture with streaming capabilities
    cdlv_video_free_cb free_callback;       // Called when freeing texture with streaming capabilities
    cdlv_video_update_cb update_callback;   // Called when texture is to be updated with new frame
    void* user_data;                        // User data
    bool change_frame_bool;                 // Whether new frame can be loaded and displayed
} cdlv_video_config;

Example:

static inline void* video_load_cb(const uint64_t width, const uint64_t height, void* user_data) {
    SDL_Renderer* renderer = (SDL_Renderer*)user_data;
    SDL_Texture* texture = SDL_CreateTexture(renderer, SDL_PIXELFORMAT_YV12, SDL_TEXTUREACCESS_STREAMING, width, height);
    if(!texture) return NULL;
    return texture;
}

static inline void video_free_cb(void* texture) {
    SDL_Texture* _texture = (SDL_Texture*)texture;
    SDL_DestroyTexture(_texture);
}

static inline void video_update_cb(cdlv_yuv_plane plane, cdlv_yuv_pitch pitch, void* texture, void* user_data) {
    SDL_Texture* _texture = (SDL_Texture*)texture;
    SDL_UpdateYUVTexture(_texture, NULL, plane.y, pitch.y, plane.u, pitch.u, plane.v, pitch.v);
}

cdlv_user_*

typedef int (*cdlv_user_update_cb)(void* user_data);
typedef void (*cdlv_line_cb)(const char* line, void* user_data);
typedef struct cdlv_user_config {
    cdlv_user_update_cb update_callback;   // Called when cdlv continues to another line
    cdlv_line_cb line_callback;            // Called when cdlv can display text line
    void* user_data;                       // User data
} cdlv_user_config;

Example:

static inline int user_update_cb(void* user_data) {
    struct text* t = (struct text*)user_data;
    if(t->current_char != t->content_size) {
        strcpy(t->rendered, t->content);
        t->current_char = t->content_size;
	return 0;
    }
    return 1;
}

static inline void line_cb(const char* line, void* user_data) {
    text_update(line);
}