| CRM64Pro GDK v0.18.0 A free cross-platform game development kit built on top of SDL 3.0

Loading...
Searching...
No Matches
Video
Graphics modules

## Description

Video Manager and Video objects for FFmpeg-based playback and rendering [v26.06.1].

### Overview

The Video module provides playback of movie files using the bundled FFmpeg libraries. It decodes video frames, uploads them to SDL textures and renders them through the same rendering path used by the graphics modules. Audio streams are decoded separately and routed through AudioTrack so they participate in the engine audio tag and volume system.

### Key features

- FFmpeg backend: Uses the bundled static FFmpeg build for demuxing and decoding
- File playback: Loads videos from external files using the file protocol
- CDC storage: Saves and loads video resources through raw streamable CDC blocks
- Audio integration: Routes decoded audio through AudioTrack with Music, SFX, Voice or Custom tags
- Playback control: Play, pause, resume, stop, seek and repeat playback support
- SDL rendering: Automatically renders decoded frames with retained target, viewport, alpha, color modulation and blending settings

### Supported formats

The active FFmpeg project is intentionally small and enables only the formats needed by the current backend:

Containers | MOV/MP4, AVI and raw H.264 streams
Video codecs | H.264
Audio codecs | AAC, MP3 and PCM S16LE
Protocols | File protocol only

### CDC storage

Video CDC resources are stored as a small CRM64Pro video metadata header followed by the original media payload. The payload is written through Archive::blockAddStream() and read through Archive::blockOpenStream(), so large videos are saved and played without buffering the full media file in memory. Videos loaded from CDC can also be saved back to CDC archives; the metadata header is rebuilt from the current Video object and the original payload is streamed.

### Playback methods

Video::play() | Starts playback and optionally configures extra repeats
Video::pause() | Pauses video and linked audio playback
Video::resume() | Resumes playback from a paused state
Video::stop() | Stops playback and resets the position to the beginning
Video::seek() | Seeks to a specific playback position in milliseconds
Video::decodeFrameAt() | Decodes one frame to an ARGB8888 SDL_Surface for import tools and offline processing

### Rendering methods

Videos are rendered automatically during the engine render phase once playback starts:

Video::setTarget() | Selects the screen used for automatic rendering
Video::setViewport() | Sets the target viewport, or uses the automatic native-size viewport when omitted
Video::setSourceViewport() | Sets the source crop viewport, or uses the full video frame when omitted
Video::setRenderEx() | Sets rotation, center point and flip options used by automatic rendering

### Manager type

This is a standard object manager. Each loaded video has its own decode state, playback position, SDL texture and optional linked AudioTrack stream.

### Limitations

- Network and pipe protocols are disabled
- Hardware acceleration is disabled
- swscale is not enabled; supported decoded YUV formats are uploaded directly to SDL textures
- Only the formats listed above are enabled in the bundled FFmpeg project
- CDC video blocks must be raw streamable blocks; compressed and encrypted CDC video blocks are not supported

### Best practices

- Use H.264 video with AAC audio in MP4/MOV containers for best compatibility
- Use hasAudio() before exposing video-specific audio controls
- Use setTag() to route video audio through the correct engine audio category
- Access the manager exclusively through Main::videoMgr()

Note
  The Video Manager is a singleton, automatically created once Main is instantiated. You can get a reference to this manager using Main::videoMgr() method.
  The Video Manager is automatically released when Main::terminate() is called. At this time, any resource still loaded will be released, avoiding resource leaks.
  Video objects are created through VideoMgr::loadFromFile() or VideoMgr::load(); VideoMgr::create() is intentionally unavailable because an empty Video has no playable source.

## Classes
struct | CRM64Pro::VideoInfo
| Video metadata and statistics. More...
class | CRM64Pro::Video
| Video Object class. More...
class | CRM64Pro::VideoMgr
| Video Manager class. More...

