Clone wiki

Filter Helper module for Corona G2 / Home

Filter Helper for Corona Graphics 2.0

The Filter Helper module is just an easy way to play with the Corona filter effects in G2. The highlight being able to easily apply multiple filters to a display object. It does not cover any animated, composite, or generated effect types. It uses a less than optimal approach to the multiple filter renders. I spent about a day and a half on it, so the module itself is not road worthy, and is meant for entertainment purposes only. All the values have been pulled from this page, except where other more updated information has been available.

Using the module


Download the module here. Feel free to contribute to the source as well.


Include the module at the top of your page:

local filters = require( "mod_filters" )

Pass a display object to the modules :new() method. The display object must support filters. A photo is a good idea for testing:

local photo = display.newImage( "photo.jpg" )
if ( photo ) then
 -- create a new filter helper instance
 local f = filters:new( photo )
end

You can now start adding filters and use the other filter helper methods:

f:addFilter( "blurGaussian" ) --add a filter

f:save() --save results to photo album

Methods

:addFilter( filterId, [ filterParamsTbl ] )

filterId (required)

The string representation of the filter, without the "filter" prefix. For example, to access the blur filter, you would use "blur", not "filter.blur"

filterParamsTbl (optional)

Most filters can take additional parameters, you can find a full list of filters and parameters here. When using filter names, do not include the "filter." prefix.

Description:

Using the addFilter method you can apply and update filters on the source display object. The filters are additive, and applied in the order called. Additional calls to the addFilter method will update the filter with the new parameters and render the filter chain again.

Example:

-- simple parameters
local params = {
 intensity = 2,
}
f:addFilter( "saturate", params )

-- Also...

f:addFilter( "saturate", { intensity = 2 } )

A few filters take more complex parameters. You can pass these in a nested fashion.

Example:

-- nested parameters
local params = {
 horizontal = {
  blurSize = 12,
  sigma = 1,
 },
 vertical = {
  blurSize = 6,
 },
}
f:addFilter( "blurGaussian", params )

It's very simple to add multiple filters to an object.

Example:

-- add multiple filters to the display object
f:addFilter( "brightness", { intensity = 2 } )
f:addFilter( "blurGaussian" )

In the example above, first the object would be run through the brightness filter, and then blurGaussian. Any parameters that are missing will use the default value.

Gotcha:

You can only have a maximum of one type of each filter on any instance. If you try to add an additional filter of the same type, the filter will only be updated in its position in the filter chain. If you want to change the order of a filter, remove it first.

Example:

f:addFilter( "brightness", { intensity = 3 } ) --creates and adds new brightness filter

-- ...later

f:addFilter( "brightness", { intensity = 5 } ) --updated brightness filter intensity

.color( r, g, b, [ a ] )

r (required)

A value for the red component ( 0 - 255 ).

g (required)

A value for the green component ( 0 - 255 ).

b (required)

A value for the blue component ( 0 - 255 ).

a (optional)

A value for the alpha ( 0 - 1 ). Defaults to 1.

Description:

A helper function that converts standard RGB colors into the new G2 color type.

Example:

This is a class method, you must use the dot syntax to access:

print( filtersMod.color( 255, 128, 64 ) )

Output:

1   0.50196078431373    0.25098039215686    1

Special Note:

You can use this directly as a color value for filters like so:

local params = {
 darkColor = filtersMod.color( 128, 255, 16, .3 )
 lightColor = filtersMod.color( 255, 64, 8, .3 )
}
f:addFilter( "duotone", params )

Additionally you can add an alias to the top of your file to make it even easier. After the require for the filters mod, add the alias:

local filtersMod = require( "mod_filters" )
local color = filtersMod.color --add an alias called color.

-- now you can just use "color" like so:

local params = {
 darkColor = color( 128, 255, 16, .3 )
 lightColor = color( 255, 64, 8, .3 )
}
f:addFilter( "duotone", params )

:destroy()

Description:

Removes the filter helper instance display object from the view. After this point all that is left is the filter table. Set the filter table to nil to mark it for garbage collection.

Example:

f:destroy() -- all associated display objects removed
f = nil -- ready for garbage collection

:getFilterChain( [ printOut ] )

printOut (Optional)

Boolean flag to additionally print the filter chain out to the console.

Description:

Returns a table array of the current filter chain.

Example:

local filterChainTbl = f:getFilterChain( true ) -- also print out to the console

Outputs:

****************************************    
FILTER CHAIN    
1)  
** saturate **  
intensity   2   
----------------------------------------    
2)  
** blurGaussian **  
----------------------------------------    

.getFilterIds()

Description:

Returns a table array of all the possible filterIds that can be used with the Filter Helper module. You can also pass these values to the introspect() method to get more details.

Example:

This is a class method, you must use the dot syntax to access:

local ids = filterMod.getFilterIds()

for _, v in ipairs( ids ) do
 print( v )
end

Outputs:

blur    
saturate    
levels  
brightness  
monotone    
...

:getSource()

Returns the display object associated with the filter helper instance.

Description:

Use this method to gain access to the underlying display object for the filter helper instance. You can then apply any regular display object methods and properties.

Example:

local filterDisplayObject = f:getSource()

filterDisplayObject.alpha = .5

:hide()

Description:

Hides the display object associated with the filter helper instance. Useful when rendering multiple filter helper instances.

Example:

local photo1 = display.newImage( "gfx/photo1.jpg" )

f1 = filters:new( photo1 )
f1:addFilter( "saturate", { intensity = 2 } )
f1:addFilter( "blurGaussian" )

f1:hide() -- filter helper display object is hidden from view

-- render another instance
local photo2 = display.newImage( "gfx/photo2.jpg" )

local f2 = filters:new( photo2 )
f2:addFilter( "brightness", { intensity = .2 } )
f2:move( 100, 100 )


f1:show() --show f1 instance again

.introspect( filterId )

filterId (required)

The string representation of the filter, without the "filter" prefix. For example, to access the blur filter, you would use "blur", not "filter.blur"

This is a class method, you must use the dot syntax to access:

local t = filterMod.introspect( filterId )

Description:

Using the introspect method you can get valuable information about a filter such as, name, properties and defaults. These can be used to build UI elements easily.

Example:

-- introspect
local t = filters.introspect( "polkaDots" )

print( "Filter: " .. t.effect )

print( "Parameters:" )
for i, v in ipairs( t.params ) do
  print( string.rep( '-', 40 ) )
  print( v )

  local defaults = t.defaults[ i ]
  for k, v in pairs( defaults ) do
    print( k, v )
  end
end

Output:

Filter: polkaDots   
Parameters: 
----------------------------------------    
numPixels   
min 4   
default 4   
max -1  
----------------------------------------    
dotRadius   
min 0   
default 1   
max 1

A value of -1 is none or no max.


:isInFilterChain( filterId )

filterId (required)

The string representation of the filter, without the "filter" prefix. For example, to access the blur filter, you would use "blur", not "filter.blur"

Returns the filter table if it exists on the object. False otherwise.

local filterTbl = f:isInFilterChain( filterId )

Description:

Use this method to not only test if a filter is active, but to also retrieve the filter info. You can use this to check current parameters:

Example:

local filterTbl = f:isInFilterChain( "saturate" )
if ( filterTbl ) then
 print( filterTbl.effect ) -- saturate
 for k,v in pairs( filterTbl.params ) do
  print( k, v)
 end
end

Output:

saturate
intensity   2

:move( xPos, yPos )

xPos (required)

The new x position for the filter helper display object.

yPos (required)

The new y position for the filter helper display object.

Description:

Use this method to move a filter display object around the screen.

Example:

f:move( 100, 25 ) -- moves display object to 100 x, and 25 y.

:new( displayObject, [ displayGroup ] )

displayObject (required)

Any Corona display object that supports Graphics 2.0 filters.

displayGroup (optional)

A display group to put the filter source in.

Returns a new instance of the filter helper module.

Description:

Use this method to create new instances of the filter helper. You can pass any display object that supports filters. The return object can be used to call the other helper methods on.

Example:

local photo = display.newImage( "gfx/photo.jpg" )

if photo then
 -- create a new filter helper instance
 local f = filters:new( photo )
 -- add a saturate filter
 f:addFilter( "saturate", { intensity = 2 } )
end

:redo()

Description:

Use this method to "redo" any action that had been undone using undo(). Once you call addFilter() again, the redo stack is emptied.

Example:

f:addFilter( "saturate", { intensity = 2 } )
f:addFilter( "blurGaussian" )

f:undo() -- removes blurGaussian

-- ...later, before calling addFilter

f:redo() -- adds blurGaussian  

:removeAll()

Description:

Use this method to remove all filters from the display object. This effectively resets the object filter chain.

Example:

f:addFilter( "saturate", { intensity = 2 } )
f:addFilter( "blurGaussian" )

f:removeAll() -- all filters cleared, resetting image

:removeFilter( filterId )

filterId (required)

The string representation of the filter, without the "filter" prefix. For example, to access the blur filter, you would use "blur", not "filter.blur"

Description:

Use this method to remove a filter type from the display object.

Example:

f:addFilter( "saturate", { intensity = 2 } )
f:addFilter( "blurGaussian" )

f:removeFilter( "saturate" ) -- removes the saturate filter, leaving blurGaussian

:save()

Description

Use this method to save the current display object with filters applied to the default photo album folder.

Example:

f:addFilter( "saturate", { intensity = 2 } )
f:addFilter( "blurGaussian" )

f:save() -- captures image and saves

:show()

Description:

Shows the display object associated with the filter helper instance. Useful when rendering multiple filter helper instances.

Example:

f:show() -- fitler helper display object is shown on screen

See :hide() for an example of rendering multiple instances.


:undo()

Description:

Use this method to "undo" the last addFilter that was applied. See also the redo() method.

Example:

f:addFilter( "saturate", { intensity = 2 } )
f:addFilter( "blurGaussian" )

f:undo() -- removes blurGaussian

f:undo() -- removes saturate 

Updated