### Setting Installation Paths

Source: https://github.com/ultravideo/uvg266/blob/master/CMakeLists.txt

Configures the installation directories for the uvg266 library, binaries, include files, and manual pages. These paths are typically derived from standard CMake installation directories but can be customized.

```cmake
set(UVG266_INSTALL_LIBDIR "${CMAKE_INSTALL_LIBDIR}" CACHE PATH "uvg266 library install path")
set(UVG266_INSTALL_BINDIR "${CMAKE_INSTALL_BINDIR}" CACHE PATH "uvg266 binary install path")
set(UVG266_INSTALL_INCLUDEDIR "${CMAKE_INSTALL_INCLUDEDIR}" CACHE PATH "uvg266 include install path")
set(UVG266_INSTALL_MANDIR "${CMAKE_INSTALL_MANDIR}/man1" CACHE PATH "uvg266 manual page file install path")
```

--------------------------------

### Full Video Encoding Example in C using UVG266

Source: https://context7.com/ultravideo/uvg266/llms.txt

This C code demonstrates a complete video encoding process using the UVG266 library. It includes initializing the encoder with custom configurations (resolution, framerate, QP, preset), reading raw YUV frames from a file, encoding each frame, writing the resulting bitstream to an output file, and flushing the encoder. The example handles file operations, memory allocation for pictures and data chunks, and error checking. It requires the UVG266 library and standard C libraries like stdio.h and stdlib.h.

```c
#include "uvg266.h"
#include <stdio.h>
#include <stdlib.h>

void write_bitstream(FILE *out, uvg_data_chunk *chunks) {
    for (uvg_data_chunk *chunk = chunks; chunk; chunk = chunk->next) {
        fwrite(chunk->data, 1, chunk->len, out);
    }
}

int encode_video(const char *input_yuv, const char *output_vvc,
                int width, int height, int frame_count) {
    const uvg_api *api = uvg_api_get(8);

    // Configure encoder
    uvg_config *config = api->config_alloc();
    api->config_init(config);
    config->width = width;
    config->height = height;
    config->framerate_num = 30;
    config->framerate_denom = 1;
    api->config_parse(config, "qp", "26");
    api->config_parse(config, "preset", "medium");
    api->config_parse(config, "period", "32");

    uvg_encoder *encoder = api->encoder_open(config);
    if (!encoder) {
        fprintf(stderr, "Failed to open encoder\n");
        api->config_destroy(config);
        return 1;
    }

    // Write headers
    FILE *out = fopen(output_vvc, "wb");
    if (!out) {
        fprintf(stderr, "Failed to open output file\n");
        api->encoder_close(encoder);
        api->config_destroy(config);
        return 1;
    }

    uvg_data_chunk *headers = NULL;
    uint32_t headers_len = 0;
    api->encoder_headers(encoder, &headers, &headers_len);
    write_bitstream(out, headers);
    api->chunk_free(headers);

    // Open input
    FILE *in = fopen(input_yuv, "rb");
    if (!in) {
        fprintf(stderr, "Failed to open input file\n");
        fclose(out);
        api->encoder_close(encoder);
        api->config_destroy(config);
        return 1;
    }

    // Encode frames
    int frames_encoded = 0;
    size_t y_size = width * height;
    size_t uv_size = (width / 2) * (height / 2);

    for (int i = 0; i < frame_count; i++) {
        uvg_picture *pic_in = api->picture_alloc(width, height);
        if (!pic_in) {
            fprintf(stderr, "Failed to allocate picture\n");
            break;
        }

        // Read YUV data
        if (fread(pic_in->y, 1, y_size, in) != y_size ||
            fread(pic_in->u, 1, uv_size, in) != uv_size ||
            fread(pic_in->v, 1, uv_size, in) != uv_size) {
            api->picture_free(pic_in);
            break;
        }

        pic_in->pts = i;
        pic_in->dts = i;

        // Encode frame
        uvg_data_chunk *data_out = NULL;
        uint32_t len_out = 0;
        uvg_picture *rec_out = NULL;
        uvg_picture *src_out = NULL;
        uvg_frame_info info_out;

        if (!api->encoder_encode(encoder, pic_in, &data_out, &len_out, 
                                &rec_out, &src_out, &info_out)) {
            fprintf(stderr, "Encoding failed at frame %d\n", i);
            api->picture_free(pic_in);
            break;
        }

        // Write output
        if (data_out) {
            write_bitstream(out, data_out);
            api->chunk_free(data_out);
            api->picture_free(rec_out);
            api->picture_free(src_out);

            fprintf(stdout, "Frame %d: POC=%d, QP=%d, type=%s, size=%u bytes\n",
                    i, info_out.poc, info_out.qp,
                    info_out.slice_type == UVG_SLICE_I ? "I" :
                    info_out.slice_type == UVG_SLICE_P ? "P" : "B",
                    len_out);

            frames_encoded++;
        }
    }

    // Flush encoder
    fprintf(stdout, "Flushing encoder...\n");
    while (1) {
        uvg_data_chunk *data_out = NULL;
        uint32_t len_out = 0;
        uvg_frame_info info_out;

        if (!api->encoder_encode(encoder, NULL, &data_out, &len_out,
                                NULL, NULL, &info_out)) {
            break;
        }

        if (!data_out) {
            break;
        }

        write_bitstream(out, data_out);
        api->chunk_free(data_out);
        frames_encoded++;

        fprintf(stdout, "Flushed frame: POC=%d, size=%u bytes\n",
                info_out.poc, len_out);
    }

    fprintf(stdout, "Encoded %d frames total\n", frames_encoded);

    // Cleanup
    fclose(in);
    fclose(out);
    api->encoder_close(encoder);
    api->config_destroy(config);

    return 0;
}

int main() {
    return encode_video("input.yuv", "output.266", 1920, 1080, 100);
}

```

