Writer Class Reference

FFmpeg-backed RGBA video writer. More...

#include <MXWrite/mxwrite.hpp>

Public Member Functions
void	close ()
	Close the writer and flush pending packets.
bool	get_block_when_full () const
	Check whether the encoder queue blocks instead of dropping frames.
double	get_duration () const
	Return the encoded duration in seconds.
int64_t	get_frame_count () const
	Return the number of frames submitted to the writer.
bool	is_hardware_encode () const
	True when the active encoder backend is hardware (NVENC).
bool	is_open () const
	Check whether the writer is currently open.
bool	open (const std::string &filename, int width, int height, float fps, const char *crf)
	Open an output file using the legacy CRF string interface.
bool	open (const std::string &filename, int width, int height, float fps, const EncodeOptions &opts)
	Open an output file using explicit encoder options.
bool	open_ts (const std::string &filename, int width, int height, float fps, const char *crf)
	Open a timestamp-based output stream using the legacy CRF string interface.
bool	open_ts (const std::string &filename, int width, int height, float fps, const EncodeOptions &opts)
	Open a timestamp-based output stream using explicit encoder options.
void	set_block_when_full (bool value)
	If true, producer threads block when the encoder queue is full instead of dropping frames. Intended for headless/batch transcoding where every input frame must reach the output. Default: false (drop).
void	write (void *rgba_buffer)
	Queue a host RGBA frame for immediate-mode encoding.
bool	write_cuda_rgba (void *cuda_rgba_buffer, int src_stride, bool bottom_up=false)
	Queue a CUDA RGBA frame for encoding.
void	write_hdr_rgba16 (void *rgba16_buffer)
	Write a 16-bit RGBA frame that is already PQ- or HLG-encoded in BT.2020 primaries (8 bytes/pixel: R16,G16,B16,A16, little-endian unsigned normalised).
void	write_ts (void *rgba_buffer)
	Queue a host RGBA frame using capture timestamps.
	Writer ()=default
	Construct a closed writer.
	~Writer ()
	Close the writer on destruction if it is still open.

Detailed Description

FFmpeg-backed RGBA video writer.

The writer accepts host RGBA buffers, optional CUDA device buffers, and 16-bit HDR RGBA buffers. It can encode either frame-by-frame or from timestamped frames, depending on the open mode.

Definition at line 102 of file mxwrite.hpp.

Constructor & Destructor Documentation

Writer()

Writer::Writer ( )

default

Construct a closed writer.

~Writer()

Writer::~Writer ( )

inline

Close the writer on destruction if it is still open.

Definition at line 197 of file mxwrite.hpp.

              {
        if (is_open()) {
            close();
            opened = false;
        }
    }

Member Function Documentation

close()

void Writer::close

(

)

Close the writer and flush pending packets.

Definition at line 1465 of file mxwrite.cpp.

                   {
    std::lock_guard<std::mutex> lock(writer_mutex);
    if (!opened) {
        return;
    }
 
    stopEncoderThread();
 
    if (stream && stream->duration > 0) {
        last_duration = static_cast<double>(stream->duration) * av_q2d(stream->time_base);
    } else if (fps_num > 0 && fps_den > 0) {
        last_duration = static_cast<double>(frame_count) * static_cast<double>(fps_den) / static_cast<double>(fps_num);
    }
 
    av_write_trailer(format_ctx);
 
    if (!(format_ctx->oformat->flags & AVFMT_NOFILE)) {
        avio_closep(&format_ctx->pb);
    }
 
    av_frame_free(&frameRGBA);
    av_frame_free(&frameYUV);
    av_frame_free(&frame10);
    sws_freeContext(sws_ctx);
    av_frame_free(&upload_sw_frame);
#ifdef MXWRITE_HAS_CUDA_COPY
    // Destroy stream before tearing down FFmpeg CUDA device/frames contexts.
    if (cuda_upload_stream) {
        cudaStreamSynchronize(cuda_upload_stream);
        cudaStreamDestroy(cuda_upload_stream);
        cuda_upload_stream = nullptr;
    }
#endif
    avcodec_free_context(&codec_ctx);
    av_buffer_unref(&hw_frames_ctx);
    av_buffer_unref(&hw_device_ctx);
    avformat_free_context(format_ctx);
 
 
    while (!encode_queue.empty()) {
        releaseFrame(encode_queue.front());
        encode_queue.pop();
    }
    opened = false;
    format_ctx = nullptr;
    codec_ctx = nullptr;
    sws_ctx = nullptr;
    frameRGBA = nullptr;
    frameYUV = nullptr;
    frame10 = nullptr;
    upload_sw_frame = nullptr;
    use_hw_encode = false;
    hdr_output = false;
    stop_requested = false;
}

