View source for SoC 2007 Project Dynamic Video Overlays

{{SoCProject|year=2007|student=[[User:Avacore|Søren Bøg]]|mentor=[[User:Dionoea|Antoine Cellerier]]}}

== Intro ==
I ([[User:Avacore|Søren Bøg]]) will be using this area to describe and track my progress, on implementing dynamic overlays in VLC, for Google Summer of Code 2007.

== Goal ==
The goal of this is to create a video filter for VLC, allowing third party applications to overlay dynamic images on top of the VLC video output.

== Details ==
The idea here is to provide VLC with a video filter that allows a third party application (hereafter the controller) to request an overlay on top of the video that VLC is displaying. The controller is then handed a piece of shared memory with a specified pixel format. The controller may then draw all that it desires to this shared memory, Finally when the shared memory has been written to, the controller will notify VLC of the change, and VLC will then composite the overlay into subsequent frames, or at least until instructed to do something else by the controller.

This is somewhat similar the the roles that bomvl, bmovl2 and vf_overlay play for MPlayer.


== Why ==
Well, because I can, why else? More seriously I can see two practical use-cases for this. The first case is my primary motivation for working on this project.

The first use case is a computer gaming website which would like to broadcast computer game tournaments over the internet using VLC. This gaming site would then be able to overlay match statistics and other information onto the streamed video.

Additionally it may be useful for HTPC projects which can then use VLC as a canvas to draw user interfaces on. Such as the MeBox does with MPlayer and bmovl2.

== Tasks ==
{| class="wikitable"
! Task Description !! Status
|-
| Make simple no-op video filters                                                || style="background: #ddffdd" | Done
|-
| Define controller protocol                                                     || style="background: #ffffdd" | In progess
|-
| Implement full video filter                                                    || style="background: #ffdddd" | Not complete
|-
| Implement bmovl/bmovl2 compatibility                                           || Undecided
|-
| Implement interface library                                                    || Undecided
|-
| Implement [http://freevo.sourceforge.net/cgi-bin/freevo-2.0/Kaa kaa] interface || Undecided
|-
| Speed up VLC blending (Using assembly or GCC intrinsics)                       || Undecided
|-
|}

== Protocol ==
It is assumed that all messages return an indication of success or failure, which is not mentioned in the descriptions below.

=== Allocation ===

==== GenImage ====
Creates an image used for overlay.

Returns:
* A numeric ID for referring to this particular image.

==== DeleteImage ====
Deletes an image, and frees any resources

Parameters:
* The image ID to be freed

=== Atomicity ===

==== StartAtomic ====
Starts an atomic action. Any image parameter modifying commands sent until the next EndAtomic, will first be executed at the EndAtomic. Any returns will first be available at this point.

==== EndAtomic ====
Ends an atomic action. Any image parameter modifying commands since the last StartAtomic will be executed at this point, and any returns made available.

=== Image data ===

==== DataSharedMem ====
Sends image data to an overlay, using shared memory. The controlling program MAY NOT modify the shared memory, until a return has been received for this command.

Parameters:
* The image ID to send the data to
* The width of the image data
* The height of the image data
* The format of the data (FOURCC code)
* The (system-specific) identifier for the shared memory.

=== Image parameters ===

==== SetPosition ====
Set the position of an overlay image.

Parameters:
* The ID of the image to reposition
* The X-coordinate of the new position
* The Y-coordinate of the new position

==== SetAlpha ====
Sets an general transparency for a given image.

Parameters:
* The ID of the image to set transparency for.
* The new transparency

==== SetVisibility ====
Sets an images visibility.

Parameters:
* The ID of the image to set transparency for.
* The boolean indicating of the image is visible.