--------------------------------

### Install Package Configuration - CMake

Source: https://github.com/ultravideo/uvg266/blob/master/CMakeLists.txt

This CMake code defines installation rules for the uvg266 project. It specifies where the pkgconfig file, executables, libraries, and header files should be installed on the system.

```cmake
install(FILES ${PROJECT_SOURCE_DIR}/src/uvg266.pc DESTINATION ${UVG266_INSTALL_LIBDIR}/pkgconfig)
install(TARGETS uvg266-bin DESTINATION ${UVG266_INSTALL_BINDIR})
install(TARGETS uvg266 ARCHIVE DESTINATION "${UVG266_INSTALL_LIBDIR}" LIBRARY DESTINATION "${UVG266_INSTALL_LIBDIR}" RUNTIME DESTINATION "${UVG266_INSTALL_BINDIR}")
install(FILES ${PROJECT_SOURCE_DIR}/src/uvg266.h DESTINATION ${UVG266_INSTALL_INCLUDEDIR})
install(FILES ${PROJECT_SOURCE_DIR}/doc/uvg266.1 DESTINATION ${UVG266_INSTALL_MANDIR})
```

--------------------------------

### Encode Video Example

Source: https://context7.com/ultravideo/uvg266/llms.txt

A complete example demonstrating how to open the encoder, configure it, write headers, read YUV input frames, encode them, and flush the encoder. It also includes error handling and cleanup.

```APIDOC
## Encode Video Example

### Description
This function demonstrates the process of encoding a video from a YUV input file to a VVC bitstream file using the UVG266 encoder. It covers configuration, frame-by-frame encoding, and flushing the encoder.

### Function Signature
```c
int encode_video(const char *input_yuv,
                const char *output_vvc,
                int width,
                int height,
                int frame_count);
```

### Parameters
#### Input Parameters
- **input_yuv** (*const char* *) - Path to the input YUV video file.
- **output_vvc** (*const char* *) - Path to the output VVC bitstream file.
- **width** (*int*) - Width of the input video frames.
- **height** (*int*) - Height of the input video frames.
- **frame_count** (*int*) - The total number of frames to encode.

### Example Usage
```c
int main() {
    // Example: Encode 100 frames of 1920x1080 video
    return encode_video("input.yuv", "output.266", 1920, 1080, 100);
}
```

### Internal Workflow
1. Get the UVG266 API.
2. Allocate and initialize encoder configuration.
3. Set basic configuration parameters (width, height, framerate).
4. Parse additional configuration options (QP, preset, GOP period).
5. Open the UVG266 encoder.
6. Open the output VVC file for writing.
7. Generate and write encoder headers to the output file.
8. Open the input YUV file for reading.
9. Loop through the specified number of frames:
   a. Allocate a picture buffer for input.
   b. Read YUV data from the input file into the picture buffer.
   c. Set PTS and DTS for the input picture.
   d. Call `encoder_encode` to encode the frame.
   e. If encoding is successful and data is produced, write the bitstream data to the output file and free resources.
   f. Print frame encoding information.
10. After the loop, flush the encoder by repeatedly calling `encoder_encode` with `NULL` input until no more data is produced.
11. Write any flushed bitstream data to the output file.
12. Print the total number of frames encoded.
13. Clean up by closing files, closing the encoder, and destroying the configuration.
```

--------------------------------

### Command-Line Encoding Examples (Bash)

Source: https://context7.com/ultravideo/uvg266/llms.txt

Demonstrates various command-line encoding scenarios for uvg266. Includes basic encoding, explicit resolution, high quality, fast encoding, rate control, ROI encoding, low-delay GOP, tile-based parallel encoding, 10-bit encoding, and debug output.

```bash
# Basic encoding with automatic resolution detection
uvg266 -i BQMall_832x480_60.yuv -o output.266

# Explicit resolution and encoding parameters
uvg266 --input video_1920x1080.yuv \
       --input-res 1920x1080 \
       --output encoded.266 \
       --qp 22 \
       --preset medium \
       --frames 300

# High quality encoding with advanced features
uvg266 -i input.yuv \
       --input-res 3840x2160 \
       -o output.266 \
       --preset slower \
       --qp 20 \
       --period 64 \
       --gop 16 \
       --ref 4 \
       --threads 8 \
       --alf full \
       --sao full \
       --rdoq \
       --mip \
       --mrl \
       --lfnst \
       --dual-tree

# Fast encoding for real-time applications
uvg266 -i input.yuv \
       --input-res 1280x720 \
       -o output.266 \
       --preset ultrafast \
       --qp 28 \
       --threads 4 \
       --owf 4

# Rate-controlled encoding
uvg266 -i input.yuv \
       --input-res 1920x1080 \
       -o output.266 \
       --bitrate 5000000 \
       --rc-algorithm lambda \
       --preset medium

# Region-of-interest encoding with custom QP map
uvg266 -i input.yuv \
       --input-res 1920x1080 \
       -o output.266 \
       --qp 26 \
       --roi roi_map.txt

# Low-delay P-frame GOP structure
uvg266 -i input.yuv \
       --input-res 1920x1080 \
       -o output.266 \
       --gop lp-g8d3t1 \
       --preset medium

# Tile-based parallel encoding
uvg266 -i input.yuv \
       --input-res 3840x2160 \
       -o output.266 \
       --tiles 2x2 \
       --threads 8 \
       --preset fast

# 10-bit encoding
uvg266 -i input_10bit.yuv \
       --input-res 1920x1080 \
       --input-bitdepth 10 \
       -o output.266 \
       --preset medium

# Debug encoding with reconstruction output
uvg266 -i input.yuv \
       --input-res 832x480 \
       -o output.266 \
       --debug recon.yuv \
       --no-sao \
       --threads 0 \
       --no-wpp \
       -p 1 \
       --rd 0
```

