extra/images/viewer/viewer-docs.factor

   1 ! Copyright (C) 2010 Jon Harper.
   2 ! See http://factorcode.org/license.txt for BSD license.
   3 USING: help.markup help.syntax kernel strings io.pathnames images
   4 models opengl.textures classes ui.gadgets ;
   5 IN: images.viewer
   6
   7 HELP: <image-gadget>
   8 { $values
   9     { "object" { $or pathname string image } }
  10     { "gadget" image-gadget }
  11 }
  12 { $description "Creates " { $instance image-gadget } " with the given image. See " { $link set-image } "." } ;
  13 HELP: <image-control>
  14 { $values
  15     { "model" model }
  16     { "gadget" image-control }
  17 }
  18 { $description "Creates " { $instance image-control } " with the given image. See " { $link set-image } "." } ;
  19
  20 HELP: new-image-gadget
  21 { $values
  22     { "class" class }
  23     { "gadget" image-gadget }
  24 }
  25 { $description "Use this if the image is not available when you want to construct the gadget. Don't forget to call "
  26 { $link set-image } " before grafting this gadget. You can also use this constructor if you want to extend image-gadget or image-control."
  27 } ;
  28
  29 HELP: new-image-gadget*
  30 { $values
  31     { "object" { $or pathname string image } } { "class" class }
  32     { "gadget" image-gadget }
  33 }
  34 { $description "Use this constructor when you want to extend image-gadget or image-control." } ;
  35
  36 HELP: set-image
  37 { $values
  38     { "gadget" image-gadget } { "object" { $or pathname string image } }
  39 }
  40 { $description "Sets the image of this gadget. This word loads the image from disk if the input is a string or a pathname."
  41 "If the input is a model, gadget has to be " { $instance image-control } "." } ;
  42
  43 HELP: image-control
  44 { $var-description "This gadget is like " { $instance image-gadget } ", but it's image must be in " { $instance model } ". It's used to display changing images." } ;
  45
  46 HELP: image-gadget
  47 { $var-description "This gadget can render " { $instance image } "." } ;
  48
  49 HELP: image-window
  50 { $values
  51     { "object" { $or pathname string image } }
  52 }
  53 { $description "Opens a new window displaying the image." } ;
  54
  55 HELP: image.
  56 { $values
  57     { "object" { $or pathname string image } }
  58 }
  59 { $description "Displays the image in the listener." } ;
  60 HELP: start-control
  61 { $values
  62     { "gadget" gadget }
  63 }
  64 { $description "Adds a connection between the gadget and it's model." } ;
  65
  66 HELP: stop-control
  67 { $values
  68     { "gadget" gadget }
  69 }
  70 { $description "Removes the connection between the gadget and it's model" } ;
  71 ARTICLE: "images.viewer" "Displaying Images"
  72 "The " { $vocab-link "images.viewer" } " vocabulary uses the " { $vocab-link "opengl.textures" }
  73 " vocabulary to display any instance of " { $link image } "." $nl
  74 "An " { $link image-gadget } " can be used for static images and " { $instance image-control }
  75 " for changing images (for example a video feed). For changing images, the image should be contained in " { $instance model }
  76 ". Change the model value with " { $link set-model } " or mutate the image and call "
  77 { $link notify-connections } " when you want to update the image. To stop refreshing the image, call " { $link stop-control } "."
  78 " To start refreshing again, call " { $link start-control } "."
  79
  80 $nl
  81 "If the " { $link image } " or " { $link model } " containing the image "
  82 "is available when the object is created, use the following words to create the gadget:"
  83 { $subsections <image-gadget> <image-control> }
  84 "The " { $link image } " or " { $link model }
  85 " can also be given after the construction of the object. In this case, use "
  86 { $link new-image-gadget } " and " { $link set-image } "."
  87 " The gadget will automatically detect if the image changes size or format and reallocate a new texture if needed."
  88 " This means images can be set even after the gadget has been grafted. Grafted gadgets without an image will display a blank screen."
  89
  90 { $notes "The image can be set after the gadget has been grafted. However, for " { $instance image-gadget } ", this can "
  91 " be done only once. If your image is changing, you should be using " { $instance image-control } " and " { $instance model } "."
  92 $nl
  93 " Performance will be greatly reduced if you are using images that have more than 512 pixels on one of their"
  94 " axis." }
  95
  96
  97 $nl
  98 "Utility words for displaying images:"
  99 { $subsections
 100 image. image-window }
 101
 102 ;
 103 ABOUT: "images.viewer"