Creating and applying custom filters

CMSoft Stereoscopic Picture Editor allows advanced users to create their own custom filters to apply in 3D pictures. All filters should use the .CLFilter extension and be copied to the application startup folder.

1. Creating a new custom filter

In order to create a new custom filter, it is necessary to create a text file with .CLFilter extension in the application startup folder. The name of the file will be the name which appears listed under the Filters menu.

The language to be used is C (more specifically, OpenCL C99). Once the file is created, the user should input the code for the desired filter. If you need information about OpenCL C99 and OpenCLTemplate please visit the tutorial.

2. Built-in variables

There are 4 built-in variables that are already declared in the environment:

float4 P – RGBA values of pixels obtained starting from current pixel;
float4 outP – RGBA values of pixel which will be written in output image. This pixel will replace P and, initially, outP = P;

float  xCoord, yCoord – image coordinates, from 0 to 1, of current pixel in width (horizontally) and height (vertically) respectively.

These variables can’t be declared again as they are already declared in the header string. Should the user need other variables, those should be declared.

The values of P correspond to the pixels of the original image in RGBA order. We recommend being careful about the alpha component because the image will not appear if alpha is set to zero.

In the pixel window, the value P corresponds to the central element:

P P P P P P P
P P P P P P P
P P P P P P P
P P P P P P P
P P P P P P P
P P P P P P P
P P P P P P P

3. Filter examples

3.1 Simple edge detector

A simple edge detection algorithm can be implemented as follows: subtract from 2x the value of the central pixel the values of its 2 closest horizontal neighbors and store the result back in the central pixel. This can be implemented as follows:

outP = fabs(2*P-P-P)*20.0f;

Remember that these are vector operations and that outP.w (the alpha component) will come out zero if the picture is not transparent since P.w = P.w = P.w = 1.0f, which implies 2*P.w – P.w – P.w = 0. Function fabs() is used to compute absolute value of the result.

We then pick the greatest value stored in outP since we want a monochromatic border. We use a scalar command to perform this operation:
outP.x = fmax(fmax(outP.x,outP.y),outP.z);

Notice that we store this maximum in the X component of outP (outP.x).

Then, we copy the value to outP’s RGB components:

outP.y = outP.x; outP.z = outP.x;

Finally, since we want borders to be black and the background to be white, we invert outP’s color:

outP = (float4)(1.0f, 1.0f, 1.0f, 1.0f) – outP;

If you want white borders and black background, swap the last line with:

outP.w = 1.0f;

because, as explained, outP.w was zero initially.

3.2 Simple flare

Let’s create a simple flare which will be centered at the 30% if the image width and 30% of image height.

First, we compute an intensity value so that exp(-intens) decreases as we move away from [0.3, 0.3] image coordinate:

float intens = (xCoord-0.3f)*(xCoord-0.3f) + (yCoord-0.2f)*(yCoord-0.2f);

Notice that we need to declare the non-built-in intens variable.

Remembering that outP = P initially, we modify outP’s red and green components using this intensity value:

outP.x *= 0.9f + 0.6f*exp(-intens*10.0f);
outP.y *= 0.9f + 0.4f*exp(-intens*20.0f);

Appendix: OpenCL C99 header, footer and host code used to apply filters

Assuming that the string inside the filter file is CoreCode and that the file name is kernelName, the following function returns the kernel code which will be compiled using OpenCL:

public static string CreateKernelCode(string kernelName, string CoreCode)
{

string kernelVoid = "__kernel void " + kernelName.Replace(" ", "").ToLower() + " ";string header = kernelVoid + @"

__write_only image2d_t img2)

{

const sampler_t smp = CLK_NORMALIZED_COORDS_FALSE | //Natural coordinates

CLK_FILTER_NEAREST; //Don't interpolate

int x0 = get_global_id(0);

int y0 = get_global_id(1);

int2 coord = (int2)(x0+3, y0+3);

uint4 val = (uint4)(0,0,0,0);

for (int i = 0; i < 7; i++)

{

for (int j = 0; j < 7; j++)

{

coord = (int2)(x0+i, y0+j);

}

}

uint4 pixel;

float4 P;

for (int i = 0; i < 7; i++)

{

for (int j = 0; j < 7; j++)

{

coord = (int2)(x0+i, y0+j);

//Converts to RGBA format

P[i][j] = (float4)((float)pixel.z, (float)pixel.y, (float)pixel.x, (float)pixel.w);

P[i][j] *= 0.00392156862745098f; //Normalize to 0-1

}

}

float4 outP = P;

float xCoord = (float)x0/(float)get_global_size(0);

float yCoord = (float)y0/(float)get_global_size(1);

";
//User manipulates P[][].

//User has to know that outP is the output pixel

string footer = @"
coord.x = x0+3;coord.y = y0+3;

outP *= 255.0f;

//outputs C# BGRA color format from RGBA

uint4 writeValue = (uint4)((uint)outP.z, (uint)outP.y, (uint)outP.x, (uint)outP.w);

//Some GPUs appear to have problems with Clamp function in OpenCL

writeValue.x = writeValue.x < 0 ? 0 : writeValue.x;

writeValue.x = writeValue.x > 255 ? 255 : writeValue.x;

writeValue.y = writeValue.y < 0 ? 0 : writeValue.y;

writeValue.y = writeValue.y > 255 ? 255 : writeValue.y;

writeValue.z = writeValue.z < 0 ? 0 : writeValue.z;

writeValue.z = writeValue.z > 255 ? 255 : writeValue.z;

writeValue.w = writeValue.w < 0 ? 0 : writeValue.w;

writeValue.w = writeValue.w > 255 ? 255 : writeValue.w;

write_imageui(img2, coord, writeValue);

}

";

return header + CoreCode + footer;
}

When the filter is called, it is then executed in the OpenCL device using the following OpenCLTemplate commands:

CLCalc.Program.Image2D CLImgSrc0 = new CLCalc.Program.Image2D(bmps);
CLCalc.Program.Image2D CLImgDst0 = new CLCalc.Program.Image2D(bmps);
CLCalc.Program.MemoryObject[] args0 = new CLCalc.Program.MemoryObject[] { CLImgSrc0, CLImgDst0 };
CLFilters[id].FilterKernel.Execute(args0, new int[] { bmps.Width - 7, bmps.Height - 7 });

Where bmps is the original bitmap, CLImgSrc0 is its copy in Device memory and CLImgDst0 is the new image created in Device memory.