--------------------------------

### Basic uvg266 VVC Encoding Example

Source: https://github.com/ultravideo/uvg266/blob/master/README.md

A straightforward example of using uvg266 to encode a YUV input file into a VVC bitstream. The essential parameters are the input and output file paths. Additional parameters like input resolution can be specified if not derivable from the filename.

```bash
uvg266 --input BQMall_832x480_60.yuv --output out.vvc

```

--------------------------------

### CMake Project Setup and Options

Source: https://github.com/ultravideo/uvg266/blob/master/CMakeLists.txt

Initializes the CMake project, sets project name, languages, homepage, and description. It also defines boolean options for building shared libraries, enabling AVX2 optimizations, and building tests. These options can be toggled by the user during the CMake configuration step.

```cmake
cmake_minimum_required(VERSION 3.12)

project(uvg266
LANGUAGES C CXX
HOMEPAGE_URL https://github.com/ultravideo/uvg266
DESCRIPTION "An open-source VVC encoder licensed under 3-clause BSD"
VERSION 0.8.1 )

option(BUILD_SHARED_LIBS "Build using shared uvg266 library" ON)

option(ENABLE_AVX2 "Enable AVX2 optimizations" ON)

option(BUILD_TESTS "Build tests" ON)
```

--------------------------------

### Configure Input Files

Source: https://github.com/ultravideo/uvg266/blob/master/CMakeLists.txt

Uses CMake's `configure_file` command to process input files (`.in`) and generate output files. This is used to embed build-time information, such as compiler versions and installation paths, into configuration files like `uvg266.pc` and `version.h`.

```cmake
# Apply dynamic info to the config files
configure_file("${PROJECT_SOURCE_DIR}/src/uvg266.pc.in" "${PROJECT_SOURCE_DIR}/src/uvg266.pc" @ONLY)
configure_file("${PROJECT_SOURCE_DIR}/src/version.h.in" "${PROJECT_SOURCE_DIR}/src/version.h" @ONLY)
```

--------------------------------

### Conditional Installation for Unix - CMake

Source: https://github.com/ultravideo/uvg266/blob/master/CMakeLists.txt

This CMake code snippet conditionally executes a block of code only if the target system is Unix-like. It's often used for platform-specific installation or build configurations, such as setting up distribution-specific files.

```cmake
IF(UNIX)
# DIST

set(GIT_LS_TREE_OK "1")
endif()
```

--------------------------------

### Read YUV Frame and Manage Picture Buffers (C)

Source: https://context7.com/ultravideo/uvg266/llms.txt

Example demonstrating how to allocate a picture buffer using `picture_alloc`, read YUV frame data from a file into the buffer, set picture properties, and then free the buffer. It utilizes `uvg_api_get` to retrieve the API, and `fread` for file reading. Error handling for file operations and memory allocation is included.

```c
#include "uvg266.h"
#include <stdio.h>
#include <string.h>

int read_yuv_frame(FILE *input, uvg_picture *pic) {
    const uvg_api *api = uvg_api_get(8);

    // Read Y plane
    size_t y_size = pic->width * pic->height;
    if (fread(pic->y, 1, y_size, input) != y_size) {
        return 0;
    }

    // Read U and V planes (4:2:0 subsampling)
    size_t uv_width = pic->width / 2;
    size_t uv_height = pic->height / 2;
    size_t uv_size = uv_width * uv_height;

    if (fread(pic->u, 1, uv_size, input) != uv_size) {
        return 0;
    }

    if (fread(pic->v, 1, uv_size, input) != uv_size) {
        return 0;
    }

    return 1;
}

int main() {
    const uvg_api *api = uvg_api_get(8);

    int32_t width = 1920;
    int32_t height = 1080;

    // Allocate 4:2:0 picture
    uvg_picture *pic = api->picture_alloc(width, height);
    if (!pic) {
        fprintf(stderr, "Failed to allocate picture\n");
        return 1;
    }

    fprintf(stdout, "Allocated picture: %dx%d, stride=%d\n",
            pic->width, pic->height, pic->stride);

    // Open input YUV file
    FILE *input = fopen("input.yuv", "rb");
    if (!input) {
        fprintf(stderr, "Failed to open input file\n");
        api->picture_free(pic);
        return 1;
    }

    // Read frame data
    if (!read_yuv_frame(input, pic)) {
        fprintf(stderr, "Failed to read frame\n");
        fclose(input);
        api->picture_free(pic);
        return 1;
    }

    // Set picture properties
    pic->pts = 0;
    pic->dts = 0;

    fprintf(stdout, "Read YUV frame successfully\n");

    // Cleanup
    fclose(input);
    api->picture_free(pic);

    return 0;
}
```

--------------------------------

### Distribution Check (CMake)

Source: https://github.com/ultravideo/uvg266/blob/master/CMakeLists.txt

Verifies the integrity of the generated distribution archive. It unpacks the tarball, configures the build using CMake, compiles the project, runs tests, and installs the project. It logs all output and checks for errors at each step.

