@c ---------------------------------------------------
@node Utility Functions
@section Utility Functions
@cindex Utility Functions
@c Utility Functions isvrjoystick
@c -----------------------------------------
@subsection isvrjoystick
@cindex isvrjoystick
@deftypefn {} {@var{retval} =} isvrjoystick (@var{obj})
 Check if input value is a vrjoystick object

 Function is essentially just a call of
@code {
 retval = isa(obj, "octave_joystick");
 }

@subsubheading Inputs
@var{obj} - The object to check

@subsubheading Outputs
@var{retval} is true, if obj is an vrjoystick object, false otherwise.

@xseealso{vrjoystick}
@end deftypefn
@c Utility Functions vrjoysticklist
@c -----------------------------------------
@subsection vrjoysticklist
@cindex vrjoysticklist
@deftypefn {} {} vrjoysticklist ()
@deftypefnx {} {@var{joylist} =} vrjoysticklist ()
 Get or print the available joystick devices.

@subsubheading Inputs
 None

@subsubheading Outputs
@var{joylist} - a list of joystick ID, Name, ForceFeedbackSupported structures.@*

@subsubheading Examples
 Display available joysticks
@example
@code {
 vrjoysticklist;
 }
@end example

 Get a list available joysticks to a variable
@example
@code {
 joylist = joysticklist;
 }
@end example

 The list will contain ID, Name and ForceFeedbackSupported entries for each joystick.

@xseealso{vrjoystick}
@end deftypefn
@c ---------------------------------------------------
@node Joystick Functions
@section Joystick Functions
@cindex Joystick Functions
@c Joystick Functions @octave_joystick/axis
@c -----------------------------------------
@subsection @@octave_joystick/axis
@cindex axis
@deftypefn {} {@var{joy} =} axis (@var{joy}, @var{id})
 Get the value of axis @var{id} on joystick @var{joy}.

@subsubheading Inputs
@var{joy} - a previously opened joystick object@*
@var{id} - a positive numeric id for the joystick axis to use@*

@var{id} can be a vector of ids to allow getting multiple axis.

@subsubheading Outputs
@var{value} - value of the axis between -1 .. 1.@*

@var{value} will be a vector of values when getting multiple axis.

@subsubheading Examples
 Open device 1 and get value of axis 1
@example
@code {
 joy = vrjoystick(1);
 val = axis(joy, 1)
 }
@end example

@xseealso{vrjoystick}
@end deftypefn
@c Joystick Functions @octave_joystick/button
@c -----------------------------------------
@subsection @@octave_joystick/button
@cindex button
@deftypefn {} {@var{joy} =} button (@var{joy}, @var{id})
 Get the value of button @var{id} on joystick @var{joy}.

@subsubheading Inputs
@var{joy} - a previously opened joystick object@*
@var{id} - a positive numeric id for the joystick button to use@*

@var{id} can be a vector of ids to allow getting multiple buttons.

@subsubheading Outputs
@var{value} - value of the button (0 or 1).@*

@var{value} will be a vector of values when getting multiple buttons.

@subsubheading Examples
 Open device 1 and get value of button 1
@example
@code {
 joy = vrjoystick(1);
 val = button(joy, 1)
 }
@end example

@xseealso{vrjoystick}
@end deftypefn
@c Joystick Functions @octave_joystick/caps
@c -----------------------------------------
@subsection @@octave_joystick/caps
@cindex caps
@deftypefn {} {@var{info} =} caps (@var{joy})
 Get the capabilities joystick @var{joy}.

@subsubheading Inputs
@var{joy} - a previously opened joystick object@*

@subsubheading Outputs
@var{info} - A struct with fields Axis, Buttons, Force, POVs to hold the numeric count of each in joystick.@*

@subsubheading Examples
 Open device 1 and capabilities
@example
@code {
 joy = vrjoystick(1);
 c = caps(joy)
 }
@end example

@xseealso{vrjoystick}
@end deftypefn
@c Joystick Functions @octave_joystick/close
@c -----------------------------------------
@subsection @@octave_joystick/close
@cindex close
@deftypefn {} {} close (@var{joy})
 Close opened joystick @var{joy}.

 After closing the joystick querying the device will no longer work.