get_block_when_full()

bool Writer::get_block_when_full ( ) const

inline

Check whether the encoder queue blocks instead of dropping frames.

Definition at line 191 of file mxwrite.hpp.

{ return block_when_full; }

get_duration()

double Writer::get_duration

(

)

const

Return the encoded duration in seconds.

Definition at line 1521 of file mxwrite.cpp.

                                  {
    if (!opened && last_duration > 0.0) {
        return last_duration;
    }
    if (stream && stream->duration > 0) {
        return static_cast<double>(stream->duration) * av_q2d(stream->time_base);
    }
    if (fps_num > 0 && fps_den > 0) {
        return static_cast<double>(frame_count) * static_cast<double>(fps_den) / static_cast<double>(fps_num);
    }
    return 0.0;
}

get_frame_count()

int64_t Writer::get_frame_count ( ) const

inline

Return the number of frames submitted to the writer.

Definition at line 193 of file mxwrite.hpp.

{ return frame_count; }

is_hardware_encode()

bool Writer::is_hardware_encode ( ) const

inline

True when the active encoder backend is hardware (NVENC).

Definition at line 185 of file mxwrite.hpp.

{ return use_hw_encode; }

is_open()

bool Writer::is_open ( ) const

inline

Check whether the writer is currently open.

Definition at line 183 of file mxwrite.hpp.

{ return opened; }

open() [1/2]

bool Writer::open	(	const std::string &	filename,
		int	width,
		int	height,
		float	fps,
		const char *	crf )

Open an output file using the legacy CRF string interface.

Parameters

filename	Output file path.
width	Output width in pixels.
height	Output height in pixels.
fps	Output frame rate.
crf	Constant Rate Factor as a string.

Returns

true on success.

Definition at line 473 of file mxwrite.cpp.

                                                                                     {
    std::lock_guard<std::mutex> lock(writer_mutex);
    EncodeOptions opts;
    if (crf && *crf) {
        try { opts.crf = std::stoi(crf); } catch (...) {}
    }
    // Preserve legacy low-latency behaviour for old callers.
    opts.preset = "ultrafast";
    opts.tune = "zerolatency";
    opts.realtime = true;
    return openInternal(filename, w, h, fps, opts, false);
}

open() [2/2]

bool Writer::open	(	const std::string &	filename,
		int	width,
		int	height,
		float	fps,
		const EncodeOptions &	opts )

Open an output file using explicit encoder options.

Parameters

filename	Output file path.
width	Output width in pixels.
height	Output height in pixels.
fps	Output frame rate.
opts	Encoder configuration.

Returns

true on success.

Definition at line 486 of file mxwrite.cpp.

                                                                                               {
    std::lock_guard<std::mutex> lock(writer_mutex);
    return openInternal(filename, w, h, fps, opts, false);
}

open_ts() [1/2]

bool Writer::open_ts	(	const std::string &	filename,
		int	width,
		int	height,
		float	fps,
		const char *	crf )

Open a timestamp-based output stream using the legacy CRF string interface.

Parameters