```cmake
set(TEMP_DISTCHECK_DIR "_distcheck")

add_custom_target(distcheck
                  COMMAND echo "Writing log to ${PROJECT_SOURCE_DIR}/distcheck.log"
                  && cd ${PROJECT_SOURCE_DIR}
                  && mkdir -p ${TEMP_DISTCHECK_DIR}
                  && cd ${TEMP_DISTCHECK_DIR}
                  && tar -zxf ${CMAKE_SOURCE_DIR}/${PROJECT_NAME}-${PROJECT_VERSION}.tar.gz > ${PROJECT_SOURCE_DIR}/distcheck.log || { echo "\033[0;31mfailed to unpack ${PROJECT_NAME}-${PROJECT_VERSION}.tar.gz.\033[m"$<SEMICOLON> exit 1$<SEMICOLON> }
                  && echo "\033[0;32mFile unpack ok\033[m"
                  && cd ${PROJECT_NAME}-${PROJECT_VERSION}
                  && mkdir -p build
                  && cd build                  
                  && cmake -DCMAKE_INSTALL_PREFIX=./ -DBUILD_SHARED_LIBS=OFF -G "Unix Makefiles" .. >> ${PROJECT_SOURCE_DIR}/distcheck.log || { echo "\033[0;31mcake failed to configure.\033[m"$<SEMICOLON> exit 1$<SEMICOLON> }
                  && echo "\033[0;32mCMake configure ok\033[m"
                  && make -j >> ${PROJECT_SOURCE_DIR}/distcheck.log || { echo "\033[0;31mmake failed.\033[m"$<SEMICOLON> exit 1$<SEMICOLON> }
                  && echo "\033[0;32mMake ok\033[m"
                  # Full tests might be too demanding to run, enable with parameter?
                  #&& make test || (echo "\e[0;31mmake test failed.\033[m" && false)
                  && tests/uvg266_tests >> ${PROJECT_SOURCE_DIR}/distcheck.log 2>&1 || { echo "\033[0;31mtests failed.\033[m"$<SEMICOLON> exit 1$<SEMICOLON> }
                  && echo "\033[0;32mTests ok\033[m"
                  && make install >> ${PROJECT_SOURCE_DIR}/distcheck.log || { echo "\033[0;31mmake install failed.\033[m"$<SEMICOLON> exit 1$<SEMICOLON> }
                  && echo "\033[0;32mInstall ok\033[m"
                  && ${CMAKE_INSTALL_BINDIR}/uvg266 --help >> ${PROJECT_SOURCE_DIR}/distcheck.log || { echo "\033[0;31muvg266 binary failed to run.\033[m"$<SEMICOLON> exit 1$<SEMICOLON> }
                  && echo "\033[0;32m${CMAKE_INSTALL_BINDIR}/uvg266 ok\033[m"
                  && make clean >> ${PROJECT_SOURCE_DIR}/distcheck.log || { echo "\033[0;31mmake clean failed.\033[m"$<SEMICOLON> exit 1$<SEMICOLON> }
                  && echo "\033[0;32mmake clean ok\033[m"
                  && cd ${PROJECT_SOURCE_DIR}
                  && rm -rf "${PROJECT_SOURCE_DIR}/${TEMP_DISTCHECK_DIR}"
                  && echo "\033[0;32m==============================================================\033[m"
                  && echo "\033[0;32m${PROJECT_NAME}-${PROJECT_VERSION} archives ready for distribution:\033[m"
                  && echo "\033[0;32m${PROJECT_NAME}-${PROJECT_VERSION}.tar.gz\033[m"
                  && echo "\033[0;32m==============================================================\033[m"
                  WORKING_DIRECTORY ${PROJECT_SOURCE_DIR}
                  DEPENDS ${CMAKE_SOURCE_DIR}/${PROJECT_NAME}-${PROJECT_VERSION}.tar.gz
                  COMMENT "Checking ${PROJECT_NAME}-${PROJECT_VERSION}.tar.gz.."
                  )
```

--------------------------------

### Process Encoded Frame Example (C)

Source: https://context7.com/ultravideo/uvg266/llms.txt

Encodes a given picture using the uvg266 encoder and processes the output. It writes the encoded bitstream to a file and frees the allocated output data and reconstructed picture. Dependencies include the uvg266 header and stdio.h.

```c
#include "uvg266.h"
#include <stdio.h>

void process_encoded_frame(const uvg_api *api, uvg_encoder *encoder,
                          uvg_picture *pic_in, FILE *output) {
    uvg_data_chunk *data_out = NULL;
    uint32_t len_out = 0;
    uvg_picture *rec_out = NULL;
    uvg_frame_info info_out;

    // Encode frame
    if (!api->encoder_encode(encoder, pic_in, &data_out, &len_out,
                            &rec_out, NULL, &info_out)) {
        fprintf(stderr, "Encoding failed\n");
        return;
    }

    // Process output if available
    if (data_out) {
        // Write bitstream to file
        for (uvg_data_chunk *chunk = data_out; chunk; chunk = chunk->next) {
            fwrite(chunk->data, 1, chunk->len, output);
        }

        fprintf(stdout, "Encoded frame POC=%d, size=%u bytes\n",
                info_out.poc, len_out);

        // Important: Free all output data
        api->chunk_free(data_out);

        // Free reconstructed picture if we requested it
        if (rec_out) {
            api->picture_free(rec_out);
        }
    }
}
```

--------------------------------

### Compile Cost Analysis Tools (C)

