From 25ff0b3b1f918aa8185c0f5df1cdfb8ac91ddfc6 Mon Sep 17 00:00:00 2001 From: Joe Groff Date: Sat, 19 Jul 2008 19:10:30 -0700 Subject: [PATCH] game-input documentation. bugfixes in game-input.scancodes and game-input.backend.iokit --- extra/game-input/authors.txt | 1 + extra/game-input/backend/authors.txt | 1 + extra/game-input/backend/iokit/authors.txt | 1 + extra/game-input/backend/iokit/iokit.factor | 22 ++-- extra/game-input/backend/iokit/summary.txt | 1 + extra/game-input/backend/iokit/tags.txt | 4 + extra/game-input/backend/summary.txt | 1 + extra/game-input/backend/tags.txt | 3 + extra/game-input/game-input-docs.factor | 118 ++++++++++++++++++ extra/game-input/scancodes/scancodes.factor | 8 +- extra/game-input/summary.txt | 1 + extra/game-input/tags.txt | 3 + extra/math/blas/matrices/matrices-docs.factor | 11 +- 13 files changed, 162 insertions(+), 13 deletions(-) create mode 100644 extra/game-input/authors.txt create mode 100644 extra/game-input/backend/authors.txt create mode 100644 extra/game-input/backend/iokit/authors.txt create mode 100644 extra/game-input/backend/iokit/summary.txt create mode 100644 extra/game-input/backend/iokit/tags.txt create mode 100644 extra/game-input/backend/summary.txt create mode 100644 extra/game-input/backend/tags.txt create mode 100644 extra/game-input/game-input-docs.factor create mode 100644 extra/game-input/summary.txt create mode 100644 extra/game-input/tags.txt diff --git a/extra/game-input/authors.txt b/extra/game-input/authors.txt new file mode 100644 index 0000000000..f13c9c1e77 --- /dev/null +++ b/extra/game-input/authors.txt @@ -0,0 +1 @@ +Joe Groff diff --git a/extra/game-input/backend/authors.txt b/extra/game-input/backend/authors.txt new file mode 100644 index 0000000000..f13c9c1e77 --- /dev/null +++ b/extra/game-input/backend/authors.txt @@ -0,0 +1 @@ +Joe Groff diff --git a/extra/game-input/backend/iokit/authors.txt b/extra/game-input/backend/iokit/authors.txt new file mode 100644 index 0000000000..f13c9c1e77 --- /dev/null +++ b/extra/game-input/backend/iokit/authors.txt @@ -0,0 +1 @@ +Joe Groff diff --git a/extra/game-input/backend/iokit/iokit.factor b/extra/game-input/backend/iokit/iokit.factor index 10e3220b3d..600ab8f170 100644 --- a/extra/game-input/backend/iokit/iokit.factor +++ b/extra/game-input/backend/iokit/iokit.factor @@ -128,7 +128,6 @@ SINGLETON: iokit-game-input-backend : button-value ( value -- f/(0,1] ) IOHIDValueGetIntegerValue dup zero? [ drop f ] when ; -! XXX calibration : axis-value ( value -- [-1,1] ) kIOHIDValueScaleTypeCalibrated IOHIDValueGetScaledValue ; : pov-value ( value -- pov-direction ) @@ -220,6 +219,7 @@ SYMBOLS: +hid-manager+ +keyboard-state+ +controller-states+ ; 256 f +keyboard-state+ set-global ; M: iokit-game-input-backend open-game-input + +hid-manager+ get-global [ "game-input already open" throw ] when hid-manager-matching-game-devices { [ initialize-variables ] [ device-matched-callback f IOHIDManagerRegisterDeviceMatchingCallback ] @@ -235,13 +235,19 @@ M: iokit-game-input-backend open-game-input ! XXX while game-input is open, we need to reset-game-input and open-game-input as a ! boot image hook M: iokit-game-input-backend close-game-input - +hid-manager+ global [ - [ 0 IOHIDManagerClose drop ] - [ CFRelease ] bi - f - ] change-at - f +keyboard-state+ set-global - f +controller-states+ set-global ; + +hid-manager+ get-global [ + +hid-manager+ global [ + [ + CFRunLoopGetMain CFRunLoopDefaultMode + IOHIDManagerUnscheduleFromRunLoop + ] + [ 0 IOHIDManagerClose drop ] + [ CFRelease ] tri + f + ] change-at + f +keyboard-state+ set-global + f +controller-states+ set-global + ] when ; M: iokit-game-input-backend get-controllers ( -- sequence ) +controller-states+ get keys [ controller boa ] map ; diff --git a/extra/game-input/backend/iokit/summary.txt b/extra/game-input/backend/iokit/summary.txt new file mode 100644 index 0000000000..8fc5d827d0 --- /dev/null +++ b/extra/game-input/backend/iokit/summary.txt @@ -0,0 +1 @@ +IOKit HID Manager backend for game-input diff --git a/extra/game-input/backend/iokit/tags.txt b/extra/game-input/backend/iokit/tags.txt new file mode 100644 index 0000000000..b3bc4f873b --- /dev/null +++ b/extra/game-input/backend/iokit/tags.txt @@ -0,0 +1,4 @@ +gamepads +joysticks +mac +input diff --git a/extra/game-input/backend/summary.txt b/extra/game-input/backend/summary.txt new file mode 100644 index 0000000000..6a77f8e1e0 --- /dev/null +++ b/extra/game-input/backend/summary.txt @@ -0,0 +1 @@ +Platform-specific backends for game-input diff --git a/extra/game-input/backend/tags.txt b/extra/game-input/backend/tags.txt new file mode 100644 index 0000000000..48ad1f6141 --- /dev/null +++ b/extra/game-input/backend/tags.txt @@ -0,0 +1,3 @@ +gamepads +joysticks +input diff --git a/extra/game-input/game-input-docs.factor b/extra/game-input/game-input-docs.factor new file mode 100644 index 0000000000..6dab99e948 --- /dev/null +++ b/extra/game-input/game-input-docs.factor @@ -0,0 +1,118 @@ +USING: help.markup help.syntax kernel ui.gestures quotations +sequences strings math ; +IN: game-input + +ARTICLE: "game-input" "Game controller input" +"The " { $vocab-link "game-input" } " vocabulary provides cross-platform access to game controller devices such as joysticks and gamepads. It also provides an interface to for polling raw keyboard input." $nl +"The game input interface must be initialized before being used:" +{ $subsection open-game-input } +{ $subsection close-game-input } +{ $subsection with-game-input } +"Once the game input interface is open, connected controller devices can be enumerated:" +{ $subsection get-controllers } +"These " { $link controller } " objects can be queried of their identity:" +{ $subsection manufacturer } +{ $subsection product } +{ $subsection vendor-id } +{ $subsection product-id } +{ $subsection location-id } +"A hook is provided for invoking the system calibration tool:" +{ $subsection calibrate-controller } +"The current state of a controller or the keyboard can be read:" +{ $subsection read-controller } +{ $subsection read-keyboard } +{ $subsection controller-state } +{ $subsection keyboard-state } ; + +HELP: open-game-input +{ $description "Initializes the game input interface. An exception will be thrown if the initialization fails." } ; + +HELP: close-game-input +{ $description "Closes the game input interface, releasing any allocated resources." } ; + +HELP: with-game-input +{ $values { "quot" quotation } } +{ $description "Initializes the game input interface for the dynamic extent of " { $snippet "quotation" } "." } ; + +{ open-game-input close-game-input with-game-input } related-words + +HELP: get-controllers +{ $values { "sequence" "A " { $link sequence } " of " { $link controller } "s" } } +{ $description "Returns a " { $link sequence } " of " { $link controller } " objects representing the currently connected game controllers." } ; + +HELP: controller +{ $class-description "Objects of this class represent game controller devices such as joysticks and gamepads. They should be treated as opaque by client code." } ; + +HELP: manufacturer +{ $values { "controller" controller } { "string" string } } +{ $description "Returns a human-readable string describing the manufacturer of the game controller device represented by " { $snippet "controller" } "." } ; + +HELP: product +{ $values { "controller" controller } { "string" string } } +{ $description "Returns a human-readable string describing the game controller device represented by " { $snippet "controller" } "." } ; + +HELP: vendor-id +{ $values { "controller" controller } { "integer" integer } } +{ $description "Returns an identifier uniquely representing the manufacturer of the game controller device represented by " { $snippet "controller" } "." } ; + +HELP: product-id +{ $values { "controller" controller } { "integer" integer } } +{ $description "Returns an identifier uniquely representing the kind of game controller device represented by " { $snippet "controller" } "." } ; + +HELP: location-id +{ $values { "controller" controller } { "integer" integer } } +{ $description "Returns an identifier uniquely representing the game controller device represented by " { $snippet "controller" } "'s location in the system." } ; + +{ manufacturer product-id vendor-id product-id location-id } related-words + +HELP: calibrate-controller +{ $values { "controller" controller } } +{ $description "Invokes the operating system's calibration tool for " { $snippet "controller" } ". If the operating system does not have a calibration tool, does nothing." } ; + +HELP: read-controller +{ $values { "controller" controller } { "controller-state" controller-state } } +{ $description "Reads the current state of " { $snippet "controller" } ". See the documentation for the " { $link controller-state } " class for details of the returned value's format." } ; + +{ controller-state controller read-controller } related-words + +HELP: read-keyboard +{ $values { "keyboard-state" keyboard-state } } +{ $description "Reads the current raw state of the keyboard. See the documentation for the " { $link keyboard-state } " class for details on the returned value's format." } +{ $warning "The keyboard state returned by this word is unprocessed by any keymaps, key repeat settings, or other operating environment postprocessing. Because of this, " { $snippet "read-keyboard" } " should not be used for text entry purposes. The Factor UI's standard gesture mechanism should be used in cases where the logical meaning of keypresses is necessary; see " { $link "keyboard-gestures" } "." } ; + +HELP: controller-state +{ $class-description "The " { $link read-controller } " word returns objects of this class. " { $snippet "controller-state" } " objects have the following slots:" +{ $list + { { $snippet "x" } " contains the position of the device's X axis." } + { { $snippet "y" } " contains the position of the device's Y axis." } + { { $snippet "z" } " contains the position of the device's Z axis, if any." } + { { $snippet "rx" } " contains the rotational position of the device's X axis, if available." } + { { $snippet "ry" } " contains the rotational position of the device's Y axis, if available." } + { { $snippet "rz" } " contains the rotational position of the device's Z axis, if available." } + { { $snippet "slider" } " contains the position of the device's throttle slider, if any." } + { { $snippet "pov" } " contains the state of the device's POV hat, if any." } + { { $snippet "buttons" } " contains a sequence of values indicating the state of every button on the device." } +} +"The values are formatted as follows:" +{ $list + { "For the axis slots (" { $snippet "x" } ", " { $snippet "y" } ", " { $snippet "z" } ", " { $snippet "rx" } ", " { $snippet "ry" } ", " { $snippet "rz" } "), a " { $link float } " value between -1.0 and 1.0 is returned." } + { "For the " { $snippet "slider" } " slot, a value between 0.0 and 1.0 is returned." } + { "For the " { $snippet "pov" } " slot, one of the following symbols is returned:" { $list + { { $link pov-neutral } } + { { $link pov-up } } + { { $link pov-up-right } } + { { $link pov-right } } + { { $link pov-down-right } } + { { $link pov-down } } + { { $link pov-down-left } } + { { $link pov-left } } + { { $link pov-up-left } } + } } + { "For each element of the " { $snippet "buttons" } " array, " { $link f } " indicates that the corresponding button is released. If the button is pressed, a value between 0.0 and 1.0 is returned indicating the pressure on the button (or simply 1.0 if the device's buttons are on/off only)." } + { "A value of " { $link f } " in any slot (besides the elements of " { $snippet "buttons" } ") indicates that the corresponding axis is not present on the device." } } } ; + +HELP: keyboard-state +{ $class-description "The " { $link read-keyboard } " word returns objects of this class. The " { $snippet "keys" } " slot of a " { $snippet "keyboard-state" } " object contains a " { $link sequence } " of 256 members representing the state of the keys on the keyboard. Each element is a boolean value indicating whether the corresponding key is pressed. The sequence is indexed by scancode as defined under usage page 7 of the USB HID standard. Named scancode constants are provided in the " { $vocab-link "game-input.scancodes" } " vocabulary." } +{ $warning "The scancodes used to index " { $snippet "keyboard-state" } " objects correspond to physical key positions on the keyboard--they are unaffected by keymaps or other operating environment postprocessing. The face value of the constants in " { $vocab-link "game-input.scancodes" } " do not necessarily correspond to what the user expects the key to type. Because of this, " { $link read-keyboard } " should not be used for text entry purposes. The Factor UI's standard gesture mechanism should be used in cases where the logical meaning of keypresses is necessary; see " { $link "keyboard-gestures" } "." } ; + +{ keyboard-state read-keyboard } related-words diff --git a/extra/game-input/scancodes/scancodes.factor b/extra/game-input/scancodes/scancodes.factor index 747d883822..5db11845c4 100644 --- a/extra/game-input/scancodes/scancodes.factor +++ b/extra/game-input/scancodes/scancodes.factor @@ -49,7 +49,7 @@ IN: game-input.scancodes : key-= HEX: 002e ; inline : key-[ HEX: 002f ; inline : key-] HEX: 0030 ; inline -: key-/ HEX: 0031 ; inline +: key-\ HEX: 0031 ; inline : key-# HEX: 0032 ; inline : key-; HEX: 0033 ; inline : key-' HEX: 0034 ; inline @@ -158,12 +158,12 @@ IN: game-input.scancodes : key-cancel HEX: 009b ; inline : key-clear HEX: 009c ; inline : key-prior HEX: 009d ; inline -: key-return HEX: 009e ; inline +: key-enter HEX: 009e ; inline : key-separator HEX: 009f ; inline : key-out HEX: 00a0 ; inline : key-oper HEX: 00a1 ; inline -: key-clear HEX: 00a2 ; inline -: key-crsel HEX: 00a3 ; inline +: key-clear-again HEX: 00a2 ; inline +: key-crsel-props HEX: 00a3 ; inline : key-exsel HEX: 00a4 ; inline : key-left-control HEX: 00e0 ; inline : key-left-shift HEX: 00e1 ; inline diff --git a/extra/game-input/summary.txt b/extra/game-input/summary.txt new file mode 100644 index 0000000000..ef479fee55 --- /dev/null +++ b/extra/game-input/summary.txt @@ -0,0 +1 @@ +Cross-platform joystick, gamepad, and raw keyboard input diff --git a/extra/game-input/tags.txt b/extra/game-input/tags.txt new file mode 100644 index 0000000000..ae360e1776 --- /dev/null +++ b/extra/game-input/tags.txt @@ -0,0 +1,3 @@ +joysticks +gamepads +input diff --git a/extra/math/blas/matrices/matrices-docs.factor b/extra/math/blas/matrices/matrices-docs.factor index 0d9ac69171..ddd72a4a39 100644 --- a/extra/math/blas/matrices/matrices-docs.factor +++ b/extra/math/blas/matrices/matrices-docs.factor @@ -34,7 +34,16 @@ ARTICLE: "math.blas-types" "BLAS interface types" { $subsection } "For the simple case of creating a dense, zero-filled vector or matrix, simple empty object constructors are provided:" { $subsection } -{ $subsection } ; +{ $subsection } +"BLAS vectors and matrices can also be constructed from other Factor sequences:" +{ $subsection >float-blas-vector } +{ $subsection >double-blas-vector } +{ $subsection >float-complex-blas-vector } +{ $subsection >double-complex-blas-vector } +{ $subsection >float-blas-matrix } +{ $subsection >double-blas-matrix } +{ $subsection >float-complex-blas-matrix } +{ $subsection >double-complex-blas-matrix } ; ARTICLE: "math.blas.matrices" "BLAS interface matrix operations" "Transposing and slicing matrices:"