promeki::SDLVideoWidget Class Reference

Widget that displays an UncompressedVideoPayload via SDL texture rendering. More...

#include <sdlvideowidget.h>

Inheritance diagram for promeki::SDLVideoWidget:

Collaboration diagram for promeki::SDLVideoWidget:

Public Types
enum	ScaleMode { ScaleNone , ScaleFit , ScaleStretch }
	Scaling mode for displayed images. More...

Public Member Functions
	SDLVideoWidget (ObjectBase *parent=nullptr)
	Constructs an SDLVideoWidget.
	~SDLVideoWidget ()
	Destructor. Frees the SDL texture.
void	setPayload (const UncompressedVideoPayload::Ptr &payload)
	Sets the payload to display.
void	setScaleMode (ScaleMode mode)
	Sets the scaling mode.
ScaleMode	scaleMode () const
	Returns the current scaling mode.

Static Public Member Functions
static uint32_t	mapPixelFormat (const PixelFormat &pd)
	Maps a promeki PixelFormat to an SDL pixel format.
static uint32_t	mapColorspace (const PixelFormat &pd)
	Maps a promeki PixelFormat to an SDL_Colorspace.
static bool	isDirectlyMappable (const PixelFormat &pd)
	Returns whether a format can skip CSC conversion on upload.

Protected Member Functions
void	paintEvent (PaintEvent *e) override

Detailed Description

Widget that displays an UncompressedVideoPayload via SDL texture rendering.

SDLVideoWidget manages an SDL_Texture and renders an UncompressedVideoPayload within its widget geometry. It handles aspect-ratio-preserving scaling with letterbox/pillarbox bars.

The widget obtains the SDL_Renderer from its ancestor SDLWindow. It must be a child (direct or indirect) of an SDLWindow to render.

Supported pixel formats

Every uncompressed PixelFormat the library supports can be displayed. Formats with a direct SDL equivalent (8-bit RGB/BGR/ RGBA/BGRA/ARGB/ABGR and the host-endian 16-bit variants of those) are uploaded to an SDL texture as-is. Everything else — DPX packings, v210, 10/12-bit words, YUV, float, linear, non-host endian — must be converted upstream (e.g. by a planner-inserted CSC stage) to an SDL-native PixelFormat before it reaches the widget; the widget itself does not perform CSC. isDirectlyMappable() reports which formats skip the planner's CSC stage.

Compressed pixel descriptions (e.g. JPEG_RGB8_sRGB) are not supported — the caller must decode them first.

Example

SDLWindow window("Player", 1280, 720);
SDLVideoWidget *video = new SDLVideoWidget(&window);
video->setGeometry(window.geometry());
video->setPayload(myPayload);
window.show();

Thread Safety

Thread-affine via ObjectBase / SDL. Must be created, used, and destroyed on the SDL event thread. setPayload() is thread-affine; use ObjectBase signal/slot dispatch (or EventLoop::postCallable) to deliver payloads from a producer thread.

Member Enumeration Documentation

ScaleMode

enum promeki::SDLVideoWidget::ScaleMode

Scaling mode for displayed images.

Enumerator
ScaleNone	No scaling, centered at native size.
ScaleFit	Scale to fit, preserving aspect ratio.
ScaleStretch	Stretch to fill, ignoring aspect ratio.

Constructor & Destructor Documentation

SDLVideoWidget()

promeki::SDLVideoWidget::SDLVideoWidget

(

ObjectBase *

parent = nullptr

)

Constructs an SDLVideoWidget.

Parameters

parent

Parent widget (typically an SDLWindow).

Member Function Documentation

isDirectlyMappable()

static bool promeki::SDLVideoWidget::isDirectlyMappable ( const PixelFormat &  pd )

static

Returns whether a format can skip CSC conversion on upload.

This is the fast-path predicate — it does NOT tell you whether the widget can display the format (it can display every uncompressed format via the fallback path).

Parameters

pd	The promeki pixel description.

Returns

true if the format maps directly to an SDL format.

mapColorspace()

static uint32_t promeki::SDLVideoWidget::mapColorspace ( const PixelFormat &  pd )

static

Maps a promeki PixelFormat to an SDL_Colorspace.

Used for YUV formats that mapPixelFormat() returns a direct SDL YUV format for. The colorspace property tells SDL which YCbCr→RGB matrix and which range (limited / full) to use when rendering the texture.

Returns 0 for RGB and for unsupported YUV formats — in the RGB case the caller should just let SDL use its default (sRGB).

Parameters

pd	The promeki pixel description.

Returns

An SDL_Colorspace value, or 0 if no colorspace override is needed.

mapPixelFormat()

static uint32_t promeki::SDLVideoWidget::mapPixelFormat ( const PixelFormat &  pd )

static

Maps a promeki PixelFormat to an SDL pixel format.

Returns a direct SDL format for:

• Uncompressed 8-bit RGB/BGR/RGBA/BGRA/ARGB/ABGR.
• Host-endian 16-bit variants of the above.
• 8-bit YUV 4:2:2 packed (YUY2 / UYVY) in Rec.709 or Rec.601.
• 8-bit YUV 4:2:0 NV12 / NV21 semi-planar in Rec.709 or Rec.601.
• 8-bit YUV 4:2:0 I420 (3-plane Y,U,V) in Rec.709 or Rec.601.

YUV formats are uploaded via SDL's direct YUV path — SDL performs the YCbCr→RGB conversion on the GPU when the texture is rendered, with the color matrix and range taken from the texture's colorspace property (see mapColorspace()).

Returns 0 for formats without a direct SDL equivalent (DPX, v210, linear-light float, non-host-endian 16-bit, 10/12-bit-in-16-bit-word, 422 planar, 422 NV16, compressed, etc). Formats that return 0 are still displayable — the widget falls back to CSC conversion to RGBA8_sRGB.

Parameters

pd	The promeki pixel description.

Returns

The SDL pixel format enum value, or 0 if no direct mapping.

setPayload()

void promeki::SDLVideoWidget::setPayload

(

const UncompressedVideoPayload::Ptr &

payload

)

Sets the payload to display.

The payload is uploaded to an SDL texture on the next paint. If the pixel format is not directly supported by SDL, the upload fails and the frame is dropped — callers must deliver an SDL-native PixelFormat (see isDirectlyMappable).

Parameters

payload

The payload to display.

setScaleMode()

void promeki::SDLVideoWidget::setScaleMode ( ScaleMode  mode )

inline

Sets the scaling mode.

Parameters

mode	The scaling mode.

---

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

• include/promeki/sdl/sdlvideowidget.h