HelpSource/Classes/SCImage.schelp

   1 class:: SCImage
   2 summary:: image component
   3 categories:: GUI>Views
   4 related:: Classes/SCImageFilter, Classes/SCImageKernel
   5
   6 DESCRIPTION::
   7
   8 SCImage is an image component for the Mac OS X supercollider client. SCImage is currently a wrapper around different models : you can use it for bitmap operations, image embedding for custom UI and for more advanced image processing as applying filters and kernels, both provided with the CoreImage framework.
   9
  10 SCImage currently supports most formats including tiff, bmp, gif, jpeg, png, tga...ect.. for reading. But for for writing it supports only those in code::SCImage.formats::.
  11
  12 NOTE::
  13 link::Classes/GUI:: Issue : since it is OS X only, be sure to call code::GUI.cocoa:: before any SCImage.call
  14 ::
  15
  16 CLASSMETHODS::
  17
  18 PRIVATE::initClass, prFromWindowRect, prFreeAll
  19
  20 METHOD::new
  21 Creates a new SCImage instance. multiple stands here for multiple arguments.
  22
  23 ARGUMENT::multiple
  24 May be a...
  25 list::
  26 ## link::Classes/Number:: to create an strong::empty:: image of size multiple as width and height
  27 code::
  28 i = SCImage.new(400);           // Create a 400x400 pixels SCimage.
  29 i.dump;
  30 i.free;
  31
  32 i = SCImage.new(400,200);       // Create a 400x200 pixels SCimage.
  33 i.dump;
  34 i.free;
  35 ::
  36 ## link::Classes/Point:: to create an strong::empty:: image of size multiple.x as width and multiple.y as height
  37 code::
  38 i = SCImage.new(400@200);       // Create a 400x200 pixels SCimage.
  39 i.dump;
  40 i.free;
  41 ::
  42 ## link::Classes/String:: to create an image from a strong::local file:: or from an strong::URL:: (http://, ftp://, file:///)
  43 code::
  44 //      Path string
  45 i = SCImage.new("/Library/Desktop Pictures/Ripples Blue.jpg");
  46 [i.width, i.height].postln;
  47 i.plot;
  48 i.free;
  49 //      URL string - http:// or ftp:// - blocks until image is downloaded
  50 i = SCImage.new("http://www.google.com/intl/en_ALL/images/logo.gif");
  51 i.plot;
  52 i.url;
  53 i.free;
  54 ::
  55 ::
  56
  57 METHOD::color
  58 Creates a new SCImage instance filled with the specified color.
  59 code::
  60 i = SCImage.color(400, 200, Color.blue(0.9,0.1));
  61 i.plot(freeOnClose:true);
  62 ::
  63
  64 ARGUMENT::args
  65 multiple arguments. the last argument should be a valid link::Classes/Color::
  66
  67 METHOD::open
  68 Creates a new SCImage instance from the local file at strong::path::.
  69 code::
  70 (
  71 i = SCImage.open("/Library/Desktop Pictures/Ripples Blue.jpg");
  72 i.plot(freeOnClose:true);
  73 i.url.postln;
  74 )
  75 ::
  76
  77 METHOD::openURL
  78 Creates a new SCImage instance from a valid image at the specified URL strong::path::.
  79 code::
  80 i = SCImage.openURL("file:///Library/Desktop%20Pictures/Ripples%20Blue.jpg");
  81 i.url;
  82 w = i.plot(freeOnClose:true);
  83 ::
  84
  85 METHOD::fromImage
  86 Creates a new SCImage instance from another SCImage.
  87 code::
  88 i = SCImage.new(SCDoc.helpSourceDir +/+ "images/vduck2.jpg");
  89 j = SCImage.fromImage(i);
  90 i.dump;
  91 j.dump;
  92 [i, j].do(_.plot);
  93 [i, j].do(_.free);
  94 ::
  95
  96 METHOD::fromWindow
  97 Creates a new SCImage from a portion of a SCWindow. this can be used to capture either a window or a specific SCView.
  98
  99 code::
 100 // WINDOW Example:
 101 // First create a window and draw inside of it
 102 (
 103         w = SCWindow.new;
 104         w.front; // comment this to copy offscreen window
 105         w.view.background_(Color.white);
 106         w.drawFunc = {
 107                 SCPen.translate(100, 100);
 108                 10.do{
 109                         // set the Color
 110                         SCPen.color = Color.blue(rrand(0.0, 1), rrand(0.0, 0.5));
 111                         SCPen.addWedge((100.rand)@(100.rand), rrand(10, 100), 2pi.rand, 2pi.rand);
 112                         SCPen.perform([\stroke, \fill].choose);
 113                 }
 114         };
 115         w.refresh;
 116 )
 117
 118 // then grab the window
 119 (
 120         i = SCImage.fromWindow(w);
 121         w.close;
 122         i.plot(freeOnClose:true);
 123 )
 124
 125 // VIEW Capture Example:
 126 // First create a window and add some views inside of it
 127 (
 128         w = SCWindow.new.front;
 129         b = [10, 80].asSpec;
 130         c = SCNumberBox(w, Rect(20, 20, 60, 40));
 131         a = SCSlider(w, Rect(20, 80, 100, 40))
 132                 .focusColor_(Color.red(alpha:0.2))
 133                 .action_({
 134                         c.value_(b.map(a.value).round(0.01))
 135         // round the float so it will fit in the SCNumberBox
 136                         });
 137 )
 138
 139 // then grab the window
 140 (
 141         i = SCImage.fromWindow(w, a.bounds);
 142         w.close;
 143         i.plot(freeOnClose:true);
 144 )
 145 ::
 146
 147 ARGUMENT::window
 148 the SCWindow object.
 149
 150 ARGUMENT::rect
 151 optional. the constrained rect to capture inside the SCWindow. By default, it is the window size.
 152
 153 SUBSECTION::Class variables and attributes
 154
 155 METHOD::formats
 156 returns all the valid image formats as an link::Classes/Array::
 157 code::
 158 SCImage.formats;
 159 ::
 160
 161 METHOD::compositingOperations
 162 returns all the valid compositing operations you can use when drawing an SCImage as an link::Classes/Array::
 163 code::
 164 SCImage.compositingOperations;
 165 ::
 166
 167 METHOD::interpolations
 168 returns an link::Classes/Array:: of the different levels of interpolation you can specify when drawing an SCImage.
 169 code::
 170 SCImage.interpolations;
 171 ::
 172
 173 METHOD::closeAllPlotWindows
 174 close all the SCImage plot windows currently opened.
 175
 176 INSTANCEMETHODS::
 177
 178 PRIVATE::prLockFocus, prDrawAtPoint, prSync, prApplyFilters, prTileInRect, prUpdatePixelsInRect, prGetPixel, prInit, prSetInterpolation, prFree, prSetPixel, prLoadPixels, prSetBackground, prApplyKernel, prUpdatePixels, prWriteToFile, prUnlockFocus, prInitFromURL, prSetColor, prGetColor, prSetName, prGetInterpolation, prDrawInRect
 179
 180 SUBSECTION::commons / general attributes
 181
 182 METHOD::width
 183 returns or set the width of the receiver
 184
 185 METHOD::height
 186 returns or set the height of the receiver
 187
 188 METHOD::setSize
 189 set the size of the receiver
 190
 191 METHOD::bounds
 192 returns the bounds of the receiver.
 193
 194 METHOD::free
 195 deallocate the receiver. this method is useful if you want to manage and reclaim yourself resources. otherwise you do not need to call this method since each object is automatically garbage collected.
 196 code::
 197 i = SCImage.new("/Library/Desktop Pictures/Ripples Blue.jpg");
 198 SCImage.all;
 199 i.free;
 200 SCImage.all;
 201 ::
 202
 203 METHOD::scalesWhenResized
 204 flag to tell or set if the receiver should update its bitmap representation to scale when a resize operation if performed
 205 code::
 206 (
 207         i = SCImage.new("/Library/Desktop Pictures/Ripples Blue.jpg");
 208         i.bounds.postln; // getting the dimensions
 209         w =i.plot;
 210 )
 211
 212 // changing the size of an image
 213 (
 214         i.scalesWhenResized_(true);
 215         i.setSize(400, 400 / (i.width / i.height));
 216         a =i.plot;
 217 )
 218 (
 219 a.close; w.close; i.free;
 220 )
 221 ::
 222
 223 METHOD::url
 224 returns or set the url of the receiver. Returning only if any where supplied at creation, otherwise returns nil. Setting may be used for different purpose but try to supply a valid one since it is used for archiving the image as an object.
 225 code::
 226 i = SCImage.new("http://www.google.com/intl/en_ALL/images/logo.gif");
 227 i.url;
 228 i.plot;
 229 i.free;
 230 ::
 231
 232 METHOD::accelerated
 233 if true, the receiver currently use the CoreImage model, possibly caching its data on GPU, if not the bitmap model. Set it to switch representation.
 234 WARNING::
 235 this method should never be used directly unless you know perfectly what you are doing. Since the SCImage will switch internally and manage itself the syncronization between representations.
 236 ::
 237
 238 METHOD::interpolation
 239 get or set the level of interpolation used when rendering the image - it has not effect when the SCImage is accelerated. see link::#*interpolations:: for a valid range of values.
 240 code::
 241 (
 242 i = SCImage.new(SCDoc.helpSourceDir +/+ "images/vduck2.jpg");
 243 w = i.plot;
 244 i.interpolation;                        // get the image currrent interpolation mode
 245 )
 246
 247 (
 248 i.interpolation = 'none';               // experiment with interpolation modes
 249 w.refresh;
 250 )
 251
 252 (
 253 i.interpolation = 'low';
 254 w.refresh;
 255 )
 256
 257 (
 258 i.interpolation = 1;                    // same as 'low'
 259 w.refresh;
 260 )
 261
 262 (
 263 i.interpolation = 'high';
 264 w.refresh;
 265 )
 266
 267 (
 268 i.interpolation = 'default';
 269 w.refresh;
 270 )
 271
 272 (
 273 i.accelerated_(true);
 274 i.interpolation = 'none'; // does not work on coreimage accelerated image
 275 w.refresh;
 276 )
 277
 278 i.free;
 279 ::
 280
 281 SUBSECTION::saving and archiving
 282
 283 METHOD::write
 284 write the SCImage to a file.
 285 code::
 286 i = SCImage.new("/Library/Desktop Pictures/Ripples Blue.jpg");
 287 i.dump
 288 i.write("~/Desktop/my_image.png");
 289 i.free;
 290
 291 //      storeOn / asCompileString
 292 i = SCImage.new("/Library/Desktop Pictures/Ripples Blue.jpg");
 293 i.url;
 294 i.asCompileString;
 295 i.writeArchive("~/Desktop/my_image.scd".standardizePath);
 296
 297 i.free;
 298 i = nil;
 299
 300 Document.open("~/Desktop/my_image.scd".standardizePath);
 301
 302 i = Object.readArchive("~/Desktop/my_image.scd".standardizePath);
 303 i.plot;
 304 i.free;
 305 ::
 306
 307 ARGUMENT::path
 308 the location where to save it
 309
 310 ARGUMENT::format
 311 (optional) format to use. see SCImage.formats for supported formats. If nil, it will get the format depending on the path extension.
 312
 313 SUBSECTION::rendering
 314
 315 METHOD::plot
 316 plots the image in a SCWindow.
 317 code::
 318 i = SCImage.new("/Library/Desktop Pictures/Ripples Blue.jpg");
 319 w = i.plot;
 320 w.close;
 321
 322 w = i.plot(showInfo:false);
 323 w.close;
 324 i.free;
 325
 326 // other option - image will be automatically freed when closed
 327 SCImage.new("/Library/Desktop Pictures/Ripples Blue.jpg").plot("Hello", freeOnClose:true);
 328 ::
 329
 330 ARGUMENT::name
 331 the title of the SCWindow. may be nil.
 332
 333 ARGUMENT::bounds
 334 the bounds of the SCWindow. may be nil.
 335
 336 ARGUMENT::freeOnClose
 337 flag to tell if the SCWindow should free the SCImage when closed.
 338
 339 ARGUMENT::background
 340 additional background to apply to the SCWindow. may be useful for artifacts due to alpha / compositing...
 341
 342 ARGUMENT::showInfo
 343 shows pixel coordinates while the mouse is over the image's plot window.
 344
 345 METHOD::lockFocus
 346 sets the receiver as the current graphic context. So you can use SCPen to draw inside of it.
 347
 348 METHOD::unlockFocus
 349 restore the graphic context state. the receiver is not anymore the current graphic context.
 350 code::
 351 (
 352         j = SCImage.new(400,300);
 353
 354         j.lockFocus;
 355
 356                 SCPen.translate(100, 100);
 357                 1000.do{
 358                         // set the Color
 359                         SCPen.color = Color.green(rrand(0.0, 1), rrand(0.0, 0.5));
 360                         SCPen.addAnnularWedge(
 361                                 (100.rand)@(100.rand),
 362                                 rrand(10, 50),
 363                                 rrand(51, 100),
 364                                 2pi.rand,
 365                                 2pi.rand
 366                         );
 367                         SCPen.perform([\stroke, \fill].choose);
 368                 };
 369
 370         j.unlockFocus;
 371 )
 372
 373 j.plot;
 374 j.write("~/Desktop/my_drawing.png"); // write the image
 375 j.free;
 376 ::
 377
 378 METHOD::draw
 379 shortcut for drawing inside an image. equivalent to :
 380 list::
 381 ## receiver.lockFocus
 382 ## aFunction
 383 ## receiver.unlockFocus
 384 ::
 385 code::
 386 (
 387         j = SCImage.new(400,300);
 388         j.draw({ arg image;
 389
 390                 SCPen.translate(100, 100);
 391                 1000.do {
 392                         // set the Color
 393                         SCPen.color = Color.green(rrand(0.0, 1), rrand(0.0, 0.5));
 394                         SCPen.addAnnularWedge(
 395                                 (100.rand)@(100.rand),
 396                                 rrand(10, 50),
 397                                 rrand(51, 100),
 398                                 2pi.rand,
 399                                 2pi.rand
 400                         );
 401                         SCPen.perform([\stroke, \fill].choose);
 402                 };
 403         }).plot(freeOnClose:true);
 404 )
 405
 406 //      String drawing support on the image
 407 //      drawStringAtPoint(string, point, font, color);
 408 (
 409         j = SCImage.new(150,50);
 410         j.draw({ arg bounds;
 411                 j.drawStringAtPoint("Hello, world!", 10@10, Font("Lucida Grande", 24), Color.black);
 412         });
 413 )
 414
 415 j.plot;
 416 j.write("~/Desktop/hello.png");
 417 j.free;
 418 ::
 419
 420 METHOD::drawStringAtPoint
 421 renders *correctly* a String inside an SCImage :) code::// to fix to have a compliant interface::
 422 code::
 423 (
 424         var width, height, tgHeight, ratio, str, font, color, strb, targetWidth=400, shadowColor, run = true;
 425         shadowColor = Color.black;
 426
 427         color = Color.gray(0.8);
 428         str = "I Love Pixels";
 429         font = Font("Monaco", 10);
 430         strb = str.bounds(font);
 431         width = strb.width;
 432         height = strb.height;
 433         ratio = height / width;
 434         i = SCImage(width@(height));
 435         i.draw({|bb|
 436                 SCPen.smoothing_(false);
 437                 i.drawStringAtPoint(str, 0@0, font, color);
 438         });
 439         i.interpolation_(\none);
 440         tgHeight = targetWidth * ratio;
 441         w = SCWindow.new("", Rect(400,400, 450, 150)).drawFunc_({
 442                 SCPen.setShadow(2@2, 0.4, color:Color.red);
 443                 i.drawInRect(Rect(5,5,targetWidth, tgHeight));
 444         });
 445
 446         w.view.background_(Color.white);
 447         w.onClose_({run = false; i.free;});
 448         w.front;
 449 )
 450 ::
 451
 452 METHOD::drawAtPoint
 453 render the image or a portion of it in the current graphic context.
 454 code::
 455 (
 456         var operation='sourceOver', fraction=1.0, i, w;
 457
 458         i = SCImage.new(
 459         //      "http://supercollider.sourceforge.net/theme/sc01/icon.supercollider.gif"
 460         //      SCDoc.helpSourceDir +/+ "images/duck_alpha.png"
 461                 SCDoc.helpSourceDir +/+ "images/Swamp.png"
 462         );
 463
 464         w = SCWindow.new("SCImage", Rect(120, 400, 360, 180)).front;
 465
 466         SCSlider.new(w, Rect(10, 150, 150, 16))
 467                 .value_(1.0)
 468                 .action_({ arg sl;
 469                         fraction = sl.value;
 470                         w.refresh;
 471                 });
 472
 473         SCPopUpMenu.new(w, Rect(170, 150, 100, 16))
 474                 .items_( SCImage.compositingOperations.collect({ arg i; i.asString }) )
 475                 .value_(2)
 476                 .action_({ arg pm;
 477                         operation = SCImage.compositingOperations.at(pm.value);
 478                         w.refresh;
 479                 });
 480
 481         w.onClose_({ i.free }); // free the image when the window is closed
 482
 483         w.drawFunc_({
 484
 485                 i.drawAtPoint(10@10, nil, operation, fraction);
 486
 487         });
 488 )
 489 ::
 490
 491 ARGUMENT::point
 492 the link::Classes/Point:: where to draw it
 493
 494 ARGUMENT::fromRect
 495 the portion of the SCImage to use
 496
 497 ARGUMENT::operation
 498 the compositing operation to use. code::'sourceOver':: is the default.
 499
 500 ARGUMENT::fraction
 501 the opacity to use, ranging from 0.0 (fully transparent) to 1.0 (fully opaque)
 502
 503 METHOD::drawInRect
 504 render the image or a portion of it in a specified rectangle of the current graphic context. This may stretch the image depending on the destination rect.
 505 code::
 506 (
 507         i = SCImage.new(
 508                 // "http://supercollider.sourceforge.net/theme/sc01/icon.supercollider.gif"
 509                 SCDoc.helpSourceDir +/+ "images/icon.supercollider.png"
 510         );
 511
 512         w = SCWindow.new("SCImage", Rect(120, 400, 360, 180)).front;
 513         w.onClose_({ i.free }); // free the image when the window is closed
 514         w.drawFunc_({
 515                 i.drawInRect(Rect(10,10,50,50), Rect(10,10,50,50), 2, 1.0); // only a section
 516         });
 517 )
 518 ::
 519
 520 ARGUMENT::rect
 521 the link::Classes/Rect:: where to draw it
 522
 523 ARGUMENT::fromRect
 524 the portion of the SCImage to use
 525
 526 ARGUMENT::operation
 527 the compositing operation to use. code::'sourceOver':: is the default.
 528
 529 ARGUMENT::fraction
 530 the opacity to use, ranging from 0.0 (fully transparent) to 1.0 (fully opaque)
 531
 532 METHOD::tileInRect
 533 tile the image or a portion of it in a specified rectangle of the current graphic context. This may stretch the image depending on the destination rect.
 534 code::
 535 (
 536         i = SCImage.new(
 537                 // "http://supercollider.sourceforge.net/theme/sc01/icon.supercollider.gif"
 538                 SCDoc.helpSourceDir +/+ "images/icon.supercollider.png"
 539         );
 540
 541         w = SCWindow.new("SCImage", Rect(120, 400, 360, 180)).front;
 542         w.onClose_({ i.free }); // free the image when the window is closed
 543         w.drawFunc_({
 544                 i.tileInRect(w.view.bounds, nil, 2, 1.0); // all image contents
 545         });
 546 )
 547 ::
 548
 549 ARGUMENT::rect
 550 the link::Classes/Rect:: where to draw it
 551
 552 ARGUMENT::fromRect
 553 the portion of the SCImage to use
 554
 555 ARGUMENT::operation
 556 the compositing operation to use. code::'sourceOver':: is the default.
 557 NOTE::
 558 Compositing operations are currently disabled for tileInRect
 559 ::
 560
 561 ARGUMENT::fraction
 562 the opacity to use, ranging from 0.0 (fully transparent) to 1.0 (fully opaque)
 563
 564 SUBSECTION::Instance Methods / accessing and setting pixels
 565
 566 METHOD::setPixel
 567 fill a pixel located at x @ y.
 568 code::
 569 i = SCImage.color(60, 60, Color.blue(0.1,0.1));
 570 w = i.plot;
 571 i.setPixel([255,0,0,255].asRGBA, 0, 0); // setting red
 572 w.refresh;
 573 ("pixel at 0 @ 0:"+i.getPixel(0,0).rgbaArray).postln;
 574 i.free;
 575 ::
 576
 577 ARGUMENT::rgbaInteger
 578 an 32 bit link::Classes/Integer:: containing color information packed as 8bit RGBA
 579
 580 METHOD::getPixel
 581 retrieve the pixel value at x @ y as a RGBA integer
 582 code::
 583 // A simple example on how to manipulate pixels with SCImage
 584 b = Int32Array[
 585         Integer.fromRGBA(255,0,0,255), // red
 586         Integer.fromRGBA(0,255,0,255), // green
 587         Integer.fromRGBA(0,0,255,255), // blue
 588         Integer.fromRGBA(255,0,255,255) // purple
 589 ];
 590
 591 b[0].red; // 255 see Integer.red
 592 b[0].green; // 0 see Integer.green
 593 b[0].blue; // 0 see Integer.blue
 594 b[0].alpha; // 255 see Integer.alpha
 595
 596 a = SCImage.new(b.size@1).pixels_(b).interpolation_(\none);
 597 a.plot;
 598
 599
 600 // Set + Get
 601 a.setPixel([255, 0, 255, 128].asRGBA /* create an Integer from 0-255 integer rgba value */, 0, 0).plot;
 602 p = a.getPixel(0,0);
 603
 604 p.red; // 255
 605 p.green; // 0
 606 p.blue; // 255
 607 p.alpha; // 128
 608
 609 // now another important example
 610 a.setPixel([255, 0, 255, 0].asRGBA, 1, 0).plot; // clear color -> alpha is 0
 611 p = a.getPixel(1,0);
 612
 613 p.red; // you expect 255 but you get 0 ??? Why = because SCImage uses premultiplied color component value internally
 614 // meaning all Red, Green, and Blue component are premultiplied by the alpha
 615 // if alpha is 0 you get 0 back for all components.
 616
 617 p.green; // 0
 618 p.blue; // 0
 619 p.alpha; // 0
 620
 621 p = a.getColor(1,0); // more explicit - but same here
 622 ::
 623
 624 METHOD::setColor
 625 fill the pixel located at x @ y with the specified strong::color::.
 626
 627 METHOD::getColor
 628 retrieve the pixel value at x @ y as a link::Classes/Color::.
 629
 630 METHOD::pixels
 631 retrieve or set all the pixels of the receiver.
 632 NOTE::
 633 Carefull: the returned Array is a link::Classes/Int32Array:: of size receiver.width * receiver.height containing all pixel values as 32bit Integer
 634 ::
 635
 636 ARGUMENT::array
 637 an link::Classes/Int32Array:: of size receiver.width * receiver.height containing all pixel values as 32bit Integer
 638
 639 METHOD::loadPixels
 640 load all the pixels of the receiver in an array. it is better and faster to call this function instead of link::#-pixels:: if you plan to retrieve frequently the pixel data (since it won't allocate a new array everytime !)
 641 code::
 642 // exec one line at a time
 643 i = SCImage.new(
 644         // "http://supercollider.sourceforge.net/theme/sc01/icon.supercollider.gif"
 645         SCDoc.helpSourceDir +/+ "images/icon.supercollider.png"
 646 );
 647
 648 // first grab the pixels
 649 p = i.pixels;
 650
 651 // do some mods - here invert
 652 i.invert;
 653
 654 // reload directly in my array - do not need to call i.pixels again
 655 i.loadPixels(p);
 656 i.free;
 657 p;
 658 ::
 659
 660 ARGUMENT::array
 661 the array that will be filled. Should be an link::Classes/Int32Array:: of size receiver.width * receiver.height.
 662
 663 ARGUMENT::region
 664 the targeted rectangular region. (nil by default, meaning full size)
 665
 666 ARGUMENT::start
 667 the start index of the array.
 668
 669 METHOD::setPixels
 670 set the pixels in a specific portion of the receiver.
 671 code::
 672 (
 673         i = SCImage.new(20@20);
 674         i.pixels_(
 675                 Int32Array.fill(i.width * i.height, {
 676                         Integer.fromRGBA(255.rand,127.rand,255.rand,255)
 677                 })
 678         );
 679         //i.interpolation_(\none); // uncomment to see the difference
 680         w = i.plot(freeOnClose:true);
 681         i.pixels.postln;
 682 )
 683
 684 (
 685         i = SCImage.color(50@50, Color.white);
 686         i.setPixels(
 687                 Int32Array.fill(20*20,{Integer.fromRGBA(255.rand, 127.rand, 255.rand, 255)}),
 688                 Rect(10,10,20,20)
 689         );
 690         i.interpolation_(\none); // uncomment to see the difference
 691         w = i.plot(freeOnClose:true);
 692         i.pixels.postln;
 693 )
 694 ::
 695
 696 ARGUMENT::array
 697 an link::Classes/Int32Array:: of size strong::rect::.width * strong::rect::.height containing all pixel values as 32bit Integer
 698
 699 ARGUMENT::rect
 700 a rectangle defining the portion to update in the receiver. By default strong::rect:: is nil, meaning full image size.
 701
 702 ARGUMENT::start
 703 the array start index.
 704
 705 SUBSECTION::Instance Methods / Attributes for SCImageFilter support
 706
 707 see link::Classes/SCImageFilter:: for more info
 708
 709 METHOD::applyFilters
 710 apply an array of link::Classes/SCImageFilter:: to the image. this should be considered as an in place operation, meaning the SCImage is altered after it.
 711 code::
 712 // ******** Built In CoreImage Generators ********
 713 // Generators are not filters, they actually create an image but do not need an input image
 714 // you just have to create an image of a new size
 715 // ** The Simple Random Filter **
 716 (
 717 f = SCImageFilter.new(\CIRandomGenerator);
 718 a = SCImage.new(500@500);
 719 a.applyFilters(f);
 720 w = a.plot(freeOnClose:true, background:Color.black);
 721 a.bounds.postln;
 722 )
 723
 724 // ** The StarShine example **
 725 (
 726 var width=500, height=500, centerVector;
 727
 728 centerVector = [ width*0.5, height*0.5 ];
 729 a = SCImage.new(500@500);
 730 f = SCImageFilter.new(\CIStarShineGenerator);
 731
 732 f.center_(centerVector);
 733 f.radius_(width*0.05);
 734 f.color_(Color.blue);
 735 f.crossWidth_(2.0);
 736 f.crossAngle_(0.0);
 737 f.crossOpacity_(-4.0);
 738
 739 a.applyFilters(f);
 740 w = a.plot(freeOnClose:true, background:Color.gray); // change background to see
 741 )
 742
 743
 744 // ** Starshine + Pixellate + ZoomBlur **
 745 (
 746 var width=500, height=500, centerVector;
 747
 748 centerVector = [ width*0.5, height*0.5 ];
 749 a = SCImage.new(500@500);
 750
 751 f = SCImageFilter.new(\CIStarShineGenerator);
 752 g = SCImageFilter.new(\CIPixellate);
 753 h = SCImageFilter.new(\CIZoomBlur);
 754
 755 f.center_(centerVector);
 756 f.radius_(width*0.05);
 757 f.color_(Color.blue);
 758 f.crossWidth_(2.0);
 759 f.crossAngle_(0.0);
 760 f.crossOpacity_(-4.0);
 761 g.center_(centerVector);
 762 h.center_(centerVector);
 763 h.amount_(50);
 764
 765 a.applyFilters([f, g, h]);
 766 w = a.plot(freeOnClose:true, background:Color.black);
 767 )
 768 ::
 769
 770 ARGUMENT::filters
 771 a SCImageFilter or an array of link::Classes/SCImageFilter:: to be applied
 772
 773 ARGUMENT::crop
 774 the crop region to finally use. This may be required for extending bounds since some SCImageFilter / CoreImageFilters require to set a wider region (to be applied correctly) or may create a huge image. Setting crop to nil sets no crop region. In case the current maximum size of a filtered SCImage is 4096 / 4096. Any larger size will be clipped. by default crop is constrained to the receiver bounds.
 775
 776 ARGUMENT::region
 777 NOTE::
 778 supported only in Mac OS 10.5 and later.
 779 ::
 780 option to constrain the filter to a specific region IN the SCImage.
 781
 782 METHOD::filteredWith
 783 returns a new SCImage, copy of the receiver filtered with an array of SCImageFilter. arguments are the same as link::#-applyFilters:: (except for strong::region::).
 784 NOTE::
 785 Beware: you are responsible for freeing the newly created SCImage !!!
 786 ::
 787
 788 METHOD::filters
 789 filters is the instance variable that holds the array of SCImageFilter attached to the receiver. This is a convenient for applying filters out place and changing the SCImageFilter's attributes. see link::#-addFilter::, link::#-removeFilter::
 790
 791 see link::Classes/SCImageFilter:: for an example on how to use the strong::filters:: array.
 792
 793 METHOD::addFilter
 794 you can also attach filters to the receiver for real-time changing operations. In this case the receiver will create a cache before each rendering to maintain his previous state, and allowing you to use filters without applying them in place. The cache is managed directly by the receiver. you can add several filters to the receiver, the first filter in the array is the first applied in the rendering chain.
 795
 796 see link::Classes/SCImageFilter:: for an example on how to use strong::addFilter::.
 797
 798 ARGUMENT::filter
 799 a SCImageFilter to apply before rendering of the image
 800
 801 METHOD::removeFilter
 802
 803 see link::Classes/SCImageFilter:: for an example on how to use strong::removeFilter::.
 804
 805 ARGUMENT::filter
 806 the SCImageFilter to remove from the rendering chain.
 807
 808 METHOD::flatten
 809 if link::#-filters:: is not zero sized, this method will apply all those filters in place. if the image is accelerated this method force a bitmap representation of the receiver.
 810
 811 METHOD::invert
 812 invert the receiver
 813 code::
 814 (
 815 i = SCImage.new("/Library/Desktop Pictures/Ripples Blue.jpg");
 816 i.invert;
 817 i.plot(freeOnClose:true);
 818 )
 819 ::
 820
 821 METHOD::crop
 822 crop the receiver
 823 code::
 824 (
 825 i = SCImage.new("/Library/Desktop Pictures/Ripples Blue.jpg");
 826 i.crop( Rect(10,10,120,100) );
 827 i.plot(freeOnClose:true);
 828 )
 829 ::
 830
 831 ARGUMENT::aRect
 832 the cropping region
 833
 834 SUBSECTION::Instance Methods / Attributes for SCImageKernel support
 835
 836 see link::Classes/SCImageKernel:: for examples and more info.
 837
 838 METHOD::applyKernel
 839 apply a Kernel in place. the receiver is modified after this call.
 840
 841 ARGUMENT::kernel
 842 a link::Classes/SCImageKernel::
 843
 844 EXAMPLES::
 845
 846 SUBSECTION::Views addition
 847
 848 you can now use a SCImage as a valid view background. 16 drawing modes are defined to behave differently.
 849
 850 definitionList::
 851 ## tileMode values: ||
 852 table::
 853 ## 1 || fixed to left, fixed to top
 854 ## 2 || horizontally tile, fixed to top
 855 ## 3 || fixed to right, fixed to top
 856 ## 4 || fixed to left, vertically tile
 857 ## 5 || horizontally tile, vertically tile
 858 ## 6 || fixed to right, vertically tile
 859 ## 7 || fixed to left, fixed to bottom
 860 ## 8 || horizontally tile, fixed to bottom
 861 ## 9 || fixed to right, fixed to bottom
 862 ## 10 || fit
 863 ## 11 || center, center (scale)
 864 ## 12 || center , fixed to top
 865 ## 13 || center , fixed to bottom
 866 ## 14 || fixed to left, center
 867 ## 15 || fixed to right, center
 868 ## 16 || center, center (no scale)
 869 ::
 870
 871 ## SCView:backgroundImage_ ||
 872
 873 strong::image:: - the SCImage to use
 874
 875 strong::tileMode:: - the mode to use. by default fixed to left, fixed to top
 876
 877 strong::alpha:: - opacity 0 < x < 1
 878
 879 strong::fromRect:: - the portion of the image to use. by default use the full image.
 880 ::
 881 code::
 882 (
 883         b = 1.0;
 884         a = SCImage.new(SCDoc.helpSourceDir +/+ "images/vduck2.jpg");
 885         r = Rect(20,3,40,40);
 886         w = SCWindow.new("SCImage background" /*, textured:false*/ );
 887         w.view.background_(Color.gray);
 888         w.view.backgroundImage_(a, 5, b, r);
 889         w.front;
 890 )
 891
 892 // monte carlo :) exec every line to test
 893 // r = nil; // uncomment for full image
 894 w.view.backgroundImage_(a, 1, b, r);
 895 w.view.backgroundImage_(a, 2, b, r);
 896 w.view.backgroundImage_(a, 3, b, r);
 897 w.view.backgroundImage_(a, 4, b, r);
 898 w.view.backgroundImage_(a, 5, b, r);
 899 w.view.backgroundImage_(a, 6, b, r);
 900 w.view.backgroundImage_(a, 7, b, r);
 901 w.view.backgroundImage_(a, 8, b, r);
 902 w.view.backgroundImage_(a, 9, b, r);
 903 w.view.backgroundImage_(a, 10, b, r);
 904 w.view.backgroundImage_(a, 11, b, r); // find best ratio - move to see
 905 w.view.backgroundImage_(a, 12, b, r);
 906 w.view.backgroundImage_(a, 13, b, r);
 907 w.view.backgroundImage_(a, 14, b, r);
 908 w.view.backgroundImage_(a, 15, b, r);
 909 w.view.backgroundImage_(a, 16, b, r);
 910
 911 // this is safe even if window is still open because Background object holds the SCImage
 912 a.free;
 913
 914 w.close;
 915
 916 (
 917         a = SCImage.new("/Library/Desktop Pictures/Ripples Blue.jpg");
 918         w = SCWindow.new("SCImage background");
 919         l = SC2DSlider.new(w, Rect(10,10,200,200))
 920                 .backgroundImage_( a, 5, 1, Rect(0,0,10,10) );
 921         w.front;
 922         a.free; // safe
 923 )
 924
 925 (
 926         var bounds = Rect(10,10,150,18);
 927         a = SCImage.new("/Library/Desktop Pictures/Ripples Blue.jpg");
 928         w = SCWindow.new("SCImage background");
 929         l = SCSlider.new(w, bounds)
 930                 .backgroundImage_(a);
 931         w.front;
 932         a.free; // safe
 933 )
 934 ::