Source: https://github.com/ultravideo/uvg266/blob/master/rdcost-weight-tool/README.txt

Compiles the C source files 'filter_rdcosts.c' and 'ols_2ndpart.c' into executable tools for analyzing block costs. These tools are optimized with '-O2' for performance.

```bash
gcc filter_rdcosts.c -O2 -o frcosts_matrix
gcc ols_2ndpart.c -O2 -o ols_2ndpart
```

--------------------------------

### Using Presets for Speed and Quality in uvg266

Source: https://github.com/ultravideo/uvg266/blob/master/README.md

Illustrates how to control the trade-off between encoding speed and compression quality in uvg266 using presets. Alternatively, individual encoding options can be set manually.

```bash
--preset=balanced

```

--------------------------------

### Get uvg266 Encoder API

Source: https://context7.com/ultravideo/uvg266/llms.txt

Retrieves the uvg266 encoder API function table for a specified bit depth. This is the entry point for accessing all encoder functionalities, including configuration and encoding operations. It returns a structure containing function pointers.

```c
const uvg_api * uvg_api_get(int bit_depth);
```

```c
#include <stdio.h>
#include <stdlib.h>
#include "uvg266.h"

int main() {
    // Get 8-bit encoder API
    const uvg_api *api = uvg_api_get(8);
    if (!api) {
        fprintf(stderr, "Failed to retrieve uvg266 API for 8-bit depth\n");
        return EXIT_FAILURE;
    }

    // Verify API version compatibility
    fprintf(stdout, "uvg266 API retrieved successfully\n");
    fprintf(stdout, "API version: %d\n", UVG_API_VERSION);

    return EXIT_SUCCESS;
}
```

--------------------------------

### Building UVG266 Command-Line Binary (CMake)

Source: https://github.com/ultravideo/uvg266/blob/master/CMakeLists.txt

This snippet defines the command-line executable 'uvg266-bin'. It lists the necessary source files, including those for the CLI and potentially platform-specific wrappers, and links the previously defined 'uvg266' library to it. It also sets the output name for the executable.

```cmake
set(CLI_SOURCES "src/encmain.c" "src/cli.c" "src/cli.h" "src/yuv_io.c" "src/yuv_io.h")

# Add the getopt and pthread for visual studio
if(MSVC) 
  list(APPEND CLI_SOURCES ${CMAKE_CURRENT_SOURCE_DIR}/src/extras/getopt.c ${CMAKE_CURRENT_SOURCE_DIR}/src/threadwrapper/src/pthread.cpp ${CMAKE_CURRENT_SOURCE_DIR}/src/threadwrapper/src/semaphore.cpp)
  
  string(REPLACE "/Zi" "/ZI" CMAKE_C_FLAGS_DEBUG "${CMAKE_C_FLAGS_DEBUG}")
  string(REPLACE "/Zi" "/ZI" CMAKE_CXX_FLAGS_DEBUG "${CMAKE_CXX_FLAGS_DEBUG}")
  string(REPLACE "/Zi" "/ZI" CMAKE_C_FLAGS_RELWITHDEBINFO "${CMAKE_C_FLAGS_RELWITHDEBINFO}")
  string(REPLACE "/Zi" "/ZI" CMAKE_CXX_FLAGS_RELWITHDEBINFO "${CMAKE_CXX_FLAGS_RELWITHDEBINFO}")

  target_link_options(uvg266 PUBLIC "/INCREMENTAL")
endif()

add_executable(uvg266-bin ${CLI_SOURCES})

target_link_libraries(uvg266-bin PUBLIC uvg266)

set_target_properties(uvg266-bin PROPERTIES OUTPUT_NAME uvg266)
set_target_properties(uvg266-bin PROPERTIES RUNTIME_OUTPUT_NAME uvg266)
```

--------------------------------

### Get Encoder API

Source: https://context7.com/ultravideo/uvg266/llms.txt

Retrieves the uvg266 encoder API function table for the specified bit depth. This function is the entry point to all encoder functionality and returns a structure containing function pointers for configuration, encoding, and memory management operations.

```APIDOC
## Get Encoder API

### Description
Retrieves the uvg266 encoder API function table for the specified bit depth. This function is the entry point to all encoder functionality and returns a structure containing function pointers for configuration, encoding, and memory management operations.

### Method
`uvg_api * uvg_api_get(int bit_depth)`

### Parameters
#### Path Parameters
None

#### Query Parameters
* **bit_depth** (int) - Required - The desired bit depth for the encoder API.

### Request Body
None

### Request Example
```c
const uvg_api *api = uvg_api_get(8);
if (!api) {
    fprintf(stderr, "Failed to retrieve uvg266 API for 8-bit depth\n");
    return EXIT_FAILURE;
}
```

### Response
#### Success Response (200)
* **api** (const uvg_api *) - A pointer to the uvg_api structure containing function pointers for encoder operations. Returns NULL on failure.

#### Response Example
```c
// Pointer to the uvg_api structure is returned on success
```
```

--------------------------------

### Configure uvg266 Test Executable Build (CMake)

Source: https://github.com/ultravideo/uvg266/blob/master/tests/CMakeLists.txt

Sets up the uvg266_tests executable in CMake. It includes source files, adds include directories, defines preprocessor macros, and links the uvg266 library. Platform-specific configurations for MSVC and other compilers are handled.

