basis/ui/pixel-formats/pixel-formats-docs.factor

   1 USING: destructors help.markup help.syntax kernel math sequences
   2 vocabs vocabs.parser words namespaces ;
   3 IN: ui.pixel-formats
   4
   5 ! break circular dependency
   6 <<
   7     "ui.gadgets.worlds" create-vocab drop
   8     "world" "ui.gadgets.worlds" create-word drop
   9     "ui.gadgets.worlds" vocab-words-assoc use-words
  10 >>
  11
  12 ARTICLE: "ui.pixel-formats-attributes" "Pixel format attributes"
  13 "The following pixel format attributes can be requested and queried of " { $link pixel-format } "s. Binary attributes are represented by the presence of a symbol in an attribute sequence:"
  14 { $subsections
  15     double-buffered
  16     stereo
  17     offscreen
  18     fullscreen
  19     windowed
  20     accelerated
  21     software-rendered
  22     backing-store
  23     multisampled
  24     supersampled
  25     sample-alpha
  26     color-float
  27 }
  28 "Integer attributes are represented by a " { $link tuple } " with a single " { $snippet "value" } "slot:"
  29 { $subsections
  30     color-bits
  31     red-bits
  32     green-bits
  33     blue-bits
  34     alpha-bits
  35     accum-bits
  36     accum-red-bits
  37     accum-green-bits
  38     accum-blue-bits
  39     accum-alpha-bits
  40     depth-bits
  41     stencil-bits
  42     aux-buffers
  43     sample-buffers
  44     samples
  45 }
  46 { $examples
  47 "The following " { $link world } " subclass will request a double-buffered window with minimum 24-bit color and depth buffers, and will throw an error if the requirements aren't met:"
  48 { $code "USING: kernel ui.gadgets.worlds ui.pixel-formats ;
  49 IN: ui.pixel-formats.examples
  50
  51 TUPLE: picky-depth-buffered-world < world ;
  52
  53 M: picky-depth-buffered-world world-pixel-format-attributes
  54     drop {
  55         double-buffered
  56         T{ color-bits { value 24 } }
  57         T{ depth-bits { value 24 } }
  58     } ;
  59
  60 M: picky-depth-buffered-world check-world-pixel-format
  61     nip
  62     [ double-buffered pixel-format-attribute 0 = [ \"Not double buffered!\" throw ] when ]
  63     [ color-bits pixel-format-attribute 24 < [ \"Not enough color bits!\" throw ] when ]
  64     [ depth-bits pixel-format-attribute 24 < [ \"Not enough depth bits!\" throw ] when ]
  65     tri ;" } }
  66 ;
  67
  68 HELP: double-buffered
  69 { $description "Requests a double-buffered pixel format." } ;
  70 HELP: stereo
  71 { $description "Requests a stereoscopic pixel format." } ;
  72
  73 HELP: offscreen
  74 { $description "Requests a pixel format suitable for offscreen rendering." } ;
  75 HELP: fullscreen
  76 { $description "Requests a pixel format suitable for fullscreen rendering." }
  77 { $notes "On some window systems this is not distinct from " { $link windowed } "." } ;
  78 HELP: windowed
  79 { $description "Requests a pixel format suitable for rendering to a window." } ;
  80
  81 { offscreen fullscreen windowed } related-words
  82
  83 HELP: accelerated
  84 { $description "Requests a pixel format supported by GPU hardware acceleration." } ;
  85 HELP: software-rendered
  86 { $description "Requests a pixel format only supported by the window system's default software renderer." } ;
  87
  88 { accelerated software-rendered } related-words
  89
  90 HELP: backing-store
  91 { $description "Used with " { $link double-buffered } " to request a double-buffered pixel format where the back buffer contents are preserved and copied to the front when buffers are swapped." } ;
  92
  93 { double-buffered backing-store } related-words
  94
  95 HELP: multisampled
  96 { $description "Requests a pixel format with multisampled antialiasing enabled. The " { $link sample-buffers } " and " { $link samples } " attributes must also be provided to specify the level of multisampling." }
  97 { $notes "On some window systems this is not distinct from " { $link supersampled } "." } ;
  98
  99 HELP: supersampled
 100 { $description "Requests a pixel format with supersampled antialiasing enabled. The " { $link sample-buffers } " and " { $link samples } " attributes must also be provided to specify the level of supersampling." }
 101 { $notes "On some window systems this is not distinct from " { $link multisampled } "." } ;
 102
 103 HELP: sample-alpha
 104 { $description "Used with " { $link multisampled } " or " { $link supersampled } " to request more accurate multisampling of alpha values." } ;
 105
 106 HELP: color-float
 107 { $description "Requests a pixel format where the color buffer is stored in floating-point format." } ;
 108
 109 HELP: color-bits
 110 { $class-description "Requests a pixel format with a color buffer of at least " { $snippet "value" } " bits per pixel." } ;
 111 HELP: red-bits
 112 { $class-description "Requests a pixel format with a color buffer with at least " { $snippet "value" } " red bits per pixel." } ;
 113 HELP: green-bits
 114 { $class-description "Requests a pixel format with a color buffer with at least " { $snippet "value" } " green bits per pixel." } ;
 115 HELP: blue-bits
 116 { $class-description "Requests a pixel format with a color buffer with at least " { $snippet "value" } " blue bits per pixel." } ;
 117 HELP: alpha-bits
 118 { $class-description "Requests a pixel format with a color buffer with at least " { $snippet "value" } " alpha bits per pixel." } ;
 119
 120 { color-float color-bits red-bits green-bits blue-bits alpha-bits } related-words
 121
 122 HELP: accum-bits
 123 { $class-description "Requests a pixel format with an accumulation buffer of at least " { $snippet "value" } " bits per pixel." } ;
 124 HELP: accum-red-bits
 125 { $class-description "Requests a pixel format with an accumulation buffer with at least " { $snippet "value" } " red bits per pixel." } ;
 126 HELP: accum-green-bits
 127 { $class-description "Requests a pixel format with an accumulation buffer with at least " { $snippet "value" } " green bits per pixel." } ;
 128 HELP: accum-blue-bits
 129 { $class-description "Requests a pixel format with an accumulation buffer with at least " { $snippet "value" } " blue bits per pixel." } ;
 130 HELP: accum-alpha-bits
 131 { $class-description "Requests a pixel format with an accumulation buffer with at least " { $snippet "value" } " alpha bits per pixel." } ;
 132
 133 { accum-bits accum-red-bits accum-green-bits accum-blue-bits accum-alpha-bits } related-words
 134
 135 HELP: depth-bits
 136 { $class-description "Requests a pixel format with a depth buffer of at least " { $snippet "value" } " bits per pixel." } ;
 137
 138 HELP: stencil-bits
 139 { $class-description "Requests a pixel format with a stencil buffer of at least " { $snippet "value" } " bits per pixel." } ;
 140
 141 HELP: aux-buffers
 142 { $class-description "Requests a pixel format with at least " { $snippet "value" } " auxiliary buffers." } ;
 143
 144 HELP: sample-buffers
 145 { $class-description "Used with " { $link multisampled } " or " { $link supersampled } " to request a pixel format with at least " { $snippet "value" } " sampling buffers." } ;
 146
 147 HELP: samples
 148 { $class-description "Used with " { $link multisampled } " or " { $link supersampled } " to request at least " { $snippet "value" } " samples per pixel." } ;
 149
 150 { multisampled supersampled sample-alpha sample-buffers samples } related-words
 151
 152 HELP: world-pixel-format-attributes
 153 { $values { "world" world } { "attributes" sequence } }
 154 { $description "Returns the set of " { $link "ui.pixel-formats-attributes" } " that " { $snippet "world" } " requests when grafted. This generic can be overridden by subclasses of " { $snippet "world" } "." }
 155 { $notes "The pixel format provided by the window system will not necessarily exactly match the requested attributes. To verify required pixel format attributes, override " { $link check-world-pixel-format } "." } ;
 156
 157 HELP: check-world-pixel-format
 158 { $values { "world" world } { "pixel-format" pixel-format } }
 159 { $description "Verifies that " { $snippet "pixel-format" } " fulfills the requirements of " { $snippet "world" } ". The default method does nothing. Subclasses can override this generic to perform their own checks on the pixel format." } ;
 160
 161 HELP: pixel-format
 162 { $class-description "The type of pixel format objects. The tuple slot contents should be considered opaque by user code. To check the value of a pixel format's attributes, use the " { $link pixel-format-attribute } " word. Pixel format objects must be freed using the " { $link dispose } " word when they are no longer needed." } ;
 163
 164 HELP: <pixel-format>
 165 { $values { "world" world } { "attributes" sequence } { "pixel-format" pixel-format } }
 166 { $description "Requests a pixel format suitable for " { $snippet "world" } " with a set of " { $link "ui.pixel-formats-attributes" } ". If no pixel format can be found that satisfies the given attributes, an " { $link invalid-pixel-format-attributes } " error is thrown. Pixel format attributes not supported by the window system are ignored. The returned " { $snippet "pixel-format" } " must be released using the " { $link dispose } " word when it is no longer needed." }
 167 { $notes "Pixel formats don't normally need to be directly allocated by user code. If you need to control the pixel format requested by a window, subclass " { $snippet "world" } " and override the " { $link world-pixel-format-attributes } " and " { $link check-world-pixel-format } " words."
 168 $nl
 169 "The returned pixel format does not necessarily exactly match the requested attributes; the window system will try to find the format that best matches the given attributes. Use " { $link pixel-format-attribute } " to check the actual values of the attributes on the returned pixel format." }
 170 ;
 171
 172 HELP: pixel-format-attribute
 173 { $values { "pixel-format" pixel-format } { "attribute-name" "one of the " { $link "ui.pixel-formats-attributes" } } { "value" object } }
 174 { $description "Returns the value of the requested " { $snippet "attribute-name" } " in " { $snippet "pixel-format" } ". If " { "attribute-name" } " is unsupported by the window system, " { $link f } " is returned." } ;
 175
 176 HELP: invalid-pixel-format-attributes
 177 { $values { "world" world } { "attributes" sequence } }
 178 { $class-description "Thrown by " { $link <pixel-format> } " when the window system is unable to find a pixel format for " { $snippet "world" } " that satisfies the requested " { $snippet "attributes" } "." } ;
 179
 180 { world-pixel-format-attributes check-world-pixel-format pixel-format <pixel-format> pixel-format-attribute }
 181 related-words
 182
 183 ARTICLE: "ui.pixel-formats" "Pixel formats"
 184 "The UI allows you to control the window system's OpenGL interface with a cross-platform set of pixel format specifiers:"
 185 { $subsections "ui.pixel-formats-attributes" }
 186
 187 "Pixel formats can be requested using these attributes:"
 188 { $subsections
 189     pixel-format
 190     <pixel-format>
 191     pixel-format-attribute
 192 }
 193
 194 "If a request for a set of pixel format attributes cannot be satisfied, an error is thrown:"
 195 { $subsections invalid-pixel-format-attributes }
 196
 197 "Pixel formats are requested as part of opening a window for a " { $link world } ". These generics can be overridden on " { $snippet "world" } " subclasses to control pixel format selection:"
 198 { $subsections
 199     world-pixel-format-attributes
 200     check-world-pixel-format
 201 }
 202 ;
 203
 204 ABOUT: "ui.pixel-formats"