v0.6 API notes

[techyian]

Input port configuration requires PortConfig parameter

For consistency with output port configuration, the call to configure input ports will now also require a PortConfig as its first parameter. Generally this will only require the overloaded constructor which accepts an encoding type and subformat type.

Capture Handlers moved to be within Callback Handlers

Currently both capture handlers and callback handlers sit underneath ports with the latter simply calling the capture handler property of the port when it wants to process data. I don't like this and as a result only callback handlers will sit underneath ports and capture handlers will be within the callbacks. This ensures ports only have reference to objects they specifically make use of directly.

Capture handlers now assigned via port configuration methods

Up until now, capture handlers have been assigned via the components themselves which doesn't make much sense and due to the above, it makes sense for all this to be done at a port level. For v0.6. you will be requried to move your capture handler reference from the component constructor to the port configuration ConfigureOutputPort method.

It is also worthwhile noting that if you currently make use of the splitter or resizer components and are passing a null capture handler, then your object initialiser should not contain any parameters for v0.6, i.e using (var splitter = new MMALSplitterComponent()). Instead, you will pass null to the splitter/resizer ConfigureOutputPort method instead for your capture handler.

File Encode/Decode work now uses existing API

My intention for this is to try and make use of the existing API to support standalone functionality and this will help with the work for #95. File encode/decode will now be initialised via the MMALStandalone class whereby there is a ProcessAsync method which is what you'll be familiar with from the rest of the library. The ProcessAsync method will accept as a parameter, the initial component in your pipeline, typically a Image or video encoder/decoder.

TransformStreamCaptureHandler renamed to InputCaptureHandler

This class was typically used with standalone encode/decode tasks where its job was to feed data from an input stream and then write output data to a separate stream. I don't really like this, so my intention for v0.6 is to separate this out with this class simply doing the input feed and it will be used alongside an IOutputCaptureHandler to handle outputting data.

ConfigureCameraSettings accepts IOutputCaptureHandler for raw Image/Video capture

This is for use with raw image/video capture so a capture handler can be assigned. The end user does not configure the Image/Video/Preview ports against the camera component, so we need a mechanism to allow users to set a capture handler for raw. In v0.6 ConfigureCameraSettings accepts optional IOutputCaptureHandlers for raw still/video capture.

ConfigureInputPort and ConfigureOutputPort accepts port type generic constraint

Overrides have been added to ConfigureInputPort and ConfigureOutputPort to accept port type generic constraints to provide flexibility over which type ports will use. In addition, these additions allow the library to provide functionality such as the raw video capture from resizer/splitter components, e.g. wiki link.

Now using TaskCompletionSource to handle port completion event tracking

I've found that TaskCompletionSource is a good solution to tracking when ports have finished completion by hooking onto their Task property and raising SetResult. Compared to what's currently in v0.5.x, this is a much better solution and should perform better too.

[techyian]

Drop full .NET Framework target

Going forward, MMALSharp will only target .NET Standard 2.0. This will make things much more straight forward. I have tested this going back as far as a Pi 1 Model B so it shouldn't cause a problem for you. You can continue to use Mono or .NET Core runtimes.

[techyian]

Use Microsoft.Extensions.Logging

As of v0.6, MMALSharp will not dictate which logging library is used to log activity. I have updated the README and Wiki on how to enable logging going forward.

[techyian]

Capture handler Process method to receive ImageContext object

The Process method seen in all capture handlers which extend OutputCaptureHandler will now receive a ImageContext object, replacing the current method definition Process(byte[] data, bool eos). The ImageContext class will contain the current frame's data, plus additional metadata which will be helpful for understanding the encoding type, end of stream status etc. This change has been made as a result of the work for #81 so capture handlers are aware of the current encoding type. Users who implement their own capture handlers will need to make the necessary changes required.

Note: See https://github.com/techyian/MMALSharp/blob/dev/src/MMALSharp.Processing/Handlers/OutputCaptureHandler.cs#L55. Users who extend OutputCaptureHandler should call the base Process method to ensure the ImageContext property is correctly assigned with the current frame's context.