```cmake
file( GLOB TEST_SOURCES "*.c" )

# ToDo: fix the tests
list(REMOVE_ITEM TEST_SOURCES "${CMAKE_CURRENT_SOURCE_DIR}/inter_recon_bipred_tests.c")

add_executable(uvg266_tests ${TEST_SOURCES} )

target_include_directories(uvg266_tests PUBLIC ${PROJECT_SOURCE_DIR})
target_include_directories(uvg266_tests PUBLIC ${PROJECT_SOURCE_DIR}/src)
target_include_directories(uvg266_tests PUBLIC ${PROJECT_SOURCE_DIR}/src/extras)

add_definitions(-DUVG_DLL_EXPORTS)

if(BUILD_SHARED_LIBS)
  add_definitions(-DPIC)
endif()

if(MSVC)
  target_include_directories(uvg266_tests PUBLIC ../src/threadwrapper/include)

  set_property( SOURCE ${TEST_SOURCES}  APPEND PROPERTY COMPILE_FLAGS "/arch:AVX2" )
  add_definitions(-DWIN32_LEAN_AND_MEAN -D_WIN32 -DWIN32 -DWIN64)
else()
  list(APPEND ALLOW_AVX2 "x86_64" "AMD64")
  if(${CMAKE_SYSTEM_PROCESSOR} IN_LIST ALLOW_AVX2) 
    set_property( SOURCE ${TEST_SOURCES}  APPEND PROPERTY COMPILE_FLAGS "-mavx2 -mbmi -mpopcnt -mlzcnt -mbmi2" )
  endif()
  find_package(Threads REQUIRED)
  target_link_libraries(uvg266_tests PUBLIC Threads::Threads)

  include(CheckLibraryExists)

  CHECK_LIBRARY_EXISTS(m sin "" HAVE_LIB_M)

  if (HAVE_LIB_M)
      set(EXTRA_LIBS ${EXTRA_LIBS} m)
  endif (HAVE_LIB_M)

  target_link_libraries(uvg266_tests PUBLIC ${EXTRA_LIBS})
endif()

target_link_libraries(uvg266_tests PUBLIC uvg266)

```

--------------------------------

### Selecting Input Format and Bitdepth in uvg266

Source: https://github.com/ultravideo/uvg266/blob/master/README.md

Shows how to specify the input video format (e.g., yuv420p) and bit depth (e.g., 8-bit or 10-bit) for the uvg266 encoder. This is crucial for handling different types of raw video input.

```bash
--input-format=yuv420p
--input-bitdepth=10

```

--------------------------------

### Manage UVG266 Encoder Instance

Source: https://context7.com/ultravideo/uvg266/llms.txt

Handles the creation and destruction of UVG266 encoder instances. `encoder_open` allocates resources and initializes the encoder based on the provided configuration. `encoder_close` releases these resources. Proper management is crucial for efficient video encoding.

```c
uvg_encoder * encoder_open(const uvg_config *cfg);
void encoder_close(uvg_encoder *encoder);
```

```c
#include "uvg266.h"
#include <stdio.h>

int main() {
    const uvg_api *api = uvg_api_get(8);

    // Setup configuration
    uvg_config *config = api->config_alloc();
    api->config_init(config);
    config->width = 1280;
    config->height = 720;
    config->framerate_num = 25;
    config->framerate_denom = 1;
    api->config_parse(config, "qp", "28");
    api->config_parse(config, "preset", "fast");

    // Open encoder
    uvg_encoder *encoder = api->encoder_open(config);
    if (!encoder) {
        fprintf(stderr, "Failed to open encoder\n");
        api->config_destroy(config);
        return 1;
    }

    fprintf(stdout, "Encoder opened successfully\n");
    fprintf(stdout, "Ready to encode %dx%d video\n",
            config->width,
            config->height);

    // Perform encoding operations... 

    // Close encoder and cleanup
    api->encoder_close(encoder);
    api->config_destroy(config);

    fprintf(stdout, "Encoder closed successfully\n");
    return 0;
}
```

--------------------------------

### Basic Command-Line Encoding (Bash)

Source: https://context7.com/ultravideo/uvg266/llms.txt

Performs basic video encoding using the uvg266 command-line tool. It requires input and output file paths and can automatically detect input resolution. Supports raw YUV and Y4M input formats.

```bash
uvg266 -i <input> --input-res <width>x<height> -o <output> [options]
```

--------------------------------

### Create and Apply ROI Map for UVG266 Encoding (C)

Source: https://context7.com/ultravideo/uvg266/llms.txt

Demonstrates how to create an ROI map within the `uvg_picture` structure and apply it during UVG266 encoding. This function allocates memory for the ROI array, calculates delta QP values based on pixel location (center region for higher quality, outer regions for lower quality), and integrates with the encoder.

