extra/images/viewer/viewer-docs.factor

   1 ! Copyright (C) 2010 Jon Harper.
   2 ! See https://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
  61 ARTICLE: "images.viewer" "Displaying Images"
  62 "The " { $vocab-link "images.viewer" } " vocabulary uses the " { $vocab-link "opengl.textures" }
  63 " vocabulary to display any instance of " { $link image } "." $nl
  64 "An " { $link image-gadget } " can be used for static images and " { $instance image-control }
  65 " for changing images (for example a video feed). For changing images, the image should be contained in " { $instance model }
  66 ". Change the model value with " { $link set-model } " or mutate the image and call "
  67 { $link notify-connections } " when you want to update the image."
  68
  69 $nl
  70 "If the " { $link image } " or " { $link model } " containing the image "
  71 "is available when the object is created, use the following words to create the gadget:"
  72 { $subsections <image-gadget> <image-control> }
  73 "The " { $link image } " or " { $link model }
  74 " can also be given after the construction of the object. In this case, use "
  75 { $link new-image-gadget } " and " { $link set-image } "."
  76 " The gadget will automatically detect if the image changes size or format and reallocate a new texture if needed."
  77 " This means images can be set even after the gadget has been grafted. Grafted gadgets without an image will display a blank screen."
  78
  79 { $notes "The image can be set after the gadget has been grafted. However, for " { $instance image-gadget } ", this can "
  80 " be done only once. If your image is changing, you should be using " { $instance image-control } " and " { $instance model } "."
  81 $nl
  82 "Performance will be greatly reduced if you are using images that have more than 512 pixels on one of their"
  83 " axis." }
  84
  85
  86 $nl
  87 "Utility words for displaying images:"
  88 { $subsections
  89 image. image-window }
  90
  91 ;
  92 ABOUT: "images.viewer"