LCDVideoPlayer context management docs are misleading

SDK Bug Reports
, ,
1

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".
  • Calling getContext on 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 freeBitmap.
  • 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 freeBitmap.
  • 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:

If 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.