[AD] Plan for the video addon

[SiegeLord <siegelordex@xxxxxxxxxx>]

So I've fiddled a bit with the video addon, and here's my conclusions 
about what needs to be done with it before we can consider it stable in 
terms of API/semantics.

First, the API. I think it's basically good as is. I want to make the 
following modifications:

- Remove al_get_video_aspect_ratio and change al_get_video_width and 
al_get_video_height to return the width and height of the video with the 
correct aspect scale. The intention is for something like this to just work:

    ALLEGRO_BITMAP* f = al_get_video_bitmap(v);
    al_draw_scaled_bitmap(f, 0, 0, al_get_bitmap_width(f), 
al_get_bitmap_height(f), 0, 0, al_get_video_width(v), 
al_get_video_height(v), 0);

- Rename al_is_video_paused/al_pause_video to 
al_is_video_playing/al_set_video_playing to match the audio addon. Make 
al_is_video_playing return false when a video finishes.
- Add ALLEGRO_VIDEO_FINISHED event.
- Rename ALLEGRO_EVENT_VIDEO_FRAME_ALLOC to 
ALLEGRO_EVENT_VIDEO_FRAME_PREPARE (see below).
- Add al_prepare_video_frame(ALLEGRO_VIDEO* video, int frame_num) (see 
below)

The semantics of displaying a single video frame are as follows, then:

1. The backend decodes the a frame from the file and sends the 
ALLEGRO_EVENT_VIDEO_FRAME_PREPARE event with that frame number to the user.

2. The user receives the ALLEGRO_EVENT_VIDEO_FRAME_PREPARE event and 
calls al_prepare_video_frame(). This uploads the frame to the GPU.

3. Once the backend decides it's time to show the frame, it sends the 
ALLEGRO_EVENT_VIDEO_FRAME_SHOW. At the same time, it arranges for the 
pointer returned by al_get_video_frame to point to the new frame (that 
was just uploaded by the user in step 2).

4. The user receives the ALLEGRO_EVENT_VIDEO_FRAME_SHOW event, and draws 
the bitmap returned by al_get_video_frame. al_get_video_frame keeps 
returning the same frame until the next ALLEGRO_EVENT_VIDEO_FRAME_SHOW.

The ALLEGRO_EVENT_VIDEO_FRAME_PREPARE event is purely an optimization 
and will not be implemented just yet. It will not be necessary to handle 
it if the bitmap upload latency doesn't matter. I.e. after the 
ALLEGRO_EVENT_VIDEO_FRAME_SHOW is sent, al_get_video_frame will do the 
upload of that frame itself if necessary.

Naturally, ignoring all the events and just calling al_get_video_frame 
will continue to work.

In terms of implementation, I think it might be best to remove the 
ffmpeg backend. It doesn't work for me, and I have trouble figuring out 
why not. The OGV backend also has plenty of issues itself, but at least 
it plays most of the videos I throw at it. It only supports seeking to 
the beginning (it's somewhat complicated to implement anything else for 
theora), but otherwise it's pretty reasonable. I don't think we need to 
worry about this for 5.2, as the features it does support are plenty for 
a simple cutscene or some other similar use case.

The only thing that still bugs me is the aspect ratio bit. Ideally, 
al_draw_bitmap(al_get_video_frame(), 0, 0, 0)); would work, but I don't 
see a way of getting that to happen.

Comments?

-SL