LCharacter Reference Manual & Mixer Integration Guide

The LCharacter class is a high-performance vector graphics and Character Generator (CG) overlay engine based on the Cairo 2D graphics API. It provides broadcasting overlay features (lower-thirds, scoreboards, scrolling tickers, and logos) drawn directly on transparent video frames using CPU or GPU rasterization.

It supports static and dynamic text wrapping, shape rendering with borders, gradients, alpha-transparency, scrolling crawls, vertical tickers, custom images, loopable transparent video items, grouping, and XML template serialization.

1. API Reference & Key Methods

📌 Ingestion & Element Addition

• LCGTextItem* addItem(std::string id, int x, int y, int w, int h, LCGTextProps props)
  Adds a text field element with background, outline, and shadow configurations.
• LCGCrawlItem* addItem(std::string id, int x, int y, int w, int h, LCGCrawlProps props)
  Adds a scrolling crawl ticker bar (e.g. news crawl).
• LCGTickerItem* addItem(std::string id, int x, int y, int w, int h, LCGTickerProps props)
  Adds a multi-page vertical ticker rolling item.
• LCGImageItem* addItem(std::string id, int x, int y, int w, int h, LCGImageProps props)
  Adds a raster image overlay (.png, .jpg).
• LCGVideoItem* addItem(std::string id, int x, int y, int w, int h, LCGVideoProps props)
  Adds a looping video element supporting transparency (ProRes 4444 / WebM alpha).
• LCGRectItem* addItem(std::string id, int x, int y, int w, int h, LCGRectProps props)
  Adds a background rectangle shape (solid or gradient, rounded corners).

📌 Modification & Lifecycle

• void updateItem(std::string id, int x, int y, int w, int h, float alpha, bool show, [PropsStruct] props)
  Updates coordinates, transparency (alpha 0.0f to 1.0f), visibility, and visual properties. (Overloads exist for all 6 element type properties).
• LCGItem* getItem(std::string id)
  Retrieves a generic element pointer by ID. Must be cast to the appropriate subclass to access type-specific properties.
• void showItem(std::string id_or_group, bool show)
  Shows or hides an item or a group.
• void remove(const std::string& id)
  Deletes an element from the canvas.
• void forceUpdate()
  Triggers a redraw of the Cairo canvas.
• void setFPS(double fps)
  Sets the compositing frame rate (e.g., 50.0).

📌 XML Configuration Save & Load

• void saveToXMLFile(const std::string& filePath)
  Saves the current canvas state, groups, and elements into an XML file.
• void loadFromXMLFile(const std::string& filePath)
  Clears the current canvas and loads the state from an XML template.
• void insertFromXMLFile(const std::string& filePath)
  Merges elements from an XML template into the current canvas.

📌 Grouping Operations

• std::string group(const std::vector<std::string>& itemIDs)
  Groups multiple elements under a single generated group ID for bulk translation or hiding.
• void unGroup(const std::string& groupID)
  Dissolves a group.
• LCGGroup* getGroupObject(const std::string& groupID)
  Retrieves a group handle to modify offset position (x, y), scale, and visibility.

2. Base Element Properties: LCGItem & Group Class: LCGGroup

LCGItem Base Class

All items added to LCharacter (LCGTextItem, LCGCrawlItem, etc.) inherit the base properties of LCGItem. These parameters can be read or modified directly on the item pointer:

LCGGroup Class

Defines a collection of elements that can be moved or toggled as a single unit:

3. Subclass Items & Property Structs

To modify properties directly on the item pointers returned by addItem or getItem, you must access the specific member properties belonging to these subclasses:

📌 LCGTextItem (Static/Dynamic Text)

Defines a text block layout:

class NOW2SDK_EXPORT LCGTextItem : public LCGItem {
public:
    LCGTextProps props; // Text properties struct
};

LCGTextProps Struct

📌 LCGCrawlItem (Scrolling News Tickers)

Defines a continuous text crawl marquee:

class NOW2SDK_EXPORT LCGCrawlItem : public LCGItem { 
public:
    LCGCrawlProps crawlProps; // Crawl ticker properties
};

LCGCrawlProps Struct

📌 LCGTickerItem (Vertical Rolling Page Tickers)

Defines a vertical slide roll ticker:

class NOW2SDK_EXPORT LCGTickerItem : public LCGItem { 
public:
    LCGTickerProps tickerProps; // Rolling ticker properties
};

LCGTickerProps Struct

📌 LCGImageItem (Image Overlay)

Defines a static raster image overlay:

class NOW2SDK_EXPORT LCGImageItem : public LCGItem {
public:
    LCGImageProps imageProps; // Image path struct
};

LCGImageProps Struct