@subsubheading Inputs
@var{joy} - a previously opened joystick object@*

@subsubheading Outputs
 None

@xseealso{vrjoystick}
@end deftypefn
@c Joystick Functions @octave_joystick/force
@c -----------------------------------------
@subsection @@octave_joystick/force
@cindex force
@deftypefn {} {@var{joy} =} force (@var{joy}, @var{id}, @var{forcevalue})
 Apply forcefeedback on axis @var{id} on joystick @var{joy}.

@subsubheading Inputs
@var{joy} - a previously opened joystick object@*
@var{id} - a positive numeric id for the joystick forcefeed axis to use@*
@var{forcevalue} - force value to use, values should be between -1 .. 1@*

 If @var{id} is a vector of axis ids, @var{forcevalue} is expected to be a
 single value applied to all of the specified axis or a vector of the same size
 as @var{id}, with a value for  each axis.

@subsubheading Outputs
 None

@xseealso{vrjoystick}
@end deftypefn
@c Joystick Functions @octave_joystick/pov
@c -----------------------------------------
@subsection @@octave_joystick/pov
@cindex pov
@deftypefn {} {@var{joy} =} pov (@var{joy}, @var{id})
 Get the value of pov @var{id} on joystick @var{joy}.

@subsubheading Inputs
@var{joy} - a previously opened joystick object@*
@var{id} - a positive numeric id for the joystick pov to use@*

@var{id} can be a vector of ids to allow getting multiple povs.

@subsubheading Outputs
@var{value} - value of the pov as an angle in degrees, or -1 if not pressed.@*

@var{value} will be a vector of values when getting multiple buttons.

@subsubheading Examples
 Open device 1 and get value of pov 1
@example
@code {
 joy = vrjoystick(1);
 val = pov(joy, 1)
 }
@end example

@xseealso{vrjoystick}
@end deftypefn
@c Joystick Functions @octave_joystick/read
@c -----------------------------------------
@subsection @@octave_joystick/read
@cindex read
@deftypefn {} {[@var{axes}, @var{buttons}, @var{povs}] =} read (@var{joy})
 Get the value of all axes, buttons and povs joystick @var{joy}.

@subsubheading Inputs
@var{joy} - a previously opened joystick object@*

@subsubheading Outputs
@var{axes} - vector of the axis values.@*
@var{buttons} - vector of the button values.@*
@var{povs} - vector of the pov values.@*

@xseealso{vrjoystick, axis, pov, buttons}
@end deftypefn
@c Joystick Functions vrjoystick
@c -----------------------------------------
@subsection vrjoystick
@cindex vrjoystick
@deftypefn {} {@var{joy} =} vrjoystick (@var{id})
@deftypefnx {} {@var{joy} =} vrjoystick (@var{id}, @var{"forcefeedback"})
 Attempt to open a joystick.

@subsubheading Inputs
@var{id} - a positive numeric id for the joystick device to use.@*
@var{"forcefeedback"} - String constant to enable forcefeedback.@*

@subsubheading Outputs
@var{joy} - a octave_joystick object.@*

@subsubheading Joystick Properties
 A joystick object has the following properties:
@table @asis
@item ID
 The ID of the joystick as used to create the joystick
@item Name
 The name of the joystick device
@item Status
 Status of the joystick ("Open" or "Closed")
@item ForceFeedbackSupported
 Boolean for if the joystick was opened with forcefeedback enabled and
 supports forcefeedback.
@end table

@subsubheading Joystick  Functions
 A joystick object provides the following functions:
@table @asis
@item axis
 Get the value of a joystick axis
@item buttons
 Get the state of a joystick button
@item caps
 Get the capabilities of the joystick
@item close
 Close a joystick
@item force
 Set the forcefeedback forces on a joystick
@item pov
 Get the pov values from a joystick
@item read
 Read all state values from a joystick
@end table

@subsubheading Examples
 Open device 1
@example
@code {
 joy = vrjoystick(1);
 }
@end example

@xseealso{vrjoysticklist}
@end deftypefn
