\input texinfo @c -*-texinfo-*-
@c Copyright (c) 2021-2023, John Donoghue <john.donoghue@ieee.org>
@c Octave Joystick - Basic implementation of vrjoystick functions

@c For manually generating the documentation use
@c   LANGUAGE=en makeinfo --html --no-split joystick.texi

@c %*** Start of HEADER
@setfilename joystick.info
@settitle Octave Joystick - Basic implementation of vrjoystick for GNU Octave
@afourpaper
@paragraphindent 0
@finalout
@set COPYRIGHT_DATE 2021-2023
@c @afourwide
@c %*** End of the HEADER

@include version.texi
@include macros.texi

@c %*** Start of TITLEPAGE
@titlepage
@center @image{joystick-logo}
@vskip 0pt plus 1filll
@title Joystick Toolkit @value{VERSION}
@subtitle Joystick functions for @acronym{GNU} Octave.
@author John Donoghue
@page
@vskip 0pt plus 1filll
Copyright @copyright{} @value{COPYRIGHT_DATE} John Donoghue

Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the same conditions as for modified versions.

@page
@heading Distribution
The @acronym{GNU} Octave Joystick package is @dfn{free} software.
Free software is a matter of the users' freedom to run, copy, distribute,
study, change and improve the software.
This means that everyone is free to use it and free to redistribute it
on certain conditions.  The @acronym{GNU} Octave Joystick package
is not, however, in the public domain.  It is copyrighted and there are
restrictions on its distribution, but the restrictions are designed to
ensure that others will have the same freedom to use and redistribute
Octave that you have.  The precise conditions can be found in the
@acronym{GNU} General Public License that comes with the @acronym{GNU}
Octave Joystick package and that also appears in @ref{Copying}.

To download a copy of the @acronym{GNU} Octave Joystick package, please visit
@url{https://gnu-octave.github.io/octave-joystick/}.

@end titlepage
@c %*** End of TITLEPAGE

@dircategory Math
@direntry
* Joystick for Octave: (joystick).         Joystick Toolbox for Octave 
@end direntry

@c %*** Start of BODY
@contents
@ifnottex
@node Top
@top Introduction
The Joystick toolkit is a set of Joystick file I/O routines for GNU Octave
@end ifnottex

@menu
* Installing and loading::    Installing and loading the Joystick toolkit
* Basic Usage Overview::      Basic Usage Overview
* Function Reference::        Joystick toolkit functions
* Copying::                   Copying
* Index::                     Index
@end menu

@c -------------------------------------------------------------------------
@node Installing and loading
@chapter Installing and loading
@cindex Installing and loading

The Joystick toolkit must be installed and then loaded to be used.

It can be installed in @acronym{GNU} Octave directly from octave-forge,
or can be installed in an off-line mode via a downloaded tarball.

The toolkit has a dependency on the SDL library (@url{http://www.libsdl.org/}), so it must be installed in order
to successfully install the Joystick toolkit.

For Fedora: @code{yum install sdl2-devel} 

For Ubuntu: @code{apt install libsdl2-dev} 

The toolkit must be then be loaded once per each @acronym{GNU} Octave session in order to use its functionality.

@section Online Direct install
@cindex Online install
With an internet connection available, the Joystick package can be installed from
the octave-joystick website using the following command within @acronym{GNU} Octave:

@example
pkg install -forge joystick
@end example

The latest released version of the toolkit will be downloaded and installed.

@section Off-line install
@cindex Off-line install
With the Joystick toolkit package already downloaded, and in the current directory when running
@acronym{GNU} Octave, the package can be installed using the following command within @acronym{GNU} Octave:

@example
pkg install joystick-@value{VERSION}.tar.gz
@end example

@section Loading
@cindex Loading
Regardless of the method of installing the Joystick toolkit, in order to use its functions,
the toolkit must be loaded using the pkg load command:

@example
pkg load joystick
@end example

The toolkit must be loaded on each @acronym{GNU} Octave session.

@c -------------------------------------------------------------------------
@node Basic Usage Overview
@chapter Basic Usage Overview
@cindex Basic Usage Overview

A list of available joysticks available can be obtained using the vrjoysticklist function.

@example
> vrjoysticklist 
id name                   forcefeedbacksupported
 1 logitech dual action   0
@end example

The ID value is then used to create a joystick object.
@example
> joy = vrjoystick(1)
joy =

  Joystick object
      ID: 1
    Name: Logitech Dual Action
@end example

The capabilities of the joystick can be read to determine number of axis and buttons are available.

@example
> caps(joy)
ans =

  scalar structure containing the fields:

    Axes = 4
    Buttons = 12
    POVs = 1
    Forces = 0
@end example

The axis and button states can be read for any axis or button number.

@example
> a1 = axis(joy, 1)
a1 = 0

> b1 = button(joy, 1)
b1 = 0
@end example

@c -------------------------------------------------------------------------
@node Function Reference
@chapter Function Reference
@cindex Function Reference

The functions currently available in the Joystick toolkit are described below;

@include functions.texi

@c -------------------------------------------------------------------------

@include gpl.texi

@c -------------------------------------------------------------------------
@node Index 
@unnumbered Index 
 
@printindex cp
 
@bye
