Implementation:Tencent Ncnn C API

Knowledge Sources	Tencent_Ncnn
Domains	Neural Network Inference, C Language Bindings
Last Updated	2026-02-09 19:00 GMT

Overview

C language bindings providing a stable ABI-compatible interface to the ncnn neural network inference library.

Description

The C API layer provides the complete C language interface for ncnn, enabling non-C++ languages to use ncnn's neural network inference capabilities through a stable Application Binary Interface (ABI). The implementation uses an adapter pattern where each ncnn C++ class that supports customization (allocators, data readers, model binary loaders, layers) has a corresponding C++ wrapper class (e.g., PoolAllocator_c_api, DataReader_c_api, Layer_c_api) that inherits from the C++ base class and overrides virtual methods to delegate to C function pointers stored in the corresponding C API struct.

The C API structs use an opaque pthis pointer to hold the actual C++ object, and static trampoline functions route calls between the C callback interface and C++ virtual dispatch. For simpler types like Option, Mat, Net, and Extractor, the implementation uses direct casts between the C opaque handle and the C++ object pointer.

The API is organized into distinct subsystems:

• Allocator API -- Pool and unlocked pool allocator creation with customizable malloc/free callbacks
• Option API -- Thread count, Vulkan compute, packing layout, and precision settings (fp16, int8, bf16)
• Mat API -- 1D-4D tensor creation, external data binding, element pack variants, reshape, clone, pixel format conversion, and mean/normalize operations
• Net API -- Model loading from file, memory, or DataReader with custom layer registration via a linked list factory
• Extractor API -- Feed input and extract output by name or index
• Layer API -- Layer creation with virtual function callbacks for load_param, load_model, create_pipeline, forward, and forward_inplace
• Drawing API -- Rectangle, text, circle, and line drawing for 1-4 channel pixel buffers

Usage

Use the C API when integrating ncnn into non-C++ applications, creating language bindings (Python via ctypes/cffi, C#, Rust, etc.), or when ABI stability across ncnn versions is required. This is also the foundation for the ncnn Python bindings and the C API test suite.

Code Reference

Source Location

• Repository: Tencent_Ncnn
• Header: src/c_api.h (401 lines)
• Implementation: src/c_api.cpp (1763 lines)

Signature

/* Version */
NCNN_EXPORT const char* ncnn_version(void);
NCNN_EXPORT int ncnn_version_number(void);

/* Allocator API */
NCNN_EXPORT ncnn_allocator_t ncnn_allocator_create_pool_allocator(void);
NCNN_EXPORT ncnn_allocator_t ncnn_allocator_create_unlocked_pool_allocator(void);
NCNN_EXPORT void ncnn_allocator_destroy(ncnn_allocator_t allocator);

/* Option API */
NCNN_EXPORT ncnn_option_t ncnn_option_create(void);
NCNN_EXPORT void ncnn_option_destroy(ncnn_option_t opt);
NCNN_EXPORT void ncnn_option_set_num_threads(ncnn_option_t opt, int num_threads);
NCNN_EXPORT void ncnn_option_set_use_vulkan_compute(ncnn_option_t opt, int enable);

/* Mat API */
NCNN_EXPORT ncnn_mat_t ncnn_mat_create_3d(int w, int h, int c, ncnn_allocator_t allocator);
NCNN_EXPORT void ncnn_mat_destroy(ncnn_mat_t mat);
NCNN_EXPORT ncnn_mat_t ncnn_mat_from_pixels(const unsigned char* pixels, int type, int w, int h, int stride, ncnn_allocator_t allocator);
NCNN_EXPORT void ncnn_mat_substract_mean_normalize(ncnn_mat_t mat, const float* mean_vals, const float* norm_vals);

/* Net API */
NCNN_EXPORT ncnn_net_t ncnn_net_create(void);
NCNN_EXPORT void ncnn_net_destroy(ncnn_net_t net);
NCNN_EXPORT int ncnn_net_load_param(ncnn_net_t net, const char* path);
NCNN_EXPORT int ncnn_net_load_model(ncnn_net_t net, const char* path);

/* Extractor API */
NCNN_EXPORT ncnn_extractor_t ncnn_extractor_create(ncnn_net_t net);
NCNN_EXPORT void ncnn_extractor_destroy(ncnn_extractor_t ex);
NCNN_EXPORT int ncnn_extractor_input(ncnn_extractor_t ex, const char* name, const ncnn_mat_t mat);
NCNN_EXPORT int ncnn_extractor_extract(ncnn_extractor_t ex, const char* name, ncnn_mat_t* mat);

Import

#include "ncnn/c_api.h"

I/O Contract

Inputs

Name	Type	Required	Description
net	ncnn_net_t	Yes	Opaque handle to an ncnn network instance, created via ncnn_net_create()
param_path	const char*	Yes	File path to the .param model parameter file
model_path	const char*	Yes	File path to the .bin model weight file
input_name	const char*	Yes	Name of the input blob as defined in the .param file
mat	ncnn_mat_t	Yes	Input tensor data (created via ncnn_mat_create_* or ncnn_mat_from_pixels)

Outputs

Name	Type	Description
return code	int	0 on success, non-zero on failure for most functions
mat	ncnn_mat_t*	Output tensor extracted by name or index via ncnn_extractor_extract()
data	void*	Raw pointer to tensor data obtained via ncnn_mat_get_data()

Usage Examples

Basic Inference with C API

#include "ncnn/c_api.h"
#include <stdio.h>

int main()
{
    /* Create network */
    ncnn_net_t net = ncnn_net_create();

    /* Configure options */
    ncnn_option_t opt = ncnn_option_create();
    ncnn_option_set_num_threads(opt, 4);
    ncnn_net_set_option(net, opt);

    /* Load model */
    ncnn_net_load_param(net, "model.param");
    ncnn_net_load_model(net, "model.bin");

    /* Create input mat (e.g., 224x224 with 3 channels) */
    ncnn_allocator_t allocator = ncnn_allocator_create_pool_allocator();
    ncnn_mat_t input = ncnn_mat_create_3d(224, 224, 3, allocator);
    ncnn_mat_fill_float(input, 0.f);

    /* Run inference */
    ncnn_extractor_t ex = ncnn_extractor_create(net);
    ncnn_extractor_input(ex, "input", input);

    ncnn_mat_t output = ncnn_mat_create();
    ncnn_extractor_extract(ex, "output", &output);

    /* Read results */
    int w = ncnn_mat_get_w(output);
    float* data = (float*)ncnn_mat_get_data(output);
    for (int i = 0; i < w; i++)
        printf("output[%d] = %f\n", i, data[i]);

    /* Cleanup */
    ncnn_mat_destroy(output);
    ncnn_mat_destroy(input);
    ncnn_extractor_destroy(ex);
    ncnn_allocator_destroy(allocator);
    ncnn_option_destroy(opt);
    ncnn_net_destroy(net);

    return 0;
}

Image Input with Pixel Conversion

/* Convert RGB pixels to ncnn Mat with mean/norm */
ncnn_allocator_t alloc = ncnn_allocator_create_pool_allocator();
ncnn_mat_t in = ncnn_mat_from_pixels(rgb_pixels, NCNN_MAT_PIXEL_RGB,
                                      width, height, width * 3, alloc);

const float mean_vals[3] = {127.5f, 127.5f, 127.5f};
const float norm_vals[3] = {1.0f / 127.5f, 1.0f / 127.5f, 1.0f / 127.5f};
ncnn_mat_substract_mean_normalize(in, mean_vals, norm_vals);