filename	Output file path.
width	Output width in pixels.
height	Output height in pixels.
fps	Nominal input frame rate.
crf	Constant Rate Factor as a string.

Returns

true on success.

Definition at line 491 of file mxwrite.cpp.

                                                                                        {
    std::lock_guard<std::mutex> lock(writer_mutex);
    EncodeOptions opts;
    if (crf && *crf) {
        try { opts.crf = std::stoi(crf); } catch (...) {}
    }
    opts.preset = "ultrafast";
    opts.tune = "zerolatency";
    opts.realtime = true;
    return openInternal(filename, w, h, fps, opts, true);
}

open_ts() [2/2]

bool Writer::open_ts	(	const std::string &	filename,
		int	width,
		int	height,
		float	fps,
		const EncodeOptions &	opts )

Open a timestamp-based output stream using explicit encoder options.

Parameters

filename	Output file path.
width	Output width in pixels.
height	Output height in pixels.
fps	Nominal input frame rate.
opts	Encoder configuration.

Returns

true on success.

Definition at line 503 of file mxwrite.cpp.

                                                                                                  {
    std::lock_guard<std::mutex> lock(writer_mutex);
    return openInternal(filename, w, h, fps, opts, true);
}

set_block_when_full()

void Writer::set_block_when_full ( bool value )

inline

If true, producer threads block when the encoder queue is full instead of dropping frames. Intended for headless/batch transcoding where every input frame must reach the output. Default: false (drop).

Definition at line 189 of file mxwrite.hpp.

{ block_when_full = value; }

write()

void Writer::write

(

void *

rgba_buffer

)

Queue a host RGBA frame for immediate-mode encoding.

Parameters

rgba_buffer

Pointer to tightly packed RGBA8 pixels.

Definition at line 1002 of file mxwrite.cpp.

                                    {
    if (!rgba_buffer) {
        return;
    }
 
    {
        std::lock_guard<std::mutex> lock(writer_mutex);
        if (!opened) {
            return;
        }
    }
 
    AVFrame *queued_frame = av_frame_alloc();
    if (!queued_frame) {
        std::cerr << "Writer: failed to allocate queued frame\n";
        return;
    }
 
    if (use_hw_encode) {
        queued_frame->format = AV_PIX_FMT_CUDA;
        queued_frame->width = width;
        queued_frame->height = height;
        if (av_hwframe_get_buffer(hw_frames_ctx, queued_frame, 0) < 0) {
            std::cerr << "Writer: failed to allocate CUDA frame from hardware pool\n";
            releaseFrame(queued_frame);
            return;
        }
 
        if (av_frame_make_writable(upload_sw_frame) < 0) {
            std::cerr << "Writer: software upload frame not writable\n";
            releaseFrame(queued_frame);
            return;
        }
 
        const auto *src = static_cast<const uint8_t *>(rgba_buffer);
        for (int y = 0; y < height; ++y) {
            std::memcpy(upload_sw_frame->data[0] + static_cast<size_t>(y) * upload_sw_frame->linesize[0],
                        src + static_cast<size_t>(y) * static_cast<size_t>(width) * 4,
                        static_cast<size_t>(width) * 4);
        }
 
        if (av_hwframe_transfer_data(queued_frame, upload_sw_frame, 0) < 0) {
            std::cerr << "Writer: failed to transfer RGBA system frame to CUDA frame\n";
            releaseFrame(queued_frame);
            return;
        }
    } else {
        queued_frame->format = AV_PIX_FMT_RGBA;
        queued_frame->width = width;
        queued_frame->height = height;
        if (av_frame_get_buffer(queued_frame, 32) < 0) {
            std::cerr << "Writer: failed to allocate queued RGBA frame buffer\n";
            releaseFrame(queued_frame);
            return;
        }
        if (av_frame_make_writable(queued_frame) < 0) {
            std::cerr << "Writer: queued RGBA frame not writable\n";
            releaseFrame(queued_frame);
            return;
        }
 
        const auto *src = static_cast<const uint8_t *>(rgba_buffer);
        for (int y = 0; y < height; ++y) {
            std::memcpy(queued_frame->data[0] + static_cast<size_t>(y) * queued_frame->linesize[0],
                        src + static_cast<size_t>(y) * static_cast<size_t>(width) * 4,
                        static_cast<size_t>(width) * 4);
        }
    }
 
    {
        std::unique_lock<std::mutex> lock(queue_mutex);
        if (block_when_full.load(std::memory_order_relaxed)) {
            if (encode_queue.size() >= MAX_QUEUE_SIZE) {
                // In no-drop mode, once the queue reaches capacity we wait
                // until the encoder thread drains it, then continue.
                queue_cv.wait(lock, [this] {
                    return stop_requested || encode_queue.empty();
                });
            }
            if (stop_requested) {
                releaseFrame(queued_frame);
                return;
            }
        } else if (stop_requested || encode_queue.size() >= MAX_QUEUE_SIZE) {
            static int drop_counter = 0;
            if (++drop_counter % 30 == 0) {
                std::cerr << "Writer: dropped " << drop_counter << " SDR frames (encoder queue full)\n";
            }
            releaseFrame(queued_frame);
            return;
        }
        queued_frame->pts = frame_count++;
        encode_queue.push(queued_frame);
    }
 
    queue_cv.notify_one();
}

