XSGIvcSetScreenInputSyncSource(3)

     NAME
          XSGIvcSetScreenInputSyncSource,
          XSGIvcQueryScreenInputSyncSource - Switch sync source

     SYNOPSIS
          #include <X11/extensions/XSGIvc.h>

          void XSGIvcSetScreenInputSyncSource(Display *display,
              int screen,
              int syncVoltage,
              int syncSource)

          void XSGIvcSetScreenExternalSyncSource(Display *display,
              int screen,
              int externalSyncSource)

          Status XSGIvcQueryScreenInputSyncSource(Display *display,
              int screen,
              int *syncVoltageReturn,
              int *syncSourceReturn,
              Bool *lockAchievedReturn)

          Status XSGIvcQueryScreenExternalSyncSource(Display *display,
              int screen,
              int *externalSyncSourceReturn)

          char * XSGIvcQueryExternalSyncSourceName(Display *display,
              int screen,
               int externalSyncSource)

     PARAMETERS
          display        Specifies the connection to the X server.

          screen         Specifies the screen of the X server.

          syncVoltage    Specifies the voltage.  Should be specified
                         as one of XSGIVC_SYNC_VOLTAGE_VIDEO (for
                         nominal video voltage level) or
                         XSGIVC_SYNC_VOLTAGE_TTL (for TTL-level sync).
                         Not all servers have the capability to accept
                         both voltage levels; check documentation for
                         the specific hardware you are using.

          externalSyncSource
                         Specifies the external sync source.  The
                         values range [0..External Source Count).

          syncSource     Use XSGIVC_SYNC_SOURCE_EXTERNAL to specify
                         the external sync source,
                         XSGIVC_SYNC_SOURCE_INTERNAL to specify the
                         internal sync source.

          syncVoltageReturn
                         Returns the current sync voltage.

          syncSourceReturn
                         Returns the current sync source.

          lockAchievedReturn
                         Returns the state of lock (TRUE if lock
                         achieved, FALSE if lock not achieved).  See
                         terminology, below, for explanation.

          externalSyncSourceReturn
                         Returns the current external sync source.


     DESCRIPTION
          These functions control the source of input sync to the
          graphics subsystem.  The input sync is used as a reference
          to which the server can lock.  The information returned from
          the function XSGIvcQueryVideoScreenInfo can help you
          determine whether the server currently has the capability to
          lock to an external source.


        Terminology and Operation
          The concept of locking refers to the ability of a video
          system to evaluate the synchronization portion of a video
          signal of an external source and produce a signal which is
          at the same rate as that external signal.  Locking the
          server to an external source is needed in environments where
          the server's video output must be synchronized with other
          video or film sources in order to be mixed externally.

          The term genlock describes a particular type of lock:  one
          in which both horizontal and vertical synchronization
          signals are locked.  It is often used as a general term for
          locking in environments where all video devices generate and
          use the same video formats; in this circumstance, the term
          genlock is correct.  See the discussion of Lock Quality
          below.

          A server may operate in a stand-alone environment in the
          absence of a stable external locking signal; by using this
          internal lock, the server locks to a clock generated within
          the server hardware.  With external lock, the server locks
          to a signal you supply externally, either on an external
          sync connector or other means, such as internally-connected
          special video hardware.

          When you instruct the server to use external sync (external
          lock), the server examines the synchronization signal
          provided on the external input sync port.  If the server
          hardware recognizes the signal's pattern, the server locks
          the rate to that of the signal. After the server's rates
          have been set successfully, the server is said to be locked
          to the external signal.

          When you specify the server should use internal lock, the
          server will disregard any external signal.  Because internal
          lock allows the server to produce video at a rate
          independent of any external source, it is often described as
          being "not locked" or has disabled lock.


        Usage
          If the server is used in a stand-alone environment, it is
          not necessary to set the sync source to anything but the
          internal source; the server will produce its output locked
          to its own reference.  However, in applications where the
          graphics output must be synchronized to an external source,
          you can direct the server to use the external source as lock
          reference.


        Lock Quality
          Different servers have different capabilities when locking
          to an external source, and the quality of lock may vary
          depending on the input source and the generated output
          format.

          Under some circumstances, the server may be able to lock to
          both horizontal and vertical rates of the external signal:
          the most stable lock, commonly known as genlock.  Some
          circumstances may permit the server to lock to only the
          vertical rate of the incoming signal.  In other cases, the
          server may be able to provide a reference at multiple
          instances within a frame, a quality between those two
          extremes.  Finally, some combination of input and output
          format or some servers may not permit any lock. Refer to
          your server's documentation to determine the qualities of
          lock available.


        External Sync Sources
          Some servers have more than one external sync source. For
          example, a server may have more than one connector on which
          sync can be provided; or, a server's hardware might have an
          option board which can also provide a sync source.  Because
          of the nature of locking (see Terminology and Operation
          above), only one sync source may be selected at a time.



        Functions
          XSGIvcSetScreenInputSyncSource sets the server's Screen sync
          source to the internal or external source.

          XSGIvcQueryScreenInputSyncSource returns the current
          settings of the sync source for the server's Screen.  This
          function also returns the current state of the lock.

          For servers with more than one external sync source,
          XSGIvcSetScreenExternalSyncSource selects which external
          source is to be used for locking.  The structure returned by
          the function XSGIvcQueryVideoScreenInfo has a member field
          containing the number of external sync sources.  The
          function XSGIvcQueryScreenExternalSyncSource returns the
          currently selected external sync source. Selecting an
          external sync source with XSGIvcSetScreenExternalSyncSource
          does not switch from the internal to the external sync
          source; it is still necessary to use the function
          XSGIvcSetScreenInputSyncSource to switch from internal to
          external sync source.

          For convenience in presenting information to a user,
          XSGIvcQueryExternalSyncSourceName returns the textual name
          associated with the sync source.  You must free the returned
          string with XFree.


     EVENTS
          The sync source state change event reports dynamic input
          sync source state changes.  The server generates a
          ScreenLockStatusChangedNotify  event when the server
          achieves or loses lock.  This allows you to determine when a
          server achieves lock. The server may not be able to report
          intervening instances of rapidly changing lock state and
          therefore may report two consecutive instances of the same
          state; client programs must check the value of the status
          variable reported in the event to determine the state of the
          lock.

          When this control is altered, the server generates a
          ScreenInputSyncSourceNotify event.



     RETURNED VALUE
          XSGIvcQueryScreenInputSyncSource returns TRUE if successful,
          FALSE upon failure.

          Parameter errors are reported via BadValue or BadMatch.



     SEE ALSO
          XSGIvc, XSGIvcQueryChannelInfo,