Filter Base

The SessionFilter class is designed to be subclassed. Without a subclass it simply acts as a passthrough filter. Each session filter manages the allocation of its respective GPUImage3 operation (lookup filter, brightness adjustment, etc.) and keeps that operation up-to-date during user interaction from the intensity slider. The operation is responsible for the manipulation of the video frame or image. Session filters also contain UI information such as their display name, thumbnail images and a view controller. In addition, they are codable allowing for their state to be saved.

See the tutorial on how to create a custom session filter using Photoshop. A simple and complex implementation of a custom session filter is also included in the sample code.

Subclassing

You must override the operation() function so it returns a freshly allocated GPUImage3 operation of your choosing. You must also override the operationUpdateNeeded(_:) function so it updates the state of your operation. When there is user interaction with the intensity slider the operationUpdateNeeded(_:) function will be called. You must then set the intensity of your operation using the current intensity value of the slider. Since every operation is different and the number of operations used is up to you, it is your responsibility to tell your operation how to react when the intensity slider is adjusted. Below is an example of overriding these functions:

override public func operation() -> ImageProcessingOperation {
    return BrightnessAdjustment()
}

override public func operationUpdateNeeded(_ op: ImageProcessingOperation) {
    let op = op as! BrightnessAdjustment

    op.brightness = Float(self.actualIntensity)
}

Some work has been done to make translating values from the intensity slider to the operation easier. The intensity slider uses values of “normalized intensity” whereas the operation uses values of “actual intensity”. Since many operations use values that are not visually pleasing they get translated to normalized values for the UI. When the intensity slider is adjusted, the normalizedIntensity variable will be updated, operationUpdateNeeded(_:) will be called, and you can then use the actualIntensity variable (which is calculated from the normalizedIntensity variable) to update your operation. This works by converting a number of one range to another range.

Adjust filters found in the Adjust tab of the EditController will usually have normalized intensity values in the range of -1.0 to 1.0 whereas primary filters found in the Filter tab of the EditController and on the CameraController will have normalized intensity values in the range of 0 to 100. It is your responsibility to set the ranges for both the normalized and actual values in your session filter initializers. You must also set the initial position of the slider, by setting the actualIntensityDefault variable.

User Interface

You can provide your own UIViewController for the session filter by overriding the viewController() function. The controller will be displayed when the filter is tapped on the Adjust tab or it is tapped twice on the Filter tab.

If you do not override the viewController() function, a default controller will be returned that contains a simple intensity slider.

Figure 1 Default view controller

The controller you return from viewController() can optionally conform to the following protocols for added functionality:

BottomBarProvider: Allows you to provide a custom bottom bar that will be visible when your controller is visible. If you do not provide a bottom bar, the default Cancel/Done bottom bar will be used.

TopBarProvider: Allows you to provide a custom top bar that will be visible when your controller is visible. If you do not provide a top bar, the default top bar that shows your filter name will be used.

SessionFilterControllerAdditions: Enables access to helper functions for the dismissal of your controller.

See more

@objcMembers
open class SessionFilter : Codable