write_cuda_rgba()

bool Writer::write_cuda_rgba	(	void *	cuda_rgba_buffer,
		int	src_stride,
		bool	bottom_up = false )

Queue a CUDA RGBA frame for encoding.

Parameters

cuda_rgba_buffer	CUDA device pointer.
src_stride	Source row pitch in bytes.
bottom_up	Whether the source is stored bottom-up.

Returns

true if the frame was accepted.

Definition at line 1185 of file mxwrite.cpp.

                                                                                                    {
    if (!cuda_rgba_buffer || src_stride <= 0) {
        return false;
    }
 
    {
        std::lock_guard<std::mutex> lock(writer_mutex);
        if (!opened || !use_hw_encode) {
            return false;
        }
    }
 
    AVFrame *queued_frame = av_frame_alloc();
    if (!queued_frame) {
        std::cerr << "Writer: failed to allocate queued CUDA frame\n";
        return false;
    }
 
    queued_frame->format = AV_PIX_FMT_CUDA;
    queued_frame->width = width;
    queued_frame->height = height;
 
    if (av_hwframe_get_buffer(hw_frames_ctx, queued_frame, 0) < 0) {
        std::cerr << "Writer: failed to allocate CUDA frame from hardware pool\n";
        releaseFrame(queued_frame);
        return false;
    }
 
#ifdef MXWRITE_HAS_CUDA_COPY
    cudaStream_t stream = cuda_upload_stream;
    const bool use_async_stream = (stream != nullptr);
    if (!bottom_up) {
        const auto copy_err = use_async_stream
                                  ? cudaMemcpy2DAsync(
                                        queued_frame->data[0],
                                        static_cast<size_t>(queued_frame->linesize[0]),
                                        cuda_rgba_buffer,
                                        static_cast<size_t>(src_stride),
                                        static_cast<size_t>(width) * 4,
                                        static_cast<size_t>(height),
                                        cudaMemcpyDeviceToDevice,
                                        stream)
                                  : cudaMemcpy2D(
                                        queued_frame->data[0],
                                        static_cast<size_t>(queued_frame->linesize[0]),
                                        cuda_rgba_buffer,
                                        static_cast<size_t>(src_stride),
                                        static_cast<size_t>(width) * 4,
                                        static_cast<size_t>(height),
                                        cudaMemcpyDeviceToDevice);
 
        if (copy_err != cudaSuccess) {
            std::cerr << "Writer: cudaMemcpy2D device upload failed: " << cudaGetErrorString(copy_err) << "\n";
            releaseFrame(queued_frame);
            return false;
        }
    } else {
        // Flip vertically by issuing one async row copy per destination row
        // onto a single stream — kept asynchronous so launch overhead overlaps
        // and the producer thread only blocks once at cudaStreamSynchronize.
        auto *src_base = static_cast<unsigned char *>(cuda_rgba_buffer);
        auto *dst_base = queued_frame->data[0];
        const size_t row_bytes = static_cast<size_t>(width) * 4;
 
        for (int y = 0; y < height; ++y) {
            auto *src_row = src_base + static_cast<size_t>(height - 1 - y) * static_cast<size_t>(src_stride);
            auto *dst_row = dst_base + static_cast<size_t>(y) * static_cast<size_t>(queued_frame->linesize[0]);
            const auto row_copy_err = use_async_stream
                                          ? cudaMemcpyAsync(dst_row, src_row, row_bytes, cudaMemcpyDeviceToDevice, stream)
                                          : cudaMemcpy(dst_row, src_row, row_bytes, cudaMemcpyDeviceToDevice);
            if (row_copy_err != cudaSuccess) {
                std::cerr << "Writer: cudaMemcpy row upload failed: " << cudaGetErrorString(row_copy_err) << "\n";
                releaseFrame(queued_frame);
                return false;
            }
        }
    }
    // Single synchronisation point — NVENC requires the data to be ready when
    // avcodec_send_frame() reads it, and the encoder thread is decoupled by
    // the queue so this sync only serialises this one producer call.
    if (use_async_stream) {
        const auto sync_err = cudaStreamSynchronize(stream);
        if (sync_err != cudaSuccess) {
            std::cerr << "Writer: cudaStreamSynchronize failed: " << cudaGetErrorString(sync_err) << "\n";
            releaseFrame(queued_frame);
            return false;
        }
    }
#else
    std::cerr << "Writer: CUDA copy support disabled at build time\n";
    releaseFrame(queued_frame);
    return false;
#endif
 
    {
        std::unique_lock<std::mutex> lock(queue_mutex);
        if (block_when_full.load(std::memory_order_relaxed)) {
            if (encode_queue.size() >= MAX_QUEUE_SIZE) {
                queue_cv.wait(lock, [this] {
                    return stop_requested || encode_queue.empty();
                });
            }
            if (stop_requested) {
                releaseFrame(queued_frame);
                return false;
            }
        } else if (stop_requested || encode_queue.size() >= MAX_QUEUE_SIZE) {
            static int drop_counter = 0;
            if (++drop_counter % 30 == 0) {
                std::cerr << "Writer: dropped " << drop_counter << " frames (encoder queue full)\n";
            }
            releaseFrame(queued_frame);
            // Return TRUE so the producer does NOT fall back to the slow CPU
            // write() path — we already "handled" the frame (by dropping it).
            // Falling back would double-process every frame and double the drops.
            queue_cv.notify_one();
            return true;
        }
        queued_frame->pts = frame_count++;
        encode_queue.push(queued_frame);
    }
 
    queue_cv.notify_one();
    return true;
}