## Functions
bool | CRM64Pro::Video::info (Sint32 iMode=0) override
| Request Video object information.
const string & | CRM64Pro::Video::getName () const override
| Get the name.
Sint32 | CRM64Pro::Video::getID () const override
| Get the ID.
Sint32 | CRM64Pro::Video::play (Sint32 iRepeats=0)
| Play the video.
bool | CRM64Pro::Video::pause ()
| Pause the video playback.
bool | CRM64Pro::Video::resume ()
| Resume video from a paused state.
bool | CRM64Pro::Video::stop ()
| Stop video playback and reset to the beginning.
ePlaybackStatus | CRM64Pro::Video::status () const
| Get the video status.
Sint32 | CRM64Pro::Video::getDuration () const
| Get total duration.
Sint32 | CRM64Pro::Video::getPlaybackPosition () const
| Get current playback position.
bool | CRM64Pro::Video::seek (Sint32 iTimeMS)
| Seek to a playback position.
Uint64 | CRM64Pro::Video::getFrameCount () const
| Get total frame count.
Uint64 | CRM64Pro::Video::getFrameCurrent () const
| Get current frame index.
Sint32 | CRM64Pro::Video::getWidth () const
| Get the native video width.
Sint32 | CRM64Pro::Video::getHeight () const
| Get the native video height.
bool | CRM64Pro::Video::setBlendMode (SDL_BlendMode bmValue)
| Set the alpha blending mode.
SDL_BlendMode | CRM64Pro::Video::getBlendMode () const
| Get the alpha blending mode.
bool | CRM64Pro::Video::setAlphaMod (Sint32 iAlpha)
| Set the alpha modulation value.
Sint32 | CRM64Pro::Video::getAlphaMod () const
| Get the alpha modulation value.
bool | CRM64Pro::Video::setColorMod (Uint8 iR, Uint8 iG, Uint8 iB)
| Set the color modulation value.
Sint32 | CRM64Pro::Video::getColorMod (Uint8 &iR, Uint8 &iG, Uint8 &iB) const
| Get the color modulation value.
bool | CRM64Pro::Video::setTag (eAudioTrackTag eTag)
| Set video audio tag category.
eAudioTrackTag | CRM64Pro::Video::getTag () const
| Get video audio tag category.
bool | CRM64Pro::Video::hasAudio () const
| Check if the video media contains an audio stream.
bool | CRM64Pro::Video::hasAudioError () const
| Check if video audio playback was dropped after a runtime audio failure.
bool | CRM64Pro::Video::getInfo (VideoInfo *pVI) const
| Get video detailed information.
Sint32 | CRM64Pro::Video::decodeFrameAt (Sint32 iTimeMS, SDL_Surface **ppSurface)
| Decode and copy one video frame at or near a timestamp.
Sint32 | CRM64Pro::Video::save (const string &sCDCFile, const string &sResourceName="")
| Save the Video into a CDC file.
Sint32 | CRM64Pro::Video::save (Sint32 idCDC, const string &sResourceName="")
| Save the Video into a CDC file.
Sint32 | CRM64Pro::Video::saveToFile (const string &sFile) const
| Export the Video to an external file.
bool | CRM64Pro::Video::setTarget (Sint32 idRes=0)
| Set the video render target.
bool | CRM64Pro::Video::setViewport (const SDL_FRect *pRect=nullptr)
| Set the target viewport used for automatic video rendering.
bool | CRM64Pro::Video::setSourceViewport (const SDL_FRect *pRect=nullptr)
| Set the source viewport used for automatic video rendering.
bool | CRM64Pro::Video::setRenderEx (double dAngle=0.0, const SDL_FPoint *pCenter=nullptr, SDL_FlipMode rf=SDL_FLIP_NONE)
| Set extended render attributes used for automatic video rendering.
bool | CRM64Pro::VideoMgr::info (Sint32 iMode=0) override
| Request Video Manager information.
Sint32 | CRM64Pro::VideoMgr::close (Sint32 idVideo=0) override
| Close and destroy a video object.
Sint32 | CRM64Pro::VideoMgr::getCount () const override
| Get number of loaded objects.
Sint32 | CRM64Pro::VideoMgr::setName (Sint32 idVideo, const string &sName) override
| Change the object name.
Video * | CRM64Pro::VideoMgr::get (Sint32 idVideo)
| Get a pointer to the video using its handle.
Sint32 | CRM64Pro::VideoMgr::loadFromFile (const string &sFile, const string &sName="", eAudioTrackTag eTag=ATT_MUSIC)
| Load a video from an external file.
Sint32 | CRM64Pro::VideoMgr::load (const string &sCDCFile, const string &sName)
| Load a video stored in a CDC file.
Sint32 | CRM64Pro::VideoMgr::load (Sint32 idCDC, const string &sName)
| Load a video stored in a CDC file.
Sint32 | CRM64Pro::VideoMgr::remove (Sint32 idCDC, const string &sName)
| Remove a video stored in a CDC file.
bool | CRM64Pro::VideoMgr::exists (Sint32 idCDC, const string &sName) const
| Check if a video is stored in a CDC file.

## Function Documentation

