ImageFilterChains.markdown

@@ -39,15 +39,18 @@ To get a list of all the available CoreImage filters on the command line:
 
 To be able to create a property list dictionary or json object that you use to setup a core image filter in a filter chain, you need to know what the list of keys are for each filter are and for each key what the range of allowed values is that can be assigned to the filter. To get the filter description you can get the "imagefilterattribute" property from the "imagefilterchain" type. The information can be returned in one of 3 ways. Either as a json string (see the example below) or saved to a json or a plist file (-jsonfile, -plistfile). If saving to a file then after the (-jsonfile, -plistfile) option you need to provide a file path.
 
-To get the CIDroste filter attributes in ruby:
+To view the CIDroste filter attributes using ruby:
 
-	MIMeta.filterattributes(filtername: :CIDroste)
+	compact_json = MIMeta.filterattributes(filtername: :CIDroste)
+	puts JSON.pretty_generate(JSON.parse(compact_json))
+
+The above obtains the compact JSON object describing the CIDroste core image filter, parses the JSON and then outputs a more human readable form.
 
 To get the CIDroste filter attributes on the command line:
 
 	smig getproperty -type imagefilterchain -property imagefilterattributes -filtername CIDroste -jsonstring
 
-Both these methods return the compact form of the json string. To view a human friendly version, copy the result and paste it into either: [JSONLint](http://jsonlint.com) or [JSON Editor online](http://jsoneditoronline.org).
+To view a human friendly version returned by command line script, copy the result and paste it into either: [JSONLint](http://jsonlint.com) or [JSON Editor online](http://jsoneditoronline.org).
 
 ### Setting up the Properties for a Filter
 
@@ -504,6 +507,8 @@ Method 2 using the filter index in the filter chain of an earlier filter, in thi
 	  }
 	}
 
+All the CoreImage filters have a single output which is the generated image. So it is not necessary to specify anything more than the filter it comes from. The "cifilterkey" property is the key used to set the image to be assigned to the filter, most often this will be "inputImage" but some filters require more than one input image, so "cifilterkey" might also have values like "inputBackgroundImage".
+
 If the input image for a filter is from a base object like a bitmap context or a image importer object then the "objectreference" key is required and it's value is a base object reference, or alternatively the two keys "objecttype" and "objectname" are required. The value for the "objecttype" key will be "bitmapcontext", "imageimporter" or "nsgraphicscontext". The value for the "objectname" is the name of the base object given to it when it was created.
 
 	{
@@ -514,6 +519,22 @@ If the input image for a filter is from a base object like a bitmap context or a
 	  }
 	}
 
+You can also specify that an input is a static image. That means that once the image is obtained even if the image represented by the source changes the image input into the filter does not change. This option is relevant when the source for the image is a bitmap or a window context. The default value is false which means that if the source of an image changes then the input image to the filter chain will change every time source changes.
+
+The property key for the static option is: "cisourceimagekeepstatic". The following demonstrates its use:
+
+	{
+	  "cifilterkey": "inputImage",
+	  "cifiltervalueclass": "CIImage",
+	  "cifiltervalue": {
+	    "objecttype": "bitmapcontext",
+	    "objectname": "bitmapcontext.sourceforimagefilter.documentation"
+	  }
+	  "cisourceimagekeepstatic": true
+	}
+
+The keep static option can be modified in the list of render filter chain command properties.
+
 The documentation for [creating a image filter chain base object in ruby](CreatingObjectsRuby#creating-an-image-filter-chain-object) demonstrates making the input image property and adding it to the list of properties.
 
 If the base object reference identifies a "imageimporter" object or if the "objecttype" is "imageimporter" then a "imageindex" should also be supplied which refers to the index of the image in the image file. If the "imageindex" key is not supplied then the image index value defaults to 0. The image index in a image file starts at 0, so in the example below the image referred to is the second image in the image file.
@@ -590,7 +611,35 @@ The command line equivalent with the JSON already created:
 
 	smig doaction -renderfilterchain -object 3 -jsonstring '{"cifilterproperties":[{"cifilterkey":"inputScale","cifiltervalue":-0.0304,"mifiltername":"bumpdistortion"}]}'
 
-All properties except the source for input images can be changed. This does not mean that input images do not change between each time the filter chain is rendered. If the input image is the output image of a filter earlier in the filter chain then if that output image changes then the input image will capture that change. If the input image is sourced from a "bitmapcontext" or "nsgraphicscontext" base object then whenever the contents of the base object changes the filter chain object captures that it needs to update the image it uses next time the filter chain is rendered.
+All input filter properties can be modified, though the source for the image properties can not be changed. This does not mean that input images do not change between each time the filter chain is rendered. If the input image is the output image of a filter earlier in the filter chain then if that output image changes then the input image will capture that change. If the input image is sourced from a "bitmapcontext" or "nsgraphicscontext" base object then whenever the contents of the base object changes the filter chain object captures that it needs to update the image it uses next time the filter chain is rendered unless the "cisourceimagekeepstatic" attribute has been set to true in the filter property. The "cisourceimagekeepstatic" attribute can be modified at render time:
+
+```json
+{
+  "cifilterproperties": [
+    {
+      "cifilterkey": "inputImage",
+      "mifiltername": "boxblur"
+      "cifiltervalueclass": "CIImage",
+      "cisourceimagekeepstatic": false
+    }
+  ]
+}
+```
+
+Or if you need to force the input image to a filter to be updated when rendering you can set the "cisourceimageforceupdate" property to true.
+
+```json
+{
+  "cifilterproperties": [
+    {
+      "cifilterkey": "inputImage",
+      "mifiltername": "boxblur"
+      "cifiltervalueclass": "CIImage",
+      "cisourceimageforceupdate": true
+    }
+  ]
+}
+```
 
 #### Setting the source and destination rectangles when rendering
 
@@ -720,9 +769,9 @@ The JSON generated from the above looks like:
 
 ### Creating the Image Filter Chain Object
 
-The above ruby script demonstrates how to build up a filter chain and create an "imagefilterchain" base object. 
+The above ruby script demonstrates how to build up a filter chain and create an "imagefilterchain" base object. A further example of creating an image filter chain object is in [Creating Objects](CreatingObjects#creating-an-image-filter-chain-object) and another is in the [Image Filter Chain object section of the Playing with objects documentation page](PlayingWithObjects#the-image-filter-chain-object) which shows all the steps for not just creating and rendering the image filter chain object but the creation and actions related to other necessary objects.
 
-There is an example of creating the image filter chain object and rendering in the [Image Filter Chain object section of the Playing with objects documentation page](PlayingWithObjects#the-image-filter-chain-object) which shows all the steps for not just creating and rendering the image filter chain object but the creation and actions related to other necessary objects.
+The following demonstrates the three ways of creating an image filter chain object at the command line.
 
 Creating an image filter chain object with the json object defined on the command line: