1 USING: destructors help.markup help.syntax kernel math sequences
2 vocabs vocabs.parser words namespaces ;
5 ! break circular dependency
7 "ui.gadgets.worlds" create-vocab drop
8 "world" "ui.gadgets.worlds" create drop
9 "ui.gadgets.worlds" vocab-words use-words
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 { $subsection double-buffered }
15 { $subsection stereo }
16 { $subsection offscreen }
17 { $subsection fullscreen }
18 { $subsection windowed }
19 { $subsection accelerated }
20 { $subsection software-rendered }
21 { $subsection backing-store }
22 { $subsection multisampled }
23 { $subsection supersampled }
24 { $subsection sample-alpha }
25 { $subsection color-float }
26 "Integer attributes are represented by a " { $link tuple } " with a single " { $snippet "value" } "slot:"
27 { $subsection color-bits }
28 { $subsection red-bits }
29 { $subsection green-bits }
30 { $subsection blue-bits }
31 { $subsection alpha-bits }
32 { $subsection accum-bits }
33 { $subsection accum-red-bits }
34 { $subsection accum-green-bits }
35 { $subsection accum-blue-bits }
36 { $subsection accum-alpha-bits }
37 { $subsection depth-bits }
38 { $subsection stencil-bits }
39 { $subsection aux-buffers }
40 { $subsection sample-buffers }
41 { $subsection samples }
43 "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:"
45 USING: kernel ui.worlds ui.pixel-formats ;
46 IN: ui.pixel-formats.examples
48 TUPLE: picky-depth-buffered-world < world ;
50 M: picky-depth-buffered-world world-pixel-format-attributes
53 T{ color-bits { value 24 } }
54 T{ depth-bits { value 24 } }
57 M: picky-depth-buffered-world check-world-pixel-format
59 [ double-buffered pixel-format-attribute 0 = [ "Not double buffered!" throw ] when ]
60 [ color-bits pixel-format-attribute 24 < [ "Not enough color bits!" throw ] when ]
61 [ depth-bits pixel-format-attribute 24 < [ "Not enough depth bits!" throw ] when ]
67 { $class-description "Requests a double-buffered pixel format." } ;
69 { $class-description "Requests a stereoscopic pixel format." } ;
72 { $class-description "Requests a pixel format suitable for offscreen rendering." } ;
74 { $class-description "Requests a pixel format suitable for fullscreen rendering." }
75 { $notes "On some window systems this is not distinct from " { $link windowed } "." } ;
77 { $class-description "Requests a pixel format suitable for rendering to a window." } ;
79 { offscreen fullscreen windowed } related-words
82 { $class-description "Requests a pixel format supported by GPU hardware acceleration." } ;
83 HELP: software-rendered
84 { $class-description "Requests a pixel format only supported by the window system's default software renderer." } ;
86 { accelerated software-rendered } related-words
89 { $class-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." } ;
91 { double-buffered backing-store } related-words
94 { $class-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." }
95 { $notes "On some window systems this is not distinct from " { $link supersampled } "." } ;
98 { $class-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." }
99 { $notes "On some window systems this is not distinct from " { $link multisampled } "." } ;
102 { $class-description "Used with " { $link multisampled } " or " { $link supersampled } " to request more accurate multisampling of alpha values." } ;
105 { $class-description "Requests a pixel format where the color buffer is stored in floating-point format." } ;
108 { $class-description "Requests a pixel format with a color buffer of at least " { $snippet "value" } " bits per pixel." } ;
110 { $class-description "Requests a pixel format with a color buffer with at least " { $snippet "value" } " red bits per pixel." } ;
112 { $class-description "Requests a pixel format with a color buffer with at least " { $snippet "value" } " green bits per pixel." } ;
114 { $class-description "Requests a pixel format with a color buffer with at least " { $snippet "value" } " blue bits per pixel." } ;
116 { $class-description "Requests a pixel format with a color buffer with at least " { $snippet "value" } " alpha bits per pixel." } ;
118 { color-float color-bits red-bits green-bits blue-bits alpha-bits } related-words
121 { $class-description "Requests a pixel format with an accumulation buffer of at least " { $snippet "value" } " bits per pixel." } ;
123 { $class-description "Requests a pixel format with an accumulation buffer with at least " { $snippet "value" } " red bits per pixel." } ;
124 HELP: accum-green-bits
125 { $class-description "Requests a pixel format with an accumulation buffer with at least " { $snippet "value" } " green bits per pixel." } ;
126 HELP: accum-blue-bits
127 { $class-description "Requests a pixel format with an accumulation buffer with at least " { $snippet "value" } " blue bits per pixel." } ;
128 HELP: accum-alpha-bits
129 { $class-description "Requests a pixel format with an accumulation buffer with at least " { $snippet "value" } " alpha bits per pixel." } ;
131 { accum-bits accum-red-bits accum-green-bits accum-blue-bits accum-alpha-bits } related-words
134 { $class-description "Requests a pixel format with a depth buffer of at least " { $snippet "value" } " bits per pixel." } ;
137 { $class-description "Requests a pixel format with a stencil buffer of at least " { $snippet "value" } " bits per pixel." } ;
140 { $class-description "Requests a pixel format with at least " { $snippet "value" } " auxiliary buffers." } ;
143 { $class-description "Used with " { $link multisampled } " or " { $link supersampled } " to request a pixel format with at least " { $snippet "value" } " sampling buffers." } ;
146 { $class-description "Used with " { $link multisampled } " or " { $link supersampled } " to request at least " { $snippet "value" } " samples per pixel." } ;
148 { multisampled supersampled sample-alpha sample-buffers samples } related-words
150 HELP: world-pixel-format-attributes
151 { $values { "world" world } { "attributes" sequence } }
152 { $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" } "." }
153 { $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 } "." } ;
155 HELP: check-world-pixel-format
156 { $values { "world" world } { "pixel-format" pixel-format } }
157 { $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 { $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 { $values { "world" world } { "attributes" sequence } { "pixel-format" pixel-format } }
164 { $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." }
165 { $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."
167 "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 HELP: pixel-format-attribute
171 { $values { "pixel-format" pixel-format } { "attribute-name" "one of the " { $link "ui.pixel-formats-attributes" } } { "value" object } }
172 { $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." } ;
174 HELP: invalid-pixel-format-attributes
175 { $values { "world" world } { "attributes" sequence } }
176 { $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" } "." } ;
178 { world-pixel-format-attributes check-world-pixel-format pixel-format <pixel-format> pixel-format-attribute }
181 ARTICLE: "ui.pixel-formats" "Pixel formats"
182 "The UI allows you to control the window system's OpenGL interface with a cross-platform set of pixel format specifiers:"
183 { $subsection "ui.pixel-formats-attributes" }
185 "Pixel formats can be requested using these attributes:"
186 { $subsection pixel-format }
187 { $subsection <pixel-format> }
188 { $subsection pixel-format-attribute }
190 "If a request for a set of pixel format attributes cannot be satisfied, an error is thrown:"
191 { $subsection invalid-pixel-format-attributes }
193 "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:"
194 { $subsection world-pixel-format-attributes }
195 { $subsection check-world-pixel-format }
198 ABOUT: "ui.pixel-formats"