HelpSource/Classes/SCImageKernel.schelp

   1 class:: SCImageKernel
   2 summary:: kernel class to use with SCImage
   3 categories:: GUI>Views
   4 related:: Classes/SCImage, Classes/SCImageFilter
   5
   6 DESCRIPTION::
   7
   8 code::// very experimental :)::
   9
  10 Currently this class represents the CoreImage strong::CIKernel:: you can apply to a link::Classes/SCImage::. The Kernel language is a subset of the OpenGL Shading Language. more information about the Kernel Language can be found here : http://developer.apple.com/documentation/GraphicsImaging/Reference/CIKernelLangRef/Introduction/chapter_1_section_1.html
  11
  12 and here: http://developer.apple.com/documentation/GraphicsImaging/Reference/CIKernelLangRef/chapter_2_section_1.html#//apple_ref/doc/uid/TP40004397-CH206-TPXREF101
  13
  14 here is the translation table between Kernel language Objects and SuperCollider objects
  15
  16 table::
  17 ## strong::Kernel Language Object:: || strong::SuperCollider Object::
  18 ## sampler || link::Classes/SCImage::
  19 ## __color || link::Classes/Color::
  20 ## float || link::Classes/Number::
  21 ## vec2, vec3, vec4 || link::Classes/Array::
  22 ## __table || link::Classes/SCImage:: (basically the __table modifier just use Images as a data providers - LUT)
  23 ::
  24
  25 CLASSMETHODS::
  26
  27 METHOD::new
  28 creates a new SCImageKernel
  29
  30 ARGUMENT::shader
  31 optional. the shader code string. nil by default
  32
  33 ARGUMENT::values
  34 optional. the values that match the kernel proc function defined in the shader string. nil by default
  35
  36 ARGUMENT::bounds
  37 optional. not used for now. nil by default
  38
  39 INSTANCEMETHODS::
  40
  41 METHOD::shader
  42 get or set the shader string.
  43
  44 METHOD::values
  45 get or set the values array. When setting the object indexes in the values Array must match the argument declaration order as defined in the main emphasis::kernel vec4 routine::. See link::#Examples:: for more info.
  46
  47 METHOD::isValid
  48 very basic verification to tell if all arguments of the shader are set.
  49
  50 METHOD::compile
  51 compile the SCImageKernel object (and cache it).
  52 NOTE::
  53 when rendered the first time, the kernel object is always compiled first. If you plan to change the shader string after, you must explicitely compile it to make it effective.
  54 ::
  55
  56 EXAMPLES::
  57
  58 code::
  59 /**** Kernels ****/
  60 // very experimental
  61 // COLOR INVERSION SHADER EXAMPLE
  62 (
  63 a = SCImage.new(SCDoc.helpSourceDir +/+ "images/vduck2.jpg"); // get the image
  64 k = SCImageKernel.new;
  65 k.shader_("
  66
  67 vec4    invertPixel(vec4 pix) {
  68         return vec4(1.0 - pix.r, 1.0 - pix.g, 1.0 - pix.b, pix.a);
  69 }
  70
  71 kernel vec4 _invertColor(sampler source)
  72 {
  73         vec4 pixel;
  74         pixel = sample(source, samplerCoord(source));
  75         unpremultiply(pixel);
  76         return unpremultiply(invertPixel(pixel));
  77 }
  78 ");
  79
  80 // the argument order should be kept in the array
  81 // here we need only the "sampler" argument wich should be as the translation table informs you a SCImage
  82 // the signature of the Kernel function is normaly 'kernel vec4'
  83 // you can of course add other functions in the shader
  84 k.values_([a]);
  85
  86 k.isValid.postln; // is it ok
  87 a.applyKernel(k);
  88
  89 w = a.plot(freeOnClose:true);
  90 )
  91
  92
  93 (
  94 // ANOTHER APPLE KERNEL EXAMPLE - See CoreImage programming guide for original example
  95 a = SCImage.new(SCDoc.helpSourceDir +/+ "images/vduck2.jpg"); // get the image
  96 k = SCImageKernel.new;
  97 k.shader_("
  98 vec2 testVec(float x, float y)
  99 {
 100         return vec2(x, y);
 101 }
 102
 103 kernel vec4 testKernelFromApple( sampler src, __color color, float distance, float slope )
 104 {
 105         vec4    t;
 106         float   d;
 107         d = destCoord().y * slope + distance;
 108         t = unpremultiply(sample(src, samplerCoord(src)));
 109         t = (t - d*color) / (1.0-d);
 110         return premultiply(t);
 111 }
 112 ");
 113
 114 // as stated in the Apple Example
 115 // distance - min: 0.0 max: 1.0
 116 // slope - min: -0.01 max: 0.01
 117 k.values_(
 118         [
 119         a,              // arg 0: the SCImage
 120         Color.white,    // arg 1: color
 121         0.5,            // arg 2: distance
 122         -0.002          // arg 3: slope
 123         ]
 124 );
 125
 126 a.applyKernel(k);
 127
 128 w = a.plot(freeOnClose:true);
 129 )
 130
 131
 132
 133
 134 (
 135 // OK a Better Colorfull Kernel
 136 a = SCImage.new(600@600); // get the image
 137 k = SCImageKernel.new;
 138
 139 k.shader_(
 140 // shader/kernel from toneburst.com
 141 // Generates spherical and planar displacement maps for VBO-based 3D heightfield.
 142 // http://machinesdontcare.wordpress.com
 143 "
 144 const float PI = 3.14159265359;
 145 const float TWOPI = 6.28318530718;
 146
 147 kernel vec4 _heightMap(sampler image, vec3 scale)
 148 {
 149         vec2 xyNorm = samplerCoord(image) / samplerSize(image);
 150         float u = xyNorm.x * PI;
 151         float v = xyNorm.y * TWOPI;
 152         vec3 spherical;
 153         spherical.r = cos(v) * sin(u);
 154         spherical.g = sin(v) * sin(u);
 155         spherical.b = cos(u);
 156
 157         spherical.r = (spherical.r * 0.5 + 0.5) * scale.x;
 158         spherical.g = (spherical.g * 0.5 + 0.5) * scale.y;
 159         spherical.b = (spherical.b * 0.5 + 0.5) * scale.z;
 160
 161         return vec4(spherical,1.0);
 162 }
 163 ");
 164
 165 k.values_([a, [1.0, 1.0, 1.0]]);
 166
 167 // k.isValid; // is it ok
 168 a.applyKernel(k);
 169 //.flatten; // ensure a bitmap rep so the kernel is not applied at each rendering call - uncomment that and rescale the plot window to see the difference.
 170
 171 w = a.plot(freeOnClose:true);
 172 )
 173 ::