```c
#include "uvg266.h"
#include <stdio.h>
#include <stdlib.h>
#include <string.h>

void create_roi_map(uvg_picture *pic) {
    // Create ROI map with same dimensions as picture
    pic->roi.width = pic->width;
    pic->roi.height = pic->height;
    pic->roi.roi_array = calloc(pic->width * pic->height, sizeof(int8_t));

    if (!pic->roi.roi_array) {
        fprintf(stderr, "Failed to allocate ROI map\n");
        return;
    }

    // Define center region for higher quality (negative QP delta)
    int center_x = pic->width / 2;
    int center_y = pic->height / 2;
    int roi_width = pic->width / 3;
    int roi_height = pic->height / 3;

    for (int y = 0; y < pic->height; y++) {
        for (int x = 0; x < pic->width; x++) {
            int idx = y * pic->width + x;

            // Check if pixel is in center ROI
            int dx = abs(x - center_x);
            int dy = abs(y - center_y);

            if (dx < roi_width / 2 && dy < roi_height / 2) {
                // Center region: reduce QP by 5 (higher quality)
                pic->roi.roi_array[idx] = -5;
            } else if (dx < roi_width && dy < roi_height) {
                // Transition region: reduce QP by 2
                pic->roi.roi_array[idx] = -2;
            } else {
                // Background: increase QP by 3 (lower quality)
                pic->roi.roi_array[idx] = 3;
            }
        }
    }
}

void free_roi_map(uvg_picture *pic) {
    if (pic->roi.roi_array) {
        free(pic->roi.roi_array);
        pic->roi.roi_array = NULL;
    }
}

int main() {
    const uvg_api *api = uvg_api_get(8);

    // Setup encoder
    uvg_config *config = api->config_alloc();
    api->config_init(config);
    config->width = 1920;
    config->height = 1080;
    api->config_parse(config, "qp", "26");
    api->config_parse(config, "preset", "medium");

    uvg_encoder *encoder = api->encoder_open(config);

    // Allocate picture with ROI
    uvg_picture *pic = api->picture_alloc(config->width, config->height);
    create_roi_map(pic);

    // Read frame data...
    // (assume pic->y, pic->u, pic->v are filled)

    pic->pts = 0;

    // Encode with ROI
    uvg_data_chunk *data_out = NULL;
    uint32_t len_out = 0;
    uvg_frame_info info_out;

    if (api->encoder_encode(encoder, pic, &data_out, &len_out,
                           NULL, NULL, &info_out)) {
        if (data_out) {
            fprintf(stdout, "Encoded frame with ROI: %u bytes\n", len_out);
            api->chunk_free(data_out);
        }
    }

    // Cleanup
    free_roi_map(pic);
    api->picture_free(pic);
    api->encoder_close(encoder);
    api->config_destroy(config);

    return 0;
}

```

--------------------------------

### Analyze Block Costs (Python)

Source: https://github.com/ultravideo/uvg266/blob/master/rdcost-weight-tool/README.txt

Analyzes extracted block costs using linear regression. This script runs the compiled 'frcosts_matrix' and 'ols_2ndpart' tools in parallel to process compressed cost data with O(1) memory complexity. The output represents the bit cost of coefficients.

```python
# Example usage:
# Run run_filter.py after compiling analysis tools.
# This script processes compressed cost data in parallel.
```

--------------------------------

### Specifying Input Resolution in uvg266

Source: https://github.com/ultravideo/uvg266/blob/master/README.md

Demonstrates how to explicitly set the input resolution for uvg266 when it cannot be determined from the input filename or when using piped input. This ensures the encoder processes the video data correctly.

```bash
uvg266 --input-res=1920x1080

```

--------------------------------

### Manage uvg266 Encoder Configuration

Source: https://context7.com/ultravideo/uvg266/llms.txt

Manages the lifecycle of the uvg266 encoder configuration. This includes allocating memory for the configuration structure, initializing it with default values, parsing specific encoding parameters by name-value pairs, and freeing the allocated memory. Proper configuration is essential before encoding.

```c
uvg_config * config_alloc(void);
int config_init(uvg_config *cfg);
int config_parse(uvg_config *cfg, const char *name, const char *value);
void config_destroy(uvg_config *cfg);
```

```c
#include "uvg266.h"
#include <stdio.h>

int main() {
    const uvg_api *api = uvg_api_get(8);

    // Allocate and initialize configuration
    uvg_config *config = api->config_alloc();
    if (!config) {
        fprintf(stderr, "Failed to allocate configuration\n");
        return 1;
    }

    // Initialize with defaults
    if (!api->config_init(config)) {
        fprintf(stderr, "Failed to initialize configuration\n");
        api->config_destroy(config);
        return 1;
    }

    // Set encoding parameters
    config->width = 1920;
    config->height = 1080;
    config->framerate_num = 30;
    config->framerate_denom = 1;

    // Parse options by name
    if (!api->config_parse(config, "qp", "22") ||
        !api->config_parse(config, "preset", "medium") ||
        !api->config_parse(config, "period", "64") ||
        !api->config_parse(config, "threads", "4") ||
        !api->config_parse(config, "ref", "4")) {
        fprintf(stderr, "Failed to parse configuration options\n");
        api->config_destroy(config);
        return 1;
    }

    // Enable VVC features
    api->config_parse(config, "alf", "full");
    api->config_parse(config, "sao", "full");
    api->config_parse(config, "rdoq", "1");
    api->config_parse(config, "mip", "1");
    api->config_parse(config, "mrl", "1");

    fprintf(stdout, "Configuration: %dx%d @ %d fps, QP=%d\n",
            config->width, config->height,
            config->framerate_num, config->qp);

    // Cleanup
    api->config_destroy(config);
    return 0;
}
```

--------------------------------

### Building UVG266 Library (CMake)

Source: https://github.com/ultravideo/uvg266/blob/master/CMakeLists.txt

This snippet configures the build of the UVG266 library, either as a shared or static library. It includes platform-specific adjustments for Visual Studio (OUTPUT_NAME) and sets up runtime search paths for shared libraries. It also defines public include directories for the library.

```cmake
if(BUILD_SHARED_LIBS)
  list( APPEND CMAKE_INSTALL_RPATH "${UVG266_INSTALL_LIBDIR}" "./" "../lib" )
  set(CMAKE_INSTALL_RPATH_USE_LINK_PATH TRUE)
  add_library(uvg266 SHARED ${LIB_SOURCES})
else()
  add_library(uvg266 STATIC ${LIB_SOURCES})
  if(MSVC) # Fix a linking problem with visual studio when the library is the same name as the binary
    set_target_properties(uvg266 PROPERTIES OUTPUT_NAME libuvg266)
  endif()
  
endif()

target_include_directories(uvg266 PUBLIC src)
target_include_directories(uvg266 PUBLIC src/extras)
target_include_directories(uvg266 PUBLIC src/strategies)
```

--------------------------------

### Configuration Management API

Source: https://context7.com/ultravideo/uvg266/llms.txt

Manages encoder configuration lifecycle. This includes allocating a configuration structure, initializing it with default values, parsing individual options by name-value pairs, and releasing configuration memory.

```APIDOC
## Configuration Management API

### Description
Manages encoder configuration lifecycle. Allocates a configuration structure, initializes it with default values, parses individual options by name-value pairs, and releases configuration memory.

### Functions

*   `uvg_config * config_alloc(void)`: Allocates memory for a new configuration structure.
*   `int config_init(uvg_config *cfg)`: Initializes the provided configuration structure with default values. Returns 0 on success, non-zero on failure.
*   `int config_parse(uvg_config *cfg, const char *name, const char *value)`: Parses a configuration option by name and value. Returns 0 on success, non-zero on failure.
*   `void config_destroy(uvg_config *cfg)`: Releases the memory associated with the configuration structure.

### Request Example
```c
#include "uvg266.h"
#include <stdio.h>

int main() {
    const uvg_api *api = uvg_api_get(8);

    // Allocate and initialize configuration
    uvg_config *config = api->config_alloc();
    if (!config) {
        fprintf(stderr, "Failed to allocate configuration\n");
        return 1;
    }

    // Initialize with defaults
    if (!api->config_init(config)) {
        fprintf(stderr, "Failed to initialize configuration\n");
        api->config_destroy(config);
        return 1;
    }

    // Set encoding parameters
    config->width = 1920;
    config->height = 1080;
    config->framerate_num = 30;
    config->framerate_denom = 1;

    // Parse options by name
    if (!api->config_parse(config, "qp", "22") ||
        !api->config_parse(config, "preset", "medium") ||
        !api->config_parse(config, "period", "64") ||
        !api->config_parse(config, "threads", "4") ||
        !api->config_parse(config, "ref", "4")) {
        fprintf(stderr, "Failed to parse configuration options\n");
        api->config_destroy(config);
        return 1;
    }

    // Enable VVC features
    api->config_parse(config, "alf", "full");
    api->config_parse(config, "sao", "full");
    api->config_parse(config, "rdoq", "1");
    api->config_parse(config, "mip", "1");
    api->config_parse(config, "mrl", "1");

    fprintf(stdout, "Configuration: %dx%d @ %d fps, QP=%d\n",
            config->width, config->height,
            config->framerate_num, config->qp);

    // Cleanup
    api->config_destroy(config);
    return 0;
}
```

### Response
#### Success Response (200)
*   `config_alloc`: Returns a pointer to a newly allocated `uvg_config` structure on success, or NULL on failure.
*   `config_init`: Returns 0 on success, non-zero on failure.
*   `config_parse`: Returns 0 on success, non-zero on failure.
*   `config_destroy`: void function, no return value.

#### Response Example
```c
// Configuration is modified in place or returns status codes indicating success/failure.
```
```

--------------------------------

### Extract Block Costs (Python)

Source: https://github.com/ultravideo/uvg266/blob/master/rdcost-weight-tool/README.txt

Extracts block costs by running Kvazaar with specified parameters. It encodes video sequences and measures costs for quantized blocks, storing them in a compressed format. Requires editing parameters in 'extract_rdcosts.py' and 'run_filter.py' for core count and sequences.

```python
# Example usage:
# Edit parameters in extract_rdcosts.py and run_filter.py first.
# Run extract_rdcosts.py to encode sequences and extract costs.
```

--------------------------------

### Allocate and Free Picture Buffers (C)

Source: https://context7.com/ultravideo/uvg266/llms.txt

Functions for allocating and deallocating picture buffers. `picture_alloc` creates YUV 4:2:0 pictures, while `picture_alloc_csp` supports various chroma sampling formats. `picture_free` deallocates the memory.

```c
uvg_picture * picture_alloc(int32_t width, int32_t height);
uvg_picture * picture_alloc_csp(int32_t width, int32_t height,                               enum uvg_chroma_format csp);
void picture_free(uvg_picture *pic);
```

--------------------------------

### Analyzing uvg266 Output with DecoderAnalyserApp

Source: https://github.com/ultravideo/uvg266/blob/master/README.md

This command utilizes the DecoderAnalyserApp to analyze the encoded bitstream generated by uvg266. It specifies the bitstream file, trace file, trace rules for detailed logging, and the output file for the reconstructed video.

```bash
./DecoderAnalyserApp -b BQMall.266 --TraceFile=trace.txt --TraceRule=D_COMMON,D_CABAC,D_SYNTAX,D_NALUNITHEADER,D_HEADER:poc>=0 -o rec.yuv

```

--------------------------------

### Average Block Costs (Python)

Source: https://github.com/ultravideo/uvg266/blob/master/rdcost-weight-tool/README.txt

Calculates the per-QP average of the analyzed block costs across a set of sequences. This averaged data is used to update the 'default_fast_coeff_cost_wts' table in 'src/fast_coeff_cost.h'.

```python
# Example usage:
# Run rdcost_do_avg.py after analysis.
# This script computes per-QP averages for updating coefficient cost weights.
```