## ◆ info() [1/2]

bool CRM64Pro::Video::info | ( | Sint32 | iMode = 0 | ) |
| override

Request Video object information.

Writes information to the default log.

Parameters

  iMode | 0 for standard output and 1 for extended output.

Returns
  true on success, or false on failure.

## ◆ getName()

const string & CRM64Pro::Video::getName | ( |  | ) | const
| override

Get the name.

Returns
  The object name.

## ◆ getID()

Sint32 CRM64Pro::Video::getID | ( |  | ) | const
| override

Get the ID.

Returns
  Object ID.

## ◆ play()

Sint32 CRM64Pro::Video::play | ( | Sint32 | iRepeats = 0 | ) |

Play the video.

Parameters

  iRepeats | Number of extra repeats after the first play. 0 plays once, -1 repeats forever.

Returns
  0 on success, or a negative error code on failure.

## ◆ pause()

bool CRM64Pro::Video::pause | ( |  | ) |

Pause the video playback.

Returns
  true on success or if already paused, or false on failure.

## ◆ resume()

bool CRM64Pro::Video::resume | ( |  | ) |

Resume video from a paused state.

Returns
  true on success or if already playing, or false on failure.

## ◆ stop()

bool CRM64Pro::Video::stop | ( |  | ) |

Stop video playback and reset to the beginning.

Returns
  true once playback is stopped. Resetting the preview frame to the beginning is best-effort.

## ◆ status()

ePlaybackStatus CRM64Pro::Video::status | ( |  | ) | const

Get the video status.

Returns
  ::PS_PLAYING, ::PS_PAUSED, ::PS_FINISHED, or ::PS_STOPPED.

## ◆ getDuration()

Sint32 CRM64Pro::Video::getDuration | ( |  | ) | const

Get total duration.

Returns
  Total duration in milliseconds.

## ◆ getPlaybackPosition()

Sint32 CRM64Pro::Video::getPlaybackPosition | ( |  | ) | const

Get current playback position.

Returns
  The position in milliseconds, or -1 if invalid.

## ◆ seek()

bool CRM64Pro::Video::seek | ( | Sint32 | iTimeMS | ) |

Seek to a playback position.

Parameters

  iTimeMS | The position in milliseconds to seek to.

Returns
  true on success, or false on failure.

## ◆ getFrameCount()

Uint64 CRM64Pro::Video::getFrameCount | ( |  | ) | const

Get total frame count.

Returns
  Total number of frames.

## ◆ getFrameCurrent()

Uint64 CRM64Pro::Video::getFrameCurrent | ( |  | ) | const

Get current frame index.

Returns
  Current frame index [0 to frame count - 1].

## ◆ getWidth()

Sint32 CRM64Pro::Video::getWidth | ( |  | ) | const

Get the native video width.

Returns
  The width in pixels.

## ◆ getHeight()

Sint32 CRM64Pro::Video::getHeight | ( |  | ) | const

Get the native video height.

Returns
  The height in pixels.

## ◆ setBlendMode()

bool CRM64Pro::Video::setBlendMode | ( | SDL_BlendMode | bmValue | ) |

Set the alpha blending mode.

Parameters

  bmValue | the SDL_BlendMode to use for rendering.

Returns
  true on success, or false on failure.

## ◆ getBlendMode()

SDL_BlendMode CRM64Pro::Video::getBlendMode | ( |  | ) | const

Get the alpha blending mode.

Returns
  The SDL_BlendMode used for rendering.

## ◆ setAlphaMod()

bool CRM64Pro::Video::setAlphaMod | ( | Sint32 | iAlpha | ) |

Set the alpha modulation value.

Parameters

  iAlpha | Ranges from 255 (opaque) to 0 (fully transparent).

Returns
  true on success, or false on failure.

## ◆ getAlphaMod()

Sint32 CRM64Pro::Video::getAlphaMod | ( |  | ) | const

Get the alpha modulation value.

Returns
  The alpha modulation value [0,255].

## ◆ setColorMod()

bool CRM64Pro::Video::setColorMod | ( | Uint8 | iR,
|  | Uint8 | iG,
|  | Uint8 | iB )

Set the color modulation value.

Parameters

  iR | Red (0-255).
  iG | Green (0-255).
  iB | Blue (0-255).

Returns
  true on success, or false on failure.

## ◆ getColorMod()

Sint32 CRM64Pro::Video::getColorMod | ( | Uint8 & | iR,
|  | Uint8 & | iG,
|  | Uint8 & | iB ) const

