librga Documentation

librga is a userspace driver implementation for the Rockchip RGA (Raster Graphic Acceleration Unit). The RGA is a dedicated 2D hardware accelerator used to speed up common 2D graphics operations such as:

• Point and line drawing
• Image scaling and rotation
• bitBlt (Bit Block Transfer)
• Alpha blending

The library provides a set of 2D graphics APIs (IM2D) to interface with this hardware.

The librga.so library provides high-performance 2D graphics operations using the RGA hardware. It offers two primary ways to interact with the hardware:

1. Direct API Calls: Individual functions for specific operations (e.g., imcopy, imresize, imrotate) that execute immediately.
2. Task-based API (Job/Task Mode): A workflow where multiple operations are bound together into a single RGA task using imbeginJob and ...Task functions, then executed atomically via imendJob. This is more efficient for complex image processing pipelines.

To use these APIs, you must first prepare your image buffers using importbuffer_T (to map external memory like DMA-FDs or virtual addresses into the RGA driver) and wrapbuffer_handle (to populate the struct rga_buffer_t with resolution and format metadata).

The samples directory contains demonstration code for the librga IM2D API, covering common image processing operations such as scaling, cropping, rotation, Blit, and alpha blending.

Key sample categories include:

• im2d_api_demo: Quick API demonstrations.
• allocator_demo: Memory allocation examples (CMA, DMA-BUF, DRM, GraphicBuffer, malloc, etc.).
• alpha_demo: Alpha blending, color key, and OSD scenarios.
• copy_demo: Image copying, FBC copying, tiling, and splicing.
• crop_demo: Image cropping and rectangular area output.
• cvtcolor_demo: Format and color space conversions.
• fill_demo: Color filling and rectangle drawing.
• resize_demo: Image scaling and YUV downsampling.
• transform_demo: Image flipping and rotation.
• async_demo: Asynchronous mode operations.
• config_demo: Thread-global configuration (e.g., specifying RGA cores).

RGA is an independent 2D hardware accelerator designed to offload common graphics operations from the CPU. It is used to speed up tasks such as:

• Point/line drawing
• Image resizing (scaling)
• Rotation (90/180/270 degrees)
• BitBlt (Bit Block Transfer)
• Alpha blending
• X/Y Mirroring
• Cropping
• Color key and Color fill operations
• Dithering and Pixel Format conversion

To perform multiple image operations efficiently, use the Job-based API pattern. This allows you to bind multiple operations (like resizing, rotating, and color conversion) into a single RGA image task that is submitted to the driver for sequential execution.

Workflow:

1. Initialize buffers using wrapbuffer_handle.
2. Start a job with imbeginJob.
3. Add multiple operations to the job using their Task variants (e.g., imresizeTask, imrotateTask).
4. Submit and execute the job with imendJob.
5. If using asynchronous mode, use imsync to wait for completion.
6. Clean up buffers with releasebuffer_handle if they were imported via importbuffer_T.

The sample input files use a structured naming scheme to identify properties. For a file named in%d%dw%d-h%d-%s.bin:

• %d (1st): File Index. Used to differentiate files with identical formats and dimensions (e.g., in0... vs in1...).
• %d (2nd): Width. Represents the width (often referred to as virtual width).
• %d (3rd): Height. Represents the height (often referred to as virtual height).
• %s: Format. The name of the pixel format (e.g., rgba8888).

Common Sample Files:

• in0w1280-h720-rgba8888.bin: 1280×720, RGBA8888, mostly transparent (except for logo).
• in1w1280-h720-rgba8888.bin: 1280×720, RGBA8888, fully opaque.

When using RGA, ensure your librga version and kernel driver version are compatible. If you update librga.so independently of the SDK, you may need to update the driver to avoid errors.

Key compatibility mappings:

Hardware-wise, RGA processes tasks sequentially (one task must finish before the next begins). It cannot draw multiple rectangles in a single hardware command.

Workarounds:

1. Async Mode: Use async mode to queue multiple tasks into the driver's work queue. The hardware will process them in order.
2. Synchronization: Use imsync() to ensure the RGA hardware has completed the queued work before accessing the buffer in your application.
3. Array APIs (librga 1.9.0+): For specific tasks like drawing lines, boxes, or filling rectangles, use the array suffixed interfaces (e.g., imfillArray, imrectangleArray) to configure multiple regions at once.

// Example concept: Using async and sync
// 1. Queue work via async API
// 2. ...
// 3. Ensure completion
imsync();

When working with grayscale-only YUV formats, be aware of how bit depth and color space affect conversion:

• RK_FORMAT_YCbCr_400: Only contains the Y channel. Often used for 256-level grayscale images. When converting between RGB and YUV, ensure the color space is configured correctly (e.g., use full range for a full 256-level grayscale image).
• RK_FORMAT_Y4: Only contains the Y channel with 4-bit dithering. Used for 16-level grayscale images. Requires the same color space configuration precautions as RK_FORMAT_YCbCr_400.
• RK_FORMAT_Y8: Similar to RK_FORMAT_Y4, but only the high 4 bits contain valid data; the low 4 bits are invalid.