📌 LCGVideoItem (Video Loop Overlay)

Defines a loopable transparent video overlay:

class NOW2SDK_EXPORT LCGVideoItem : public LCGItem {
public:
    LCGVideoProps videoProps; // Video path struct
};

LCGVideoProps Struct

📌 LCGRectItem (Vector Rectangle Shape)

Defines a vector rectangle block:

class NOW2SDK_EXPORT LCGRectItem : public LCGItem {
public:
    LCGRectProps rectProps; // Rectangle styling properties
};

LCGRectProps Struct

4. Mixer Integration Example

The following C++ example demonstrates how to integrate LCharacter inside LMixer to overlay branding elements (logo, scrolling crawl, and styled lower-third) over video playback.

mainwindow.cpp

#include "mainwindow.h"
#include "now2sdk.h"
#include <QTimer>

MainWindow::MainWindow(QWidget *parent)
    : QMainWindow(parent),
      m_lFile(new LFile()),
      m_lMixer(new LMixer()),
      m_lCG(new LCharacter()),
      m_lPreview(new LPreview())
{
    // 1. Configure Mixer Resolution (1080p50)
    videoFormatProps format;
    format.setVideoFormat = vF::HD1080_50p;
    m_lMixer->setVideoFormat(format);

    // 2. Add Background Video Layer (z-index: 0)
    m_lMixer->addLayer("video_bg", m_lFile, 0, 0, 0, 255, 1920, 1080);

    // 3. Add CG Character Generator Overlay Layer (z-index: 1)
    m_lMixer->addLayer("cg_overlay", m_lCG, 1, 0, 0, 255, 1920, 1080);

    // 4. Configure Preview Widget
    m_lPreview->setProps("ui_framework", "qt");
    m_lPreview->previewEnable(ui->programView, true, true);
    m_lPreview->previewObject(m_lMixer);

    // Load file and play
    m_lFile->fileNameSet("/media/background.mp4");
    m_lFile->play();
}

MainWindow::~MainWindow() {
    m_lFile->stop();
    delete m_lPreview;
    delete m_lFile;
    delete m_lMixer;
    delete m_lCG;
}

// ─── 1. Lower Third Overlay (Background block with gradient + two text rows) ───
void MainWindow::showLowerThird() {
    m_lCG->remove("lt_bg");
    m_lCG->remove("lt_title");
    m_lCG->remove("lt_desc");

    // Background block
    LCGRectProps bg;
    bg.bgType = "Gradient";
    bg.bgGradientStartColor = "#0055ff";
    bg.bgGradientEndColor = "#020215";
    bg.bgAlpha = 240;
    bg.bgRadius = 8;
    m_lCG->addItem("lt_bg", 150, 800, 700, 120, bg);

    // Header Text (Courier New, Outline)
    LCGTextProps title;
    title.text = "ALİ SABER";
    title.font = "Courier New";
    title.fontSize = 36;
    title.color = "#FFFFFF";
    title.outlineSize = 1;
    title.outlineColor = "#000000";
    title.hAlign = "Left";
    title.padding = 20;
    m_lCG->addItem("lt_title", 150, 800, 700, 70, title);

    // Subtitle Text
    LCGTextProps desc;
    desc.text = "Lead Broadcast Engineer";
    desc.font = "Courier New";
    desc.fontSize = 22;
    desc.color = "#55AAFF";
    desc.hAlign = "Left";
    desc.padding = 20;
    m_lCG->addItem("lt_desc", 150, 860, 700, 50, desc);

    m_lCG->forceUpdate();
}

// ─── 2. Scrolling Crawl Ticker (News Crawl at bottom) ───
void MainWindow::showNewsTicker() {
    m_lCG->remove("ticker");

    LCGCrawlProps crawl;
    crawl.text = "::: NOW2SDK CAIRO GRAPHICS ENGINE DEMO ::: EXTREMELY LOW LATENCY RASTERIZATION :::";
    crawl.font = "Arial";
    crawl.fontSize = 30;
    crawl.color = "#FFFF00";
    crawl.bgType = "Solid";
    crawl.bgColor = "#111111";
    crawl.bgAlpha = 220;
    crawl.textMove = "Horizontal";
    crawl.textSpeed = -4.0f; // Scroll speed to the left (4 pixels per frame)

    m_lCG->addItem("ticker", 0, 980, 1920, 80, crawl);
    m_lCG->forceUpdate();
}

// ─── 3. Clear CG overlays ───
void MainWindow::clearOverlays() {
    m_lCG->remove("lt_bg");
    m_lCG->remove("lt_title");
    m_lCG->remove("lt_desc");
    m_lCG->remove("ticker");
    m_lCG->forceUpdate();
}