Documentation suggestions

[MV10]

From our conversation in PR #169:

Now that I'm more familiar with the library, I think what would be helpful in the wiki is to catalog the different components and how they relate to the pipeline. The "Handling Data" topic initially made me feel as if I understood the pipeline, but when it comes to the coding I find I'm still a bit confused about how they all talk to each other. I think the topic is clear and well written, but it needs more detail. Given the number of components in the library, that may warrant a separate section. I know it's a lot of work, I'd offer to help but I don't understand the pipeline well enough yet, so call this a suggestion.

As an example, there are places where you pass null to capture handler arguments (I think it was in a splitter output example), and recently you replied to one of my comments with sample code where components wired themselves together automatically -- how and when that works is unclear.

[techyian]

I think I may have found out why you were having issues with the splitter component when calling ConfigureOutputPort using that particular port config being set. I had a look at the source code for Raspivid again and I can see the splitter component allows you to do a pixel format conversion against any of its ports, and in our case, the port config being set was new MMALPortConfig(MMALEncoding.OPAQUE, MMALEncoding.I420) meaning it was trying to do a format conversion to OPAQUE/I420. I've just tried using both new MMALPortConfig(MMALEncoding.I420, MMALEncoding.I420) and new MMALPortConfig(MMALEncoding.RGB24, MMALEncoding.RGB24) which work absolutely fine.

As an example, there are places where you pass null to capture handler arguments (I think it was in a splitter output example)

Could you find this example so I can try to explain? I'm not too sure what you're referring to.

and recently you replied to one of my comments with sample code where components wired themselves together automatically -- how and when that works is unclear.

All connections between components are explicit via ConnectTo(), they don't automatically connect themselves together in the library. I think you probably mean the ConfigureOutputPort confusion seen earlier in this post, and I doubt the splitter component is the only component that would be affected by this - the resizer component also allows format conversions so would more than likely suffer the same issues.

If you'd like to learn more about MMAL and the components themselves, I'd really encourage you to look over the API docs as they've been extremely useful to me whilst developing the library:

http://www.jvcref.com/files/PI/documentation/html/index.html
http://www.jvcref.com/files/PI/documentation/ilcomponents/video_splitter.html

[MV10]

Thanks, I'll check out those links. Does the port configuration on an input port change what comes in from that port? I had assumed it was meant to declare the input to expect from whatever is upstream.

I'll try to find the examples I had in mind. Some of them (the nulls in various places) were in the wiki examples.

[MV10]

Just a docs-related note to myself that in #159 (closed) I suggested documenting how to choose a CircularBufferCaptureHandler buffer size. For raw streams this is easy (width x height x bpp), for h.264 or other encodings you just have to estimate.

[MV10]

The way I set up a test in the second post of #176 is an example of how null args can be used in the library which I initially found confusing, but of course, the last line is how they get connected in this case. For that specific scenario, instead of a doc change, what might make initial exposure less confusing is to make the capture handler argument on port configuration optional. Then the examples wouldn't need the null. I realize this is all really due to my newbie status here but I suppose if things are easier for n00bs, we have a better chance of retaining users.

resizer.ConfigureInputPort(camConfig, cam.Camera.VideoPort, null);
encoder.ConfigureInputPort(rawConfig, null);
resizer.ConfigureOutputPort(rawConfig, null);
encoder.ConfigureOutputPort(h264Config, capture);

var connection = resizer.Outputs[0].ConnectTo(encoder, useCallback: true);

[MV10]

This was the other comment that wasn't clear to me and I suspect might warrant wiki changes:

Typically, you should call ConfigureOutputPort on components which are at the end of the pipeline and any component in between should hopefully have its configuration picked up automatically by MMAL.

#163 (comment)

[techyian]

I may have spoken to soon when I said that without fully appreciating the underlying cause. I've explained the reasoning behind the splitter component acting the way it did (setting OPAQUE pixel format). To be honest, there shouldn't really be any issue with setting ConfigureOutputPort so long as you're setting logical values so I think you can disregard that comment, apologies for the confusion.

[techyian]

The way I set up a test in the second post of #176 is an example of how null args can be used in the library which I initially found confusing, but of course, the last line is how they get connected in this case. For that specific scenario, instead of a doc change, what might make initial exposure less confusing is to make the capture handler argument on port configuration optional. Then the examples wouldn't need the null. I realize this is all really due to my newbie status here but I suppose if things are easier for n00bs, we have a better chance of retaining users.

Yes I can see the benefits of making it optional. I'll add a ticket for this.