extra/opencl/opencl-docs.factor

   1 ! Copyright (C) 2010 Erik Charlebois.
   2 ! See http://factorcode.org/license.txt for BSD license.
   3 USING: help.markup help.syntax kernel quotations strings opencl.private
   4 math byte-arrays alien ;
   5 IN: opencl
   6
   7 HELP: sampler>cl-addressing-mode
   8 { $values
   9     { "sampler" cl-sampler }
  10     { "addressing-mode" cl-addressing-mode }
  11 }
  12 { $description "Returns the addressing mode of the given sampler." } ;
  13
  14 HELP: cl-barrier
  15 { $description "Insert a synchronization barrier into the current command queue." } ;
  16
  17 HELP: cl-barrier-events
  18 { $values
  19     { "event/events" "a single event or sequence of events" }
  20 }
  21 { $description "Insert a synchronization barrier for the specified events into the current command queue." } ;
  22
  23 HELP: cl-buffer
  24 { $var-description "Tuple wrapper which will release the memory object handle when disposed." } ;
  25
  26 HELP: cl-buffer-ptr
  27 { $var-description "A buffer and offset pair for specifying a starting point for a copy." } ;
  28
  29 HELP: cl-buffer-range
  30 { $var-description "A buffer, offset and size triplet for specifying copy ranges." } ;
  31
  32 HELP: cl-context
  33 { $var-description "Tuple wrapper which will release the context handle when disposed." } ;
  34
  35 HELP: cl-current-context
  36 { $var-description "Symbol for the current cl-context tuple." } ;
  37
  38 HELP: cl-current-device
  39 { $var-description "Symbol for the current cl-device tuple." } ;
  40
  41 HELP: cl-current-queue
  42 { $var-description "Symbol for the current cl-queue tuple." } ;
  43
  44 HELP: cl-device
  45 { $var-description "Tuple wrapper which will release the device handle when disposed." } ;
  46
  47 HELP: cl-event
  48 { $var-description "Tuple wrapper which will release the event handle when disposed." } ;
  49
  50 HELP: cl-event-status
  51 { $values
  52     { "event" cl-event }
  53     { "execution-status" cl-execution-status }
  54 }
  55 { $description "Returns the current execution status of the operation represented by the event." } ;
  56
  57 HELP: cl-event-type
  58 { $values
  59     { "event" cl-event }
  60     { "command-type" cl-execution-status }
  61 }
  62 { $description "Returns the type of operation that created the event." } ;
  63
  64 HELP: sampler>cl-filter-mode
  65 { $values
  66     { "sampler" cl-sampler }
  67     { "filter-mode" cl-filter-mode }
  68 }
  69 { $description "Returns the filter mode of the sampler object." } ;
  70
  71 HELP: cl-finish
  72 { $description "Flush the current command queue and wait till all operations are completed." } ;
  73
  74 HELP: cl-flush
  75 { $description "Flush the current command queue to kick off pending operations." } ;
  76
  77 HELP: cl-kernel
  78 { $var-description "Tuple wrapper which will release the kernel handle when disposed." } ;
  79
  80 HELP: cl-kernel-arity
  81 { $values
  82     { "kernel" cl-kernel }
  83     { "arity" integer }
  84 }
  85 { $description "Returns the number of inputs that this kernel function accepts." } ;
  86
  87 HELP: cl-kernel-local-size
  88 { $values
  89     { "kernel" cl-kernel }
  90     { "size" integer }
  91 }
  92 { $description "Returns the maximum size of a local work group for this kernel." } ;
  93
  94 HELP: cl-kernel-name
  95 { $values
  96     { "kernel" cl-kernel }
  97     { "string" string }
  98 }
  99 { $description "Returns the name of the kernel function." } ;
 100
 101 HELP: cl-marker
 102 { $values
 103
 104     { "event" cl-event }
 105 }
 106 { $description "Inserts a marker into the current command queue." } ;
 107
 108 HELP: cl-normalized-coords?
 109 { $values
 110     { "sampler" cl-sampler }
 111     { "?" boolean }
 112 }
 113 { $description "Returns whether the sampler uses normalized coords or not." } ;
 114
 115 HELP: cl-out-of-order-execution?
 116 { $values
 117     { "command-queue" cl-queue }
 118     { "?" boolean }
 119 }
 120 { $description "Returns whether the given command queue allows out of order execution or not." } ;
 121
 122 HELP: cl-platform
 123 { $var-description "Tuple summarizing the capabilities and devices of an OpenCL platform." } ;
 124
 125 HELP: cl-platforms
 126 { $values
 127
 128     { "platforms" "sequence of cl-platform" }
 129 }
 130 { $description "Returns the platforms available for OpenCL computation on this hardware." } ;
 131
 132 HELP: cl-profile-counters
 133 { $values
 134     { "event" cl-event }
 135     { "queued" integer } { "submitted" integer } { "started" integer } { "finished" integer }
 136 }
 137 { $description "Returns the profiling counters for the operation represented by event." } ;
 138
 139 HELP: cl-profiling?
 140 { $values
 141     { "command-queue" cl-queue }
 142     { "?" boolean }
 143 }
 144 { $description "Returns true if the command queue allows profiling." } ;
 145
 146 HELP: cl-program
 147 { $var-description "Tuple wrapper which will release the program handle when disposed." } ;
 148
 149 HELP: cl-queue
 150 { $var-description "Tuple wrapper which will release the command queue handle when disposed." } ;
 151
 152 HELP: cl-read-buffer
 153 { $values
 154     { "buffer-range" cl-buffer-range }
 155     { "byte-array" byte-array }
 156 }
 157 { $description "Synchronously read a byte-array from the specified buffer location." } ;
 158
 159 HELP: cl-sampler
 160 { $var-description "Tuple wrapper which will release the sampler handle when disposed." } ;
 161
 162 HELP: cl-queue-copy-buffer
 163 { $values
 164     { "src-buffer-ptr" cl-buffer-ptr } { "dst-buffer-ptr" cl-buffer-ptr } { "size" integer } { "dependent-events" "sequence of events" }
 165     { "event" cl-event }
 166 }
 167 { $description "Queue a copy operation from " { $snippet "src-buffer-ptr" } " to " { $snippet "dst-buffer-ptr" } ". Dependent events can be passed to order the operation relative to other operations." } ;
 168
 169 HELP: cl-queue-kernel
 170 { $values
 171     { "kernel" cl-kernel } { "args" "sequence of cl-buffer or byte-array" } { "sizes" "sequence of integers" } { "dependent-events" "sequence of events" }
 172     { "event" cl-event }
 173 }
 174 { $description "Queue a kernel for execution with the given arguments. The " { $snippet "sizes" } " argument specifies input array sizes for each dimension. Dependent events can be passed to order the operation relative to other operations." } ;
 175
 176 HELP: cl-queue-read-buffer
 177 { $values
 178     { "buffer-range" cl-buffer-range } { "alien" alien } { "dependent-events" "a sequence of events" }
 179     { "event" cl-event }
 180 }
 181 { $description "Queue a read operation from " { $snippet "buffer-range" } " to " { $snippet "alien" } ". Dependent events can be passed to order the operation relative to other operations." } ;
 182
 183 HELP: cl-queue-write-buffer
 184 { $values
 185     { "buffer-range" cl-buffer-range } { "alien" alien } { "dependent-events" "a sequence of events" }
 186     { "event" cl-event }
 187 }
 188 { $description "Queue a write operation from " { $snippet "alien" } " to " { $snippet "buffer-range" } ". Dependent events can be passed to order the operation relative to other operations." } ;
 189
 190 HELP: cl-wait
 191 { $values
 192     { "event/events" "a single event or sequence of events" }
 193 }
 194 { $description "Synchronously wait for the events to complete." } ;
 195
 196 HELP: cl-write-buffer
 197 { $values
 198     { "buffer-range" cl-buffer-range } { "byte-array" byte-array }
 199 }
 200 { $description "Synchronously write a byte-array to the specified buffer location." } ;
 201
 202 HELP: <cl-program>
 203 { $values
 204     { "options" string } { "strings" "sequence of source code strings" }
 205     { "program" "compiled cl-program" }
 206 }
 207 { $description "Compile the given source code and return a program object. A " { $link cl-error } " is thrown in the event of a compile error." } ;
 208
 209 HELP: with-cl-state
 210 { $values
 211   { "context/f" { $maybe cl-context } } { "device/f" { $maybe cl-device } } { "queue/f" { $maybe cl-queue } } { "quot" quotation }
 212 }
 213 { $description "Run the specified quotation with the given context, device and command queue. False arguments are not bound." } ;
 214
 215 ARTICLE: "opencl" "OpenCL"
 216 "The " { $vocab-link "opencl" } " vocabulary provides high-level words for using OpenCL."
 217 { $subsections
 218   cl-platforms
 219   <cl-queue>
 220   with-cl-state
 221 }
 222 "Memory Objects:"
 223 { $subsections
 224   <cl-buffer>
 225   cl-queue-copy-buffer
 226   cl-read-buffer
 227   cl-queue-read-buffer
 228   cl-write-buffer
 229   cl-queue-write-buffer
 230 }
 231 "Programs and Kernels:"
 232 { $subsections
 233   <cl-program>
 234   <cl-kernel>
 235 }
 236
 237 "Running and Waiting for Completion:"
 238 { $subsections
 239   cl-queue-kernel
 240   cl-wait
 241   cl-flush
 242   cl-finish
 243 }
 244 ;
 245
 246 ABOUT: "opencl"