XSGIvcSetScreenInputSyncSource(3XSGIvcSetScreenInputSyncSource(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.
Page 1 (printed 7/20/06)
XSGIvcSetScreenInputSyncSource(3XSGIvcSetScreenInputSyncSource(3)
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
Page 2 (printed 7/20/06)
XSGIvcSetScreenInputSyncSource(3XSGIvcSetScreenInputSyncSource(3)
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
Page 3 (printed 7/20/06)
XSGIvcSetScreenInputSyncSource(3XSGIvcSetScreenInputSyncSource(3)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
Page 4 (printed 7/20/06)
XSGIvcSetScreenInputSyncSource(3XSGIvcSetScreenInputSyncSource(3)
XSGIvc, XSGIvcQueryChannelInfo,
Page 5 (printed 7/20/06)
