I've been playing around with the video player and it took me quite a while and a lot of trial and error to figure out how context management works.
First of all, the description for
pd->graphics->video->getContext is garbled:
Gets the rendering destination for the video player. If no rendering context has been setallocates a context bitmap with the same dimensions as the vieo will be allocated.
But even if you read between the lines and parse this as
If no rendering context has been set, a context bitmap with the same dimensions as the video will be allocated
this description doesn't fully explain who owns the allocated bitmap, which makes it easy to misuse the API and end up with either double frees or memory leaks.
This is what I've been able to infer from actually testing the API and taking note of its behavior:
- When a video player is first created with
loadVideo, an associated bitmap is also allocated. Let's call this the "initial bitmap".
getContexton a completely new video player returns the initial bitmap; it doesn't actually allocate a new bitmap.
- When freeing the video player with
freePlayer, if its context is the initial bitmap, the initial bitmap is freed. Users must never free the initial bitmap with
- When setting the video player's context to a user-created bitmap with
setContext, if its context is the initial bitmap, the initial bitmap is freed. The video player does not take owership of the user-created bitmap.
- When freeing the video player when its context is a user-created bitmap, only the video player is freed. The user-created bitmap remains valid and must be freed separately with
useScreenContext(player)is more or less the same as doing
setContext(player, getDisplayBufferBitmap()), including freeing the initial bitmap if necessary.
It would be great if the video player docs could be updated to document these details and more clearly explain when the user should and should not free a video player's context.
I'd also like to report a bug:
video->renderFrame returns 0 indicating an error, no actual error message is set and the next call to
video->getError will either return NULL or the previous error message.