Get the color modulation value.

Parameters

  iR | reference to receive red [0,255].
  iG | reference to receive green [0,255].
  iB | reference to receive blue [0,255].

Returns
  0 on success, or a negative error code on failure.

## ◆ setTag()

bool CRM64Pro::Video::setTag | ( | eAudioTrackTag | eTag | ) |

Set video audio tag category.

Links the video's audio to the ConfigMgr's volume system.

Parameters

  eTag | The tag category (e.g., ATT_MUSIC or ATT_VOICE).

Returns
  true on success, or false on failure.

## ◆ getTag()

eAudioTrackTag CRM64Pro::Video::getTag | ( |  | ) | const

Get video audio tag category.

Returns
  The current eAudioTrackTag.

## ◆ hasAudio()

bool CRM64Pro::Video::hasAudio | ( |  | ) | const

Check if the video media contains an audio stream.

Returns
  true if the media file contains an audio stream, otherwise false.

Note
  Audio may still be unavailable at runtime if playback setup or decoding fails. Use hasAudioError() to check whether audio was dropped during playback.

## ◆ hasAudioError()

bool CRM64Pro::Video::hasAudioError | ( |  | ) | const

Check if video audio playback was dropped after a runtime audio failure.

Returns
  true if an audio stream was detected but disabled during playback after setup or decoding failed, otherwise false.

## ◆ getInfo()

bool CRM64Pro::Video::getInfo | ( | VideoInfo * | pVI | ) | const

Get video detailed information.

Parameters

  pVI | Pointer to a VideoInfo struct to be filled.

Returns
  true on success, or false on failure.

## ◆ decodeFrameAt()

Sint32 CRM64Pro::Video::decodeFrameAt | ( | Sint32 | iTimeMS,
|  | SDL_Surface ** | ppSurface )

Decode and copy one video frame at or near a timestamp.

Parameters

  iTimeMS | Target position in milliseconds.
  ppSurface | Output SDL surface in SDL_PIXELFORMAT_ARGB8888 format.

Returns
  0 on success, or a negative error code on failure.

Note
  The caller owns the returned surface and must release it with SDL_DestroySurface().
  This method advances the video decoder state. Sequential increasing calls decode forward efficiently; backward calls seek.
  This method cannot be used while the video is playing. Pause or stop playback first, or use a separate Video instance for offline extraction.

## ◆ save() [1/2]

Sint32 CRM64Pro::Video::save | ( | const string & | sCDCFile,
|  | const string & | sResourceName = "" )

Save the Video into a CDC file.

Parameters

  sCDCFile | Path to the CDC archive.
  sResourceName | Optional resource name to use in the CDC. If empty (default), uses the Video object's internal name.

Returns
  0 on success, or a negative error code on failure.

## ◆ save() [2/2]

Sint32 CRM64Pro::Video::save | ( | Sint32 | idCDC,
|  | const string & | sResourceName = "" )

Save the Video into a CDC file.

Parameters

  idCDC | CDC id.
  sResourceName | Optional resource name to use in the CDC. If empty (default), uses the Video object's internal name.

Returns
  0 on success, or a negative error code on failure.

## ◆ saveToFile()

Sint32 CRM64Pro::Video::saveToFile | ( | const string & | sFile | ) | const

Export the Video to an external file.

Parameters

  sFile | Output file path.

Returns
  0 on success, or a negative error code on failure.

Note
  If the output path has no matching video extension, one is appended based on the detected container.

## ◆ setTarget()

bool CRM64Pro::Video::setTarget | ( | Sint32 | idRes = 0 | ) |

Set the video render target.

Parameters

  idRes | A valid screen handle. Default uses the default screen.

Returns
  true on success, or false on failure.

## ◆ setViewport()

bool CRM64Pro::Video::setViewport | ( | const SDL_FRect * | pRect = nullptr | ) |

Set the target viewport used for automatic video rendering.

Parameters

  pRect | Destination viewport on the render target, or nullptr to use the automatic viewport.

Returns
  true on success, or false on failure.

Note
  The automatic viewport starts at (0,0), uses the native video size and shrinks to fit the target while preserving aspect ratio.

## ◆ setSourceViewport()

bool CRM64Pro::Video::setSourceViewport | ( | const SDL_FRect * | pRect = nullptr | ) |

Set the source viewport used for automatic video rendering.

Parameters

  pRect | Source viewport in video pixels, or nullptr to use the full video frame.

Returns
  true on success, or false on failure.

## ◆ setRenderEx()