write_hdr_rgba16()

void Writer::write_hdr_rgba16

(

void *

rgba16_buffer

)

Write a 16-bit RGBA frame that is already PQ- or HLG-encoded in BT.2020 primaries (8 bytes/pixel: R16,G16,B16,A16, little-endian unsigned normalised).

The data is expected to originate from the HDR GPU encode pass: it is BT.2020 primaries with a non-linear PQ (or HLG) transfer already applied, so this path skips colour-space conversion and only performs (a) the BT.2020 non-constant-luminance RGB'->YCbCr' matrix, and (b) 16-bit -> 10-bit limited-range scaling, producing AV_PIX_FMT_YUV420P10LE for libx265 Main10. Requires the writer to have been opened with EncodeOptions::HdrInfo::enabled.

Parameters

rgba16_buffer

Pointer to tightly packed RGBA16 pixels.

Definition at line 1100 of file mxwrite.cpp.

                                                 {
    if (!rgba16_buffer) {
        return;
    }
 
    {
        std::lock_guard<std::mutex> lock(writer_mutex);
        if (!opened) {
            return;
        }
        if (!hdr_output) {
            std::cerr << "Writer: write_hdr_rgba16 called but writer not in HDR mode\n";
            return;
        }
    }
 
    AVFrame *queued_frame = av_frame_alloc();
    if (!queued_frame) {
        std::cerr << "Writer: failed to allocate queued HDR frame\n";
        return;
    }
    queued_frame->format = AV_PIX_FMT_YUV420P10LE;
    queued_frame->width = width;
    queued_frame->height = height;
    if (av_frame_get_buffer(queued_frame, 32) < 0) {
        std::cerr << "Writer: failed to allocate YUV420P10 buffer\n";
        releaseFrame(queued_frame);
        return;
    }
    if (av_frame_make_writable(queued_frame) < 0) {
        std::cerr << "Writer: queued HDR frame not writable\n";
        releaseFrame(queued_frame);
        return;
    }
 
    // Convert the already-PQ/HLG-encoded 16-bit BT.2020 RGBA into the
    // 10-bit limited-range YUV420 plane that libx265 Main10 expects.
    convertBt2020Rgba16EncodedToYuv420p10(
        reinterpret_cast<const uint16_t *>(rgba16_buffer),
        width * 4,
        reinterpret_cast<uint16_t *>(queued_frame->data[0]),
        queued_frame->linesize[0] / 2,
        reinterpret_cast<uint16_t *>(queued_frame->data[1]),
        queued_frame->linesize[1] / 2,
        reinterpret_cast<uint16_t *>(queued_frame->data[2]),
        queued_frame->linesize[2] / 2,
        width,
        height);
 
    queued_frame->color_primaries = static_cast<AVColorPrimaries>(
        hdr_info.color_primaries ? hdr_info.color_primaries : AVCOL_PRI_BT2020);
    queued_frame->color_trc = static_cast<AVColorTransferCharacteristic>(
        hdr_info.color_trc ? hdr_info.color_trc : AVCOL_TRC_SMPTE2084);
    queued_frame->colorspace = static_cast<AVColorSpace>(
        hdr_info.color_space ? hdr_info.color_space : AVCOL_SPC_BT2020_NCL);
    queued_frame->color_range = static_cast<AVColorRange>(
        hdr_info.color_range ? hdr_info.color_range : AVCOL_RANGE_MPEG);
 
    {
        std::unique_lock<std::mutex> lock(queue_mutex);
        if (block_when_full.load(std::memory_order_relaxed)) {
            if (encode_queue.size() >= MAX_QUEUE_SIZE) {
                queue_cv.wait(lock, [this] {
                    return stop_requested || encode_queue.empty();
                });
            }
            if (stop_requested) {
                releaseFrame(queued_frame);
                return;
            }
        } else if (stop_requested || encode_queue.size() >= MAX_QUEUE_SIZE) {
            static int drop_counter = 0;
            if (++drop_counter % 30 == 0) {
                std::cerr << "Writer: dropped " << drop_counter << " HDR frames (encoder queue full)\n";
            }
            releaseFrame(queued_frame);
            return;
        }
        queued_frame->pts = frame_count++;
        encode_queue.push(queued_frame);
    }
 
    queue_cv.notify_one();
}

write_ts()

void Writer::write_ts

(

void *

rgba_buffer

)

Queue a host RGBA frame using capture timestamps.

Parameters

rgba_buffer

Pointer to tightly packed RGBA8 pixels.

Definition at line 1311 of file mxwrite.cpp.

                                       {
    write(rgba_buffer);
}

---

The documentation for this class was generated from the following files:

• MXWrite/mxwrite.hpp
• MXWrite/mxwrite.cpp