extra/gpu/textures/textures-docs.factor

   1 ! (c)2009 Joe Groff bsd license
   2 USING: alien byte-arrays classes gpu.buffers help.markup help.syntax
   3 images kernel math ;
   4 IN: gpu.textures
   5
   6 HELP: +X
   7 { $class-description "This " { $link cube-map-axis } " references the positive X face of a " { $link texture-cube-map } "." } ;
   8
   9 HELP: +Y
  10 { $class-description "This " { $link cube-map-axis } " references the positive Y face of a " { $link texture-cube-map } "." } ;
  11
  12 HELP: +Z
  13 { $class-description "This " { $link cube-map-axis } " references the positive Z face of a " { $link texture-cube-map } "." } ;
  14
  15 HELP: -X
  16 { $class-description "This " { $link cube-map-axis } " references the negative X face of a " { $link texture-cube-map } "." } ;
  17
  18 HELP: -Y
  19 { $class-description "This " { $link cube-map-axis } " references the negative Y face of a " { $link texture-cube-map } "." } ;
  20
  21 HELP: -Z
  22 { $class-description "This " { $link cube-map-axis } " references the negative Z face of a " { $link texture-cube-map } "." } ;
  23
  24 HELP: <cube-map-face>
  25 { $values
  26     { "texture" texture-cube-map } { "axis" cube-map-axis }
  27     { "cube-map-face" cube-map-face }
  28 }
  29 { $description "Constructs a new " { $link cube-map-face } " reference." } ;
  30
  31 HELP: <texture-1d-array>
  32 { $values
  33     { "component-order" component-order } { "component-type" component-type } { "parameters" texture-parameters }
  34     { "texture" texture-1d-array }
  35 }
  36 { $description "Creates a new one-dimensional array texture. The new texture starts out with no image data; " { $link allocate-texture } " or " { $link allocate-texture-image } " must be used to allocate memory for the required levels of detail of the texture." }
  37 { $notes "Array textures require OpenGL 3.0 or the " { $snippet "GL_EXT_texture_array" } " extension." } ;
  38
  39 HELP: <texture-1d>
  40 { $values
  41     { "component-order" component-order } { "component-type" component-type } { "parameters" texture-parameters }
  42     { "texture" texture-1d }
  43 }
  44 { $description "Creates a new one-dimensional texture. The new texture starts out with no image data; " { $link allocate-texture } " or " { $link allocate-texture-image } " must be used to allocate memory for the required levels of detail of the texture." } ;
  45
  46 HELP: <texture-2d-array>
  47 { $values
  48     { "component-order" component-order } { "component-type" component-type } { "parameters" texture-parameters }
  49     { "texture" texture-2d-array }
  50 }
  51 { $description "Creates a new two-dimensional array texture. The new texture starts out with no image data; " { $link allocate-texture } " or " { $link allocate-texture-image } " must be used to allocate memory for the required levels of detail of the texture." }
  52 { $notes "Array textures require OpenGL 3.0 or the " { $snippet "GL_EXT_texture_array" } " extension." } ;
  53
  54 HELP: <texture-2d>
  55 { $values
  56     { "component-order" component-order } { "component-type" component-type } { "parameters" texture-parameters }
  57     { "texture" texture-2d }
  58 }
  59 { $description "Creates a new two-dimensional texture. The new texture starts out with no image data; " { $link allocate-texture } " or " { $link allocate-texture-image } " must be used to allocate memory for the required levels of detail of the texture." } ;
  60
  61 HELP: <texture-3d>
  62 { $values
  63     { "component-order" component-order } { "component-type" component-type } { "parameters" texture-parameters }
  64     { "texture" texture-3d }
  65 }
  66 { $description "Creates a new three-dimensional texture. The new texture starts out with no image data; " { $link allocate-texture } " or " { $link allocate-texture-image } " must be used to allocate memory for the required levels of detail of the texture." } ;
  67
  68 HELP: <texture-cube-map>
  69 { $values
  70     { "component-order" component-order } { "component-type" component-type } { "parameters" texture-parameters }
  71     { "texture" texture-cube-map }
  72 }
  73 { $description "Creates a new cube map texture. The new texture starts out with no image data; " { $link allocate-texture } " or " { $link allocate-texture-image } " must be used to allocate memory for the required levels of detail of each " { $link cube-map-face } " of the new texture." } ;
  74
  75 HELP: <texture-data>
  76 { $values
  77     { "ptr" gpu-data-ptr } { "component-order" component-order } { "component-type" component-type }
  78     { "texture-data" texture-data }
  79 }
  80 { $description "Constructs a new " { $link texture-data } " tuple." }
  81 { $notes "Using a " { $link buffer-ptr } " as the " { $snippet "ptr" } " of a " { $snippet "texture-data" } " object requires OpenGL 2.1 or later or the " { $snippet "GL_ARB_pixel_buffer_object" } " extension." } ;
  82
  83 HELP: <texture-rectangle>
  84 { $values
  85     { "component-order" component-order } { "component-type" component-type } { "parameters" texture-parameters }
  86     { "texture" texture-rectangle }
  87 }
  88 { $description "Creates a new rectangle texture. The new texture starts out with no image data; " { $link allocate-texture } " or " { $link allocate-texture-image } " must be used to allocate memory for the texture." }
  89 { $notes "Rectangle textures require OpenGL 3.1 or the " { $snippet "GL_ARB_texture_rectangle" } " extension." } ;
  90
  91 HELP: allocate-texture
  92 { $values
  93     { "tdt" texture-data-target } { "level" integer } { "dim" "an " { $link integer } " or sequence of " { $link integer } "s" } { "data" { $maybe texture-data } }
  94 }
  95 { $description "Allocates a new block of GPU memory for the " { $snippet "level" } "th level of detail of a " { $link texture-data-target } ". If " { $snippet "data" } " is not " { $link f } ", the new data is initialized from the given " { $link texture-data } " object; otherwise, the new image is left uninitialized." }
  96 { $notes "Using a " { $link buffer-ptr } " as the " { $snippet "ptr" } " of a " { $snippet "texture-data" } " object requires OpenGL 2.1 or later or the " { $snippet "GL_ARB_pixel_buffer_object" } " extension." } ;
  97
  98 HELP: allocate-texture-image
  99 { $values
 100     { "tdt" texture-data-target } { "level" integer } { "image" image }
 101 }
 102 { $description "Allocates a new block of GPU memory for the " { $snippet "level" } "th level of detail of a " { $link texture-data-target } " and initializes it with the contents of an " { $link image } "." } ;
 103
 104 { allocate-texture allocate-texture-image } related-words
 105
 106 HELP: clamp-texcoord-to-border
 107 { $class-description "This " { $link texture-wrap } " value clamps texture coordinates to a texture's border." } ;
 108
 109 HELP: clamp-texcoord-to-edge
 110 { $class-description "This " { $link texture-wrap } " value clamps texture coordinates to a texture image's edge." } ;
 111
 112 HELP: cube-map-axis
 113 { $class-description "Objects of this class are stored in the " { $snippet "axis" } " slot of a " { $link cube-map-face } " to choose the referenced face: " { $link +X } ", "  { $link +Y } ", " { $link +Z } ", " { $link -X } ", " { $link -Y } ", or " { $link -Z } "."
 114 } ;
 115
 116 HELP: cube-map-face
 117 { $class-description "A " { $snippet "cube-map-face" } " tuple references a single face of a " { $link texture-cube-map } " object for use with " { $link allocate-texture } ", " { $link update-texture } ", or " { $link read-texture } "."
 118 { $list
 119 { "The " { $snippet "texture" } " slot indicates the cube map texture being referenced." }
 120 { "The " { $snippet "axis" } " slot indicates which face to reference: " { $link +X } ", "  { $link +Y } ", " { $link +Z } ", " { $link -X } ", " { $link -Y } ", or " { $link -Z } "." }
 121 } } ;
 122
 123 HELP: filter-linear
 124 { $class-description "This " { $link texture-filter } " value selects linear filtering between pixel samples." } ;
 125
 126 HELP: filter-nearest
 127 { $class-description "This " { $link texture-filter } " value selects nearest-neighbor sampling." } ;
 128
 129 HELP: generate-mipmaps
 130 { $values
 131     { "texture" texture }
 132 }
 133 { $description "Replaces the image data for all levels of detail of " { $snippet "texture" } " below the highest level with images automatically generated from the highest level of detail image." }
 134 { $notes "This word requires OpenGL 3.0 or one of the " { $snippet "GL_EXT_framebuffer_object" } " or " { $snippet "GL_ARB_framebuffer_object" } " extensions." } ;
 135
 136 HELP: image>texture-data
 137 { $values
 138     { "image" image }
 139     { "dim" "a sequence of " { $link integer } "s" } { "texture-data" texture-data }
 140 }
 141 { $description "Constructs a " { $link texture-data } " tuple referencing the pixel data from an " { $link image } "." } ;
 142
 143 HELP: read-texture
 144 { $values
 145     { "tdt" texture-data-target } { "level" integer }
 146     { "byte-array" byte-array }
 147 }
 148 { $description "Reads the entire image for the " { $snippet "level" } "th level of detail of a texture into a new " { $link byte-array } ". The format of the data in the byte array is determined by the " { $link component-order } " and " { $link component-type } " of the texture." } ;
 149
 150 HELP: read-texture-image
 151 { $values
 152     { "tdt" texture-data-target } { "level" integer }
 153     { "image" image }
 154 }
 155 { $description "Reads the entire image for the " { $snippet "level" } "th level of detail of a texture into a new " { $link image } ". The format of the image is determined by the " { $link component-order } " and " { $link component-type } " of the texture." } ;
 156
 157 HELP: read-texture-to
 158 { $values
 159     { "tdt" texture-data-target } { "level" integer } { "gpu-data-ptr" gpu-data-ptr }
 160 }
 161 { $description "Reads the entire image for the " { $snippet "level" } "th level of detail of a texture into the CPU or GPU memory referenced by " { $link gpu-data-ptr } ". The format of the data in the byte array is determined by the " { $link component-order } " and " { $link component-type } " of the texture." }
 162 { $notes "Reading texture data into a GPU " { $snippet "buffer-ptr" } " requires OpenGL 2.1 or later or the " { $snippet "GL_ARB_pixel_buffer_object" } " extension." } ;
 163
 164 { read-texture read-texture-image read-texture-to } related-words
 165
 166 HELP: repeat-texcoord
 167 { $class-description "This " { $link texture-wrap } " value causes the texture image to be repeated through texture coordinate space." } ;
 168
 169 HELP: repeat-texcoord-mirrored
 170 { $class-description "This " { $link texture-wrap } " value causes the texture image to be repeated through texture coordinate space, mirroring the image on every repetition." } ;
 171
 172 HELP: set-texture-parameters
 173 { $values
 174     { "texture" texture } { "parameters" texture-parameters }
 175 }
 176 { $description "Changes the " { $link texture-parameters } " of a " { $link texture } "." } ;
 177
 178 HELP: texture
 179 { $class-description "Textures are typed, multidimensional arrays of GPU memory used for storing image data, lookup tables, and other kinds of multidimensional data for use with shader programs. They come in different types depending on dimensionality and intended usage:"
 180 { $subsection texture-1d }
 181 { $subsection texture-2d }
 182 { $subsection texture-3d }
 183 { $subsection texture-cube-map }
 184 { $subsection texture-rectangle }
 185 { $subsection texture-1d-array }
 186 { $subsection texture-2d-array }
 187 "Textures are constructed using the corresponding " { $snippet "<constructor word>" } " for their type. The constructor sets the texture's " { $link component-order } ", " { $link component-type } ", and " { $link texture-parameters } ". Once created, memory for a texture can be allocated with " { $link allocate-texture } ", updated with " { $link update-texture } ", or retrieved with " { $link read-texture } "." } ;
 188
 189 HELP: texture-1d
 190 { $class-description "A one-dimensional " { $link texture } " object. Textures of this type are dimensioned by single integers in calls to " { $link allocate-texture } " and " { $link update-texture } "." } ;
 191
 192 { texture-1d <texture-1d> } related-words
 193
 194 HELP: texture-1d-array
 195 { $class-description "A one-dimensional array " { $link texture } " object. Textures of this type are dimensioned by pairs of integers in calls to " { $link allocate-texture } " and " { $link update-texture } ". A 1D array texture is distinct from a 2D texture (" { $link texture-2d } ") in that each row of the texture is independent; texture values are not filtered between rows, and lower levels of detail retain the same height, only losing detail in the width direction." }
 196 { $notes "Array textures require OpenGL 3.0 or the " { $snippet "GL_EXT_texture_array" } " extension." } ;
 197
 198 { texture-1d-array <texture-1d-array> } related-words
 199
 200 HELP: texture-2d
 201 { $class-description "A two-dimensional " { $link texture } " object. Textures of this type are dimensioned by pairs of integers in calls to " { $link allocate-texture } " and " { $link update-texture } "." } ;
 202
 203 { texture-2d <texture-2d> } related-words
 204
 205 HELP: texture-2d-array
 206 { $class-description "A two-dimensional array " { $link texture } " object. Textures of this type are dimensioned by sequences of three integers in calls to " { $link allocate-texture } " and " { $link update-texture } ". A 2D array texture is distinct from a 3D texture (" { $link texture-3d } ") in that each plane of the texture is independent; texture values are not filtered between planes, and lower levels of detail retain the same depth, only losing detail in the width and height directions." }
 207 { $notes "Array textures require OpenGL 3.0 or the " { $snippet "GL_EXT_texture_array" } " extension." } ;
 208
 209 { texture-2d-array <texture-2d-array> } related-words
 210
 211 HELP: texture-3d
 212 { $class-description "A three-dimensional " { $link texture } " object. Textures of this type are dimensioned by sequences of three integers in calls to " { $link allocate-texture } " and " { $link update-texture } "." } ;
 213
 214 { texture-3d <texture-3d> } related-words
 215
 216 HELP: texture-wrap
 217 { $class-description "Values of this class are used in the " { $snippet "wrap" } " slot of a set of " { $link texture-parameters } " to specify how texture coordinates outside the 0.0 to 1.0 range should be mapped onto the texture image."
 218 { $list
 219 { { $link clamp-texcoord-to-edge } " clamps coordinates to the edge of the texture image." }
 220 { { $link clamp-texcoord-to-border } " clamps coordinates to the border of the texture image." }
 221 { { $link repeat-texcoord } " repeats the texture image." }
 222 { { $link repeat-texcoord-mirrored } " repeats the texture image, mirroring it with each repetition." }
 223 } } ;
 224
 225 HELP: texture-cube-map
 226 { $class-description "A cube map " { $link texture } " object. Textures of this type comprise six two-dimensional image sets, which are independently referenced by " { $link cube-map-face } " objects and dimensioned by pairs of integers in calls to " { $link allocate-texture } " and " { $link update-texture } ". When a cube map is sampled in shader code, the three-dimensional texture coordinates are projected onto the unit cube, and the cube face that is hit by the vector is used to select a face of the cube map texture." } ;
 227
 228 { texture-cube-map <texture-cube-map> } related-words
 229
 230 HELP: texture-data
 231 { $class-description { $snippet "texture-data" } " tuples are used to feed image data to " { $link allocate-texture } " and " { $link update-texture } "."
 232 { $list
 233 { "The " { $snippet "ptr" } " slot references either CPU memory (as a " { $link byte-array } " or " { $link alien } ") or a GPU " { $link buffer-ptr } " that contains the image data." }
 234 { "The " { $snippet "component-order" } " and " { $snippet "component-type" } " slots determine the " { $link component-order } " and " { $link component-type } " of the referenced data." }
 235 } }
 236 { $notes "Using a " { $link buffer-ptr } " as the " { $snippet "ptr" } " of a " { $snippet "texture-data" } " object requires OpenGL 2.1 or later or the " { $snippet "GL_ARB_pixel_buffer_object" } " extension." } ;
 237
 238 { texture-data <texture-data> } related-words
 239
 240 HELP: texture-data-size
 241 { $values
 242     { "tdt" texture-data-target } { "level" integer }
 243     { "size" integer }
 244 }
 245 { $description "Returns the size in bytes of the image data allocated for the " { $snippet "level" } "th level of detail of a " { $link texture-data-target } "." } ;
 246
 247 HELP: texture-data-target
 248 { $class-description "Most " { $link texture } " types can have image data assigned to themselves directly by " { $link allocate-texture } " and " { $link update-texture } "; however, " { $link texture-cube-map } " objects comprise six independent image sets, each of which must be referenced separately with a " { $link cube-map-face } " tuple when allocating or updating images. The " { $snippet "texture-data-target" } " class is a union of all " { $link texture } " classes (except " { $snippet "texture-cube-map" } ") and the " { $snippet "cube-map-face" } " class." } ;
 249
 250 HELP: texture-dim
 251 { $values
 252     { "tdt" texture-data-target } { "level" integer }
 253     { "dim" "an " { $link integer } " or sequence of integers" }
 254 }
 255 { $description "Returns the dimensions of the memory allocated for the " { $snippet "level" } "th level of detail of the given " { $link texture-data-target } "." } ;
 256
 257 HELP: texture-filter
 258 { $class-description { $snippet "texture-filter" } " values are used in a " { $link texture-parameters } " tuple to determine how a texture should be sampled between pixels or between levels of detail. " { $link filter-linear } " selects linear filtering, while " { $link filter-nearest } " selects nearest-neighbor sampling." } ;
 259
 260 HELP: texture-parameters
 261 { $class-description "A " { $snippet "texture-parameters" } " tuple is supplied when constructing a " { $link texture } " to control the wrapping, filtering, and level-of-detail handling of the texture. These tuples have the following slots:"
 262 { $list
 263 { "The " { $snippet "wrap" } " slot determines how texture coordinates outside the 0.0 to 1.0 range are mapped to the texture image. The slot either contains a single " { $link texture-wrap } " value, which will apply to all three axes, or a sequence of up to three values, which will apply to the S, T, and R axes, respectively." }
 264 { "The " { $snippet "min-filter" } " and " { $snippet "min-mipmap-filter" } " determine how the texture image is filtered when sampled below its highest level of detail, the former filtering between pixels within a level of detail and the latter filtering between levels of detail. A setting of " { $link filter-linear } " uses linear, bilinear, or trilinear filtering among the sampled pixels, while a setting of " { $link filter-nearest } " uses nearest-neighbor sampling. The " { $snippet "min-mipmap-filter" } " slot may additionally be set to " { $link f } " to disable mipmapping and only sample the highest level of detail." }
 265 { "The " { $snippet "mag-filter" } " analogously determines how the texture image is filtered when sampled above its highest level of detail." }
 266 { "The " { $snippet "min-lod" } " and " { $snippet "max-lod" } " slots contain integer values that will clamp the range of levels of detail that will be sampled from the texture." }
 267 { "The " { $snippet "lod-bias" } " slot contains an integer value that will offset the levels of detail that would normally be sampled from the texture." }
 268 { "The " { $snippet "base-level" } " slot contains an integer value that identifies the highest level of detail for the image, typically zero." }
 269 { "The " { $snippet "max-level" } " slot contains an integer value that identifies the lowest level of detail for the image. This value will automatically be clamped to the maximum of the base-2 logarithms of the dimensions of the highest level of detail image." }
 270 } } ;
 271
 272 { texture-parameters set-texture-parameters } related-words
 273
 274 HELP: texture-rectangle
 275 { $class-description "A two-dimensional rectangle " { $link texture } " object. Textures of this type are dimensioned by pairs of integers in calls to " { $link allocate-texture } " and " { $link update-texture } ". Rectangle textures differ from normal 2D textures (" { $link texture-2d } ") in that texture coordinates map directly to pixel coordinates when they are sampled from shader code, rather than being normalized into the 0.0 to 1.0 range as with other texture types. Also, rectangle textures do not support mipmapping or texture wrapping." }
 276 { $notes "Rectangle textures require OpenGL 3.1 or the " { $snippet "GL_ARB_texture_rectangle" } " extension." } ;
 277
 278 HELP: update-texture
 279 { $values
 280     { "tdt" texture-data-target } { "level" integer } { "loc" "an " { $link integer } " or sequence of integers" } { "dim" "an " { $link integer } " or sequence of integers" } { "data" texture-data }
 281 }
 282 { $description "Updates the linear, rectangular, or cubic subregion of a " { $link texture-data-target } " bounded by " { $snippet "loc" } " and " { $snippet "dim" } " with new image data from a " { $link texture-data } " tuple." }
 283 { $notes "Using a " { $link buffer-ptr } " as the " { $snippet "ptr" } " of a " { $snippet "texture-data" } " object requires OpenGL 2.1 or later or the " { $snippet "GL_ARB_pixel_buffer_object" } " extension." } ;
 284
 285 HELP: update-texture-image
 286 { $values
 287     { "tdt" texture-data-target } { "level" integer } { "loc" "an " { $link integer } " or sequence of integers" } { "image" image }
 288 }
 289 { $description "Updates the linear, rectangular, or cubic subregion of a " { $link texture-data-target } " bounded by " { $snippet "loc" } " and " { $snippet "dim" } " with new image data from an " { $link image } " object." } ;
 290
 291 { update-texture update-texture-image } related-words
 292
 293 ARTICLE: "gpu.textures" "Texture objects"
 294 "The " { $vocab-link "gpu.textures" } " vocabulary provides words for creating, allocating, updating, and reading GPU texture objects."
 295 { $subsection texture }
 296 { $subsection allocate-texture }
 297 { $subsection update-texture }
 298 { $subsection read-texture }
 299 "Words are also provided to interface textures with the " { $vocab-link "images" } " library:"
 300 { $subsection allocate-texture-image }
 301 { $subsection update-texture-image }
 302 { $subsection read-texture-image }
 303 ;
 304
 305 ABOUT: "gpu.textures"