bool CRM64Pro::Video::setRenderEx | ( | double | dAngle = 0.0,
|  | const SDL_FPoint * | pCenter = nullptr,
|  | SDL_FlipMode | rf = SDL_FLIP_NONE )

Set extended render attributes used for automatic video rendering.

Parameters

  dAngle | Angle in degrees for rotation.
  pCenter | SDL_FPoint pointer indicating rotation center. Default nullptr rotates around the target viewport center.
  rf | SDL_FlipMode value for flipping actions.

Returns
  true on success, or false on failure.

## ◆ info() [2/2]

bool CRM64Pro::VideoMgr::info | ( | Sint32 | iMode = 0 | ) |
| override

Request Video Manager information.

Writes manager information to the default log.

Parameters

  iMode | -1 to display only manager information. 0 (default) to display manager and all objects. A specific object ID displays manager information and only that object.

Returns
  true on success, or false on failure.

## ◆ close()

Sint32 CRM64Pro::VideoMgr::close | ( | Sint32 | idVideo = 0 | ) |
| override

Close and destroy a video object.

Parameters

  idVideo | 0 for closing all videos or the specific Video id.

Returns
  0 on success, or a negative error code on failure.

## ◆ getCount()

Sint32 CRM64Pro::VideoMgr::getCount | ( |  | ) | const
| override

Get number of loaded objects.

Returns
  The number of videos.

## ◆ setName()

Sint32 CRM64Pro::VideoMgr::setName | ( | Sint32 | idVideo,
|  | const string & | sName )
| override

Change the object name.

Parameters

  idVideo | Video id.
  sName | The video name. Must be unique.

Returns
  0 on success, or a negative error code on failure.

## ◆ get()

Video * CRM64Pro::VideoMgr::get | ( | Sint32 | idVideo | ) |

Get a pointer to the video using its handle.

Parameters

  idVideo | Video id.

Returns
  Borrowed pointer to the Video object, or nullptr if not found.

Note
  The returned pointer must not be deleted. It remains valid until the Video is closed or VideoMgr is reset or terminated.

## ◆ loadFromFile()

Sint32 CRM64Pro::VideoMgr::loadFromFile | ( | const string & | sFile,
|  | const string & | sName = "",
|  | eAudioTrackTag | eTag = ATT_MUSIC )

Load a video from an external file.

Parameters

  sFile | string containing [directory]+filename+[extension].
  sName | Object name. If empty, filename without extension is used. Must be unique and shorter than 64 characters.
  eTag | Audio category tag (default ATT_MUSIC).

Returns
  Greater than 0 on success (the Video id), or a negative error code on failure.

## ◆ load() [1/2]

Sint32 CRM64Pro::VideoMgr::load | ( | const string & | sCDCFile,
|  | const string & | sName )

Load a video stored in a CDC file.

Parameters

  sCDCFile | string containing [directory]+filename+[extension] of the CDC archive.
  sName | string with the video name.

Note
  The audio category tag is restored from the CDC metadata. Use Video::setTag() after loading to change it.
  The returned video owns the CDC archive handle opened by this call and keeps it alive until the video is closed.

Returns
  Greater than 0 on success (the Video id), or a negative error code on failure.

## ◆ load() [2/2]

Sint32 CRM64Pro::VideoMgr::load | ( | Sint32 | idCDC,
|  | const string & | sName )

Load a video stored in a CDC file.

Parameters

  idCDC | CDC id.
  sName | string with the video name.

Note
  The audio category tag is restored from the CDC metadata. Use Video::setTag() after loading to change it.
  The returned video streams from the caller-owned CDC archive. ArchiveMgr::close(idCDC) releases only the caller's archive owner reference and the video keeps its active block streams alive, but ArchiveMgr::close(0) closes CDC-backed videos and invalidates their ids and pointers.

Returns
  Greater than 0 on success (the Video id), or a negative error code on failure.

## ◆ remove()

Sint32 CRM64Pro::VideoMgr::remove | ( | Sint32 | idCDC,
|  | const string & | sName )

Remove a video stored in a CDC file.

Parameters

  idCDC | CDC id.
  sName | string with the video name.

Returns
  0 on success, or a negative error code on failure.

## ◆ exists()

bool CRM64Pro::VideoMgr::exists | ( | Sint32 | idCDC,
|  | const string & | sName ) const

Check if a video is stored in a CDC file.

Parameters

  idCDC | CDC id.
  sName | string with the video name.

Returns
  true if the resource is stored in the CDC file, or false otherwise. No error is reported.