Page: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
16 17 18 19 20 21 22 23

Chapter 8

MVEX

Minimal Video Extension to X

(Version 6.2)

X Window System is a trademark of X Consortium, Inc.

Copyright © 1989, 1990, l991 Tektronix, Inc.

Permission to use, copy, modify, and distribute this document for any purpose and without fee is hereby granted, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice are retained, and that the name of Tektronix not be used in advertising or publicity pertaining to this document without specific, written prior permission. Tektronix makes no representations about the suitability of this document or the protocol defined in this document for any purpose. It is provided "as is" without express or implied warranty.

MVEX enables those models that can be fitted with color video boards to use the X-window video extension facility. The current specifications are based on the following versions:

MVEX (A Minimal Video Extension to X) Protocol Encoding Version 6.2
MVEXLib Video Extension to X Client Library Version 1-13

These versions do not conform to the X Consortium standards. They may be changed as they are introduced to the X Consortium standards.

Home

8.1. EXTERNAL INTERFACES

8.1.1 Header File and Library

Programs that use MVEX must include <Xl 1/MVEX/MVEXlib.h>.

To link the MVEX library, the -lmvex option must be specified at linkage.

8.1.2 Data Structures

These data structures are used by routines in MVEXlib:

typedef XID VideoIn;
typedef XID VideoOut;
typedef XID VedeoIO;
typedef XID VideoReference;

typedef struct {
VideoIO vio;
Atom port;
Bool frames_available;
Bool timecodes_available;
Bool frame_accurate;
} MVEXSetupState;
typedef struct {
Bool negative;
int hour;
int minute;
int second;
int frame;
int field;
} MVEXTimecode;
typedef struct {
Bool negative;
int frame;
int field;
} MVEXFrame;
typedef struct {
long numerator;
long denominator;
} MVEXFraction;
typedef struct {
long num_base;
long num_increment;
long num_limit;
int num_type; /* MVEXGeometricRange or MVEXLi nearRange */
long denom_base;
long denom_increment;
long denom_limit;
int denom_type; /* MVEXGeometricRange or MVEXLi nearRange */
} MVEXFractionRange;
typedef struct {

Home

XRectangle base;
XRectangle limit;
int x-inc;
int y_inc;
int width_inc;
int height_inc;
int type; /* MVEXGeometricRange or nearRange */
} MVEXRectangleRange;
typedef struct {
MVEXFraction frame_rate; /* max nominal rate(frames/sec) */
MVEXRectangleRange src; /* set of possible source rectangles */
MVEXRectangleRange dest; /* set of possible dest rectangles */
MVEXFractionRange x_scale; /* set of dst/src width ratios */
MVEXFractionRange y_scale; /* set of dst/src height ratios */
Bool identity_aspect; /* must x_scale ==y_scale? */
} MVEXPlacement;
typedef struct {
MVEXFraction frame_rate; /* frames/sec in signal format */
MVEXFraction field_rate; /* fields/sec in signal format */
int width; /* signal width (in pixels) */
int height; /* signal height (in pixels) */
int priority_steps; /* priority resolution */
int concurrent_use; /* max simultaneous use */
int nplacement; /* number of placements */
MVEXPlacement *placement; /* placement list */
} MVEXGeometry;
typedef struct {
Window window; /* identifies client requesting ownership */
VideoID vid; /* resource to be owned */

Home

} MVEXOwner;
typedef struct {
int depth; /* depth */
VisualID visualid; /* visual ID used for colormaps in *
/* CaptureGraphics, window in */
/* Render Video */
/* True if video input pixels cannot */
Bool opaque; /* be interpreted by a Core type */
unsigned long model_mask; /* Window, Pixmap and/or Composite */
unsigned long red_mask;
unsigned long green-mask;
unsigned long blue_mask;
} MVEXRenderModel;
typedef struct {
MVEXFraction normal_saturation;
MVEXFraction normal_contrast;
MVEXFraction normal_hue;
MVEXFraction normal_bright;
int n_saturation;
int n_contrast;
int n hue;
int n_bright;
MVEXFractionRange *saturation;
MVEXFractionRange *contrast;
MVEXFractionRange *hue;
MVEXFractionRange *bright;
} MVEXVideoAbility;
typedef struct {
VideoReference vref; /* VideoIn reference ID */
int ncontrols;
MVEXControl *controls;
MVEXGeometry geometry;
MVEXModelInfo model_info;
XRectangle clip_size;
} MVEXVin;
typedef struct {

Home

VideoReference vref; /* VideoOut reference ID */
int ncontrols;
MVEXControl *controls;
MVEXGeometry geometry;
MVEXModelInfo model_info;
} MVEXVout;
typedef struct {
int full_motion;
int priority;
int marker_type;
MVEXFrame in_frame;
MVEXFrame out_frame;
MVEXTimecode in_timecode;
MVEXTimecode out_timecode;
MVEXFraction hue;
MVEXFraction saturation;
MVEXFraction bright;
MVEXFraction contrast;
}MVEXVideoValues;

Home

8.1.3 Event Structures

typedef struct {
int type; /* of event */
unsigned long serial; /* # of last request processed by server */
Bool send_event; /* true if this came from a SendEvent request */
Display *display; /* Display the event was read from */
Window window; /* window on which video constraints were violated */
VideoIO vid; /* VideoIO whose video constraints were violated */
Time time; /* current server time */
unsigned long action_mask; /* MVEXScale Violation (1L << 0)
/* MVEXPlacementViolation */
/* MVEXClipViolation */
/* MVEXOverlapViolation */
/* MVEXHueViolation */
/* MVEXSaturationViolation */
/* MVEXContrastViolation */
/* MVEXBrightnessViolation */
int state; /* MVEXViolationSuccess,
* MVEXViolationFail, or
* MVEXVilationSubset */
} MVEXViolationEvent;
typedef struct {
int type; /* of event */
unsigned long serial; /* # of last request processed by server */
Bool send_event; /* true if this came from a SendEvent request */
Display *display; /* Display the event was read from */
Drawable window; /* unused */
VideoIO vid; /* vid on which Render/Capture was requested */
Atom port; /* port setup changed */
Time time; /* current server time */
Bool frames_available; /* true if frames can be read */
Bool timecodes_available; /* true if timecodes can be read */
Bool frame_accurate; /* true if requests are frame accurate */
} MVEXSetupEvent;
typedef struct {
int type; /* of event */
unsigned long serial; /* # of last request processed by server */
Bool send_event; /* true if this came from a SendEvent request */
Display *display; /* Display the event was read from */
VideoIO vid; /* drawable on which Render/Capture was requested */
Time time;/* current server time */
int state; /* MVEXSyncAcquired or MVEXSyncLost */
} MVEXSyncEvent;
typedef struct {
int type; /* of event */
unsigned long serial; /* # of last request processed by server */
Bool send_event; /* true if this came from a SendEvent request */
Display *display; /* Display the event was read from */
Drawable drawable; /* drawable on which Override was selected */
VideoIO vid; /* vid on which Render/Capture was requested */
VideoIO override_id; /* vid in overriding request */
Time time; /* current server time */
int state; /* Reason for override */
} MVEXOverrideEvent;
typedef struct {
int type; /* of event */
unsigned long serial; /* # of last request processed by server */
Bool send_event; /* true if this came from a SendEvent request */
Display *display; /* Display the event was read from */
Window window; /* unused */
XID src;
XIDdst;
Bool redirect;
int request; /* MVEXRender or MVEXCapture */
Time time; /* current server time */
} MVEXRequestEvent;

Home

8.1.4 MVEX Protocol Functions

8.1.4.1 MVEXChangeOwnership
MVEXChangeOwnership(display,owners ,nowners)
Display* display;
MVEXOwner owners[ ];
unsigned long nowners;
display Specifies the connection to the X server.
owners Specifies array of ownerships to set.
nowners Specifies number of entries in owners array.

For each member of the owners list, the client that created the specified window is given owner-ship of the specified resource. [See the MVEX Protocol ChangeOwnership request description]

8.1.4.2 MVEXCreateVideo
VideoIO MVEXCreate Video (display , reference)
Display *display;
VideoReference reference;
display Specifies the connection to the X server.
reference Specifies reference for which a VIDEOIO alias is requested.

Returns a VideoIO corresponding to the given VideoReference. If the MVEX extension cannot be initialized, the returned value is None. [See the MVEX Protocol Create Video request description]


(In the current release, only one resource can be decoded at a time and one video window can be displayed on the X server.)

8.1.4.3 MVEXRenderVideo
MVEXRenderVideo (display,src,dest,gc, port,src_x,src_y,src_width,src_heighT,dest_x,dest_y,d est_width,dest_height,value_mask,values)
Display *display;
VideoIn src;
Drawable dest;
GC gc;
GC port;
int src_x,src_y;
unsigned int src_width,src_height;
int dest_x,dest_y;
unsigned int dest_width,dest_height;
unsigned long value_mask;
MVEXVideo Vaues values,
display Specifies the connection to the X server.
src Specifies the video source.
dest Specifies the drawable which accepts the video signal.
gc Specifies the gc which provides the subWindowMode and the clip information.
port Specifies the port identifier for the video input.
src_x
src_y Specify the x and y coordinates of the upper-left corner of the video source rectangle.
src_width
src_height Specify the width and height of the video source rectangle.
dest_x
dest_y Specify the x and y coordinates of the upper-left corner of the destination drawable rectangle. The coordinates are relative to the origin of the destination drawable.
dest_width
dest_height Specify the width and height of the destination drawable rectangle.
value_mask Specifies the set of bits designating the values to send.
values Specifies the set of values for this request.

The specified region of the source video signal is decoded and directed to the destination drawable.
See Section 8.2.2, Remarks on DEOGEOMETRY. Accessing a videopixel can be implemented.

The values that can be specified to value_mask are as follows:

VRFullMotion Sets consecutive updating of a video signal
VRPriority Sets priorities (Not supported)
VRMarkerType none,FrameMaker, or TimecodeMarker (Not supported)
VRInFrame Sets the start frame (Not supported)
VROutFrame Sets the end frame (Not supported)
VRInTimecode Sets the start time code (Not supported)
VROutTimecode Sets the end time code (Not supported)
VRHue Sets the Hue
VRSaturation Sets the Saturation
VRBrightness Sets the Brightness
VRContrast Sets the Contrast

Home

8.1.4.4 MVEXCaptureGraphics
MVEXCaptureGraphics(display,src,dest,cmap,port, src_x,src_y,src_width,src_height, dest_x,dest_y,d est_width,dest_height, subwindow_mode, value_mask,values)
Display*display;
Drawable src;
VideoOut dest;
Colormap cmap;
Atom port;
int src_x,src_y;
unsigned int src_width,src_height;
int dest_x,dest_y;
unsigned int dest_width,dest_height;
int subwindow_mode;
unsigned long value_mask;
MVEXVideo Values values;
display Specifies the connection to the X server.
src Specifies the drawable source.
dest Specifies the video output which accepts the video signal.
cmap Specifies the colormap to use for a Pixmap drawable. Must be None for window drawable.
port Specifies the port identifier for the video output.
src_x
src_y Specify the x and y coordinates of the upper-left corner of the source drawable rectangle. The coordinates are relative to the origin of the source drawable.
src_width
src_height Specify the width and height of the drawable source rectangle.
dest_x
dest_y Specify the x and y coordinates of the upper-left corner of the destination video rectangle.
src_width
src_height Specify the width and height of the drawable source rectangle.
dest_x
dest_y Specify the x and y coordinates of the upper-left corner of the destination video rectangle.
dest_width
dest_height Specify the width and height of the destination video rectangle.
dest_height Specify the width and height of the destination video rectangle.
subwindow_mode Specifies the treatment of the source window's children. Ignored if source is a pixmap. You can pass ClipBy Children or IncludeInferiors.
value_mask Specifies the set of bits designating the values to send.
values Specifies the set of values for this request.

The specified region of the drawable source is encoded into a video signal by the destination encoder.
This function is not supported in the current release.

8.1.4.5 MVEXStopVideo
MVEXStopvideo(display,action_mask,drawables,ndrawables)
Display *display;
int action_mask;
Drawable drawables[ ];
unsigned long ndrawables;
display Specifies the connection to the X server.
action_mask Specifies the action to take on the drawables list. The mask values is a bitwise OR of these masks: MVEXStopRenderVideo and MVEXStopCaptureVideo.
drawables Specifies array of drawables to stop.
ndrawables Specifies number of entries in drawablesarray.

The video actions previously requested on any of the drawables given in the drawables array are stopped, even if one of the drawables produces an error. [See the MVEXProtocol StopVideo request description]

8.1.4.6 MVEXQuerySetup
MVEXQuerySetup (display,setup)
Display *display;
MVEXSetupState *setup;
display Specifies the connection to the X server.
setup For input, it specifies the vio and the port combination being queried. For return values, it specifies if frames and timecodes are available, and if the combination is frame-accurate on all operations.

The vio and port combination are queried its ability to "see" timecodes and/or frames, and whether it is able to perform RenderVideo or CaptureGraphics on a frame accurate basis. [See the MVEX Protocol QuerySetup request description]

8.1.4.7 MVEXQueryVideo
Status MVEXQueryVideo (display, screen_number)
Display *display;
int screen_number;
display Specifies the connection to the X server.
screen_number Specifies the screen to be updated.

[See the MVEXProtocol QueryVideo request description]
MVEXQueryVideo updates connectivity and device list information in MVEXlib. It should be called by the client after receiving a MVEXConnectivityEvent or a MVEXChangeEvent.

The client should get a new XVout array by calling MVEXGetVouts after calling MVEXQueryVideo.

MVEXQueryVideo does an implicit selection for MVEXChange events. This selection cannot be withdrawn.

Status return is non-zero if MVEXlib can be initialized. Otherwise the return is zero and MVEXlib data are not updated.

Home

8.1.4.8 MVEXSelectEvents
MVEXSelectEvents (display, id, event_mask)
Display *display;
XIS id;
unsigned long event_mask;
display Specifies the connection to the X server.
id Specifies the VideoID or Drawable on which events are selected.
event_mask Specifies the events to select.

The following table lists the event mask constants you can pass to the event_mask argument and the circumstances in which you would want to specify the event mask:

Event Mask Circumstances
NoEvent Mask No events wanted
MVEXRedirectMask MVEXRequest events wanted on a screen
(should be used only by Video Manager)
MVEXSyncMask MVEXSync events wanted
MVEXViolationMask MVEXViolation events wanted
Home

MVEXOverrideMask MVEXOverride events wanted

MVEXRequest, MVEXViolation, and MVEXOverride events can be selected only on a Drawable. MVEXSync events can be selected only on a VideoIO and MVEXControl events can be selected only on a VideoID. Selections are not cumulative; if an event is not asserted in conjunction with a valid resource for that event (e.g. not asserting MVEXOverrideMask when using a Drawable resource), the event will not be delivered on that resource regardless of earlier selections on that resource. MVEXRequest events are actually selected on the screen associated with the drawable id argument; to maintain these selections, MVEXRedirectMask must be asserted on each drawable id associated with that screen. [See the MVEX Protocol SelectVideoEvents request description]

8.1.4.8.1 MVEX Events

Every MVEX event also contains the least-significant 16 bits of the sequence number of the last request issued by the client that was (or is currently being) processed by the server.
The events particular to MVEX can be recognized from the fact that the value of the occurred event type is the same as that of the event code obtained by the utility function of MVEXBaseEvent or more. (The event codes of MVEX are set in the order of MVEXViolation, MVEXSetup, MVEXSynch, MVEXOverride, and MVEXRequest.

The meanings of individual events are given below (see Section 8.1.3, Event Structures);

MVEXViolation :
This event is reported to the client selecting ViolationNotify on the drawable. The event is generated for the specified drawable and video input or output when scaling, placement, clipping and overlap constraints are violated; it is also generated when a value for hue, saturation, contrast or brightness does not match a value listed in the abilities of the video resource. If state is Success, then the listed violations caused no discernable problem in the display or video output for the specified drawable, although some other drawable may be affected.

For scale, placement, clip and overlap, if state is Subset, then some subset of the unobscured regions are still being displayed or captured; if the state is Fail, then the originating RenderVideo and CaptureGraphics will be cancelled (no VideoOverride event is generated). Note that for pixmaps, Overlap will never be asserted.

For hue, saturation, contrast and brightness, if the state is Subset, then a suitably close value has been substituted; if the state is Fail, then normal value was substitued. Note that Violation events for these are not generated when the hardware lists no abilities for the adjustment.

The time is the current server time.

MVEXSetup :
This event is reported to the client selecting SetupNotify on the vid.
It is generated whenever the videoio-port pair changes in its ability to recognize and synchronize to rames and timecodes change.
The time is the current server time.
 
MVEXSync :
This event is reported to the client selecting SyncNotify on the vid.

It is generated following a RenderVideo request with the specified id and video input, whenever the sync is lost or gained. When selected, at least one VideoSync event is guaranteed following a RenderVideo request. An event with state Lost will be delivered if the picture cannot be rendered for some reason; e.g. no video sync, or a digital feed is down. An event with state Acquired will be delivered after the a complete frame has been rendered.

The event is also generated following a CaptureGraphics request with the specified id and video output, whenever the output signal begins to be produced. When selected, at least one VideoSync event is guaranteed following a CaptureGraphics request. An event with state Lost will be delivered if the picture cannot be captured for some reason; e.g. no video sync, or a digital feed is down. An event with state Acquired will be delivered after the a complete frame has been captured.

Note that if the original request specified fullmotion false, and the request succeeded, this will be the only event generated.

The time is the current server time.

MVEXOverride :
This event is reported to the client selecting OverrideNotify on the id. It is generated when a change in the system state causes a RenderVideo or CaptureGraphics request to stop.

Given a RenderVideo or CaptureGraphics request specifying VIDEOIO V and drawable D, the following changes in the environment will cause th request to stop, and the VideoOverride event to be generated with the specified state:

  • An unexpected hardware error; state HardwareError
  • An explicit StopVideo request with drawable D and render; state Stopped
  • a change state of the window D such that it is no longer viewable (defined by the core protocol); state DrawableChange
  • a change in the size of the window D with bitgravity ForgetGravity; state DrawableChange
  • destruction of D; state DrawableChange
  • destruction of V; state Stopped
  • a connection close for the client that created V, thereby causing destruction of the identifier V; state Stopped
  • another RenderVideo (CaptureGraphics) request specifying V as a source (destination); state Reused. Note that for every VREFERENCE, there may be many V; reuse of the same V will stop the earlier request
  • another RenderVideo (CaptureGraphics) request specifying D as a destination (source); state Reused
  • the client does not have ownership for the VIDEOIO, the concurrent use for video input resource is exhausted and some client issues a request that specifies a different VIDEOIO created from the same VIDEOREFERENCE as V; state RequestOverride; override-id will contain the VIDEOIO of the overriding request
  • An out marker was reached; state MarkerReached

Note that if a client has ownership for a VIDEOIO, the system is guaranteed never to stop an issued request given any of the conditions marked with state RequestOverride. A video resource manager may arbitrarily decide to revoke ownership at any time, but a request will not be stopped until there is contention for the resource.

Normally, when a client receives a VideoOverride event with state RequestOverride and the override-id is not its own, it should not try to restart the RenderVideo (CaptureGraphics) request until being notified by some video manager, or explicit instruction by the user. This model will work whether or not a video manager is present.

The time is the current server time.

MVEXRequest :
This event is reported to the client selecting VideoRedirect. The request element indicates whether the request was RenderVideo or CaptureGraphics.
Every RenderVideo or CaptureGraphics request using a resource for which the requesting client does not have ownership, and the concurrent use limit has been reached, and there are no non-owners using the resource, will generate a VideoRequest event with redirect set to true. Events are generated for requests that do not match this criteria with redirect set to false.

This event is intended to be used by video resource managers so that it can be notified about clients that want to use a video resource that is currently in use.

The time is the current server time.

Home

8.1.5 Application Utility Functions

8.1.5.1 MVEXMajorVersion
int MVEXMajorVersion(display)
Display *display;
display Specifies the connection to the X server.

Returns the major version for the MVEX extension if the MVEX library can be initialized; otherwise, - l is returned.

8.1.5.2 MVEXMinorVersion

int MVEXMinorVersion(display)
Display *display;
display Specifies the connection to the X server.

Returns the major version for the MVEX extension if the MVEX library can be initialized; otherwise, - l is returned.

8.1.5.3 MVEXBaseOpcode

int MVEXBaseOpCode(display)
Display *display;
display
display Specifies the connection to the X server.

Returns the major opcode for the MVEX extension if MVEXlib can be initialized; otherwise, False is returned.

8.1.5.4 MVEXBaseEvent
int MVEXBaseEvent(display)
Display *display;
display Specifies the connection to the X server.

Returns the base event type code for the MVEX extension if MVEXlib can be initialized; otherwise, False is returned.

8.1.5.5 MVEXBaseError
int MVEXBaseError(display)
Display *display;
display Specifies the connection to the X server.

Returns the base error code for the MVEX extension if MVEXlib can be initialized; otherwise, False is returned.

8.1.5.6 MVEXOverlapsOfScreen
Status MVEXOverlaps OfScreen(display screen_number,input_overlap,capture_overlapsio_overlap)
Display *display;
int screen_number;
Bool *input_overlap, *capture_overlap, *io_overlap,
display Specifies the connection to the X server.
screen_number Specifies the screen to be examined.
input_overlap Returns True if VIRs may overlap, False otherwise.
capture_overlap Returns True if VORs may overlap, False otherwise.
io_overlap Returns True if a VIR and a VOR may overlap, False otherwise.

Status return is non-zero if VEXlib can be initialized. Otherwise the return is zero and the return arguments are not updated. [See VEXProtocol QueryVideo request description]

Home

8.1.5.7 MVEXGetVisualInfo
XVisualInfo
*MVEXGetVisualIkfo(display, Xvinfo_mask, vinfo_template, nitems_return, include_core-visuals)
Display *display;
long vinfo_mask;
X VisualInfo *vinfo_template;
int *nitems_return;
Bool include_core_visuals;
display Specifies the connection to the X server.
vinfo_mask Specifies the visual mask value.
vinfo_template Specifies the visual attributes that are to be used in matching the visual structures.
nitems_return Returns the number of matching visual structures.
include_core_visuals Specifies which visuals lists should be searched. If the value is True, then both the Core and the VEX visuals lists are searched, otherwise, only the VEX list is searched.

MVEXGetVisualInfo function returns a list of visual structures that match the attributes specified by vinfo_template. If include_core_visuals is False, it returns only those visuals that are unique to VEX(not provided in the Core connection information), otherwise it returns visuals from either the Core list or the VEX list. Visuals returned by this routine are not guaranteed to have any video capability; association with video is determined by MVEXWindowModel structures returned by MVEXGetVins and MVEXGetVouts. If no visual structures match the template using the specified vinfo_mask, MVEXGetVisualInfo returns a NULL. To free the data returned by this function, use XFree. The choices for vinfo_mask and the definition for the XVisualInfo data structure are given in the Core Xlib specification (see XGetVisualInfo in Chapter l0, Application Utility Functions). Possible values for the class field of the XVisualInfo structure include MVEXVideoGray and MVEXVideoColor in addition to the Core class types.

8.1.5.8 MVEXGetVins
MVEXVin *MVEXGetVins(display,screen_number,nitems_return)
Display *display;
int screen_number;
int *nitems_return;
display Specifies the connection to the X server.
screen_number Specifies the screen to be examined.
nitems_return Returns number of MVEXVin structures in the returned MVEXVin array.

Returns an array of MVEXVin structures for the named screen. The array remains valid for the life of the connection. Returns NULL if VEXlib cannot be initialized or cannot allocate space or if there are no VideoInputs for this screen. To free the data returned by this function, use XFree.

8.1.5.9 MVEXGetVouts

MVEXVout * MVEXGetVouts(display,screen_number,nitems_return)
Display *display;
int screen_number;
int *nitems_return;
display Specifies the connection to the X server.
screen_number Specifies the screen to be examined.
nitems_return Returns number of MVEXVout structures in the returned MVEXVout, array.

Returns an array ofMVEXVout structures for the named screen. The array remains valid for the life of the connection. Returns NULL if VEXlib cannot be initialized or cannot allocate space or if there are no Video Outputs for this screen. To free the data returned by this function, use XFree.

8.1.5.10 MVEXMatchFraction
BoolMVEXMatchFraction (given,ranges,nranges,lower,higher)
MVEXFraction *given;
MVEXFractionRange *ranges;
int nranges;
MVEXFraction *lower;
MVEXFraction *higher;
given Specifies the fraction to be checked.
ranges Specifies the fraction range list to be compared against.
nranges Specifies the number of fraction ranges in the list.
lower Returns the nearest lower or equivalent fraction in the range.
higher Returns the nearest higher or equivalent fraction in the range.

Returns True if given is numerically equal to a fraction in one of the fraction ranges in ranges, in which case lower and higher are returned numerically equal to given, with the smallest values for numerator and denominator within range. For example, if given is 22/33, lower and higher could be 2/3 even if 22/33 is also in range.

Returns False otherwise. If given is between the highest and lowest fractions in all the fraction ranges in ranges, then lower is the closest fraction in ranges of less value and higher is the closest fraction in ranges of greater value. If given is below the lowest fraction in ranges, both lower and higher are that lowest fraction, while if above both are the highest.

One use of this function is to make sure a src and dest match according to the x_scale and y_scale ranges, so that the MVEXRenderVideo or MVEXCaptureGraphics functions do not get a VideoViolation event.

Home

8.1.5.11 MVEXMatchFractionInList
intMVEXMatchFractionInList(given,list,count,lowerwhigherRindex_return)
MVEXFraction *given;
MVEXFractionRange *list;
int count;
MVEXFraction *lower;
MVEXFraction *higher;
int *index_return;
given Specifies the fraction to be checked.
list Specifies the fraction list to be compared against.
count Specifies the number of fractions in the list.
lower Returns the nearest lower or equivalent fraction in the list.
higher Returns the nearest higher or equivalent fraction in the list.
index_return Returns the index of lower.

Returns True if given is numerically equal to a fraction in list, in which case lower and higher are both some fraction that is numerically equivalent to given.

Returns False otherwise. If given is between the highest and lowest fractions in list, then lower is the closest fraction of less value and higher is the closest fraction of greater value. If given is below the lowest fraction in list, both lower and higher are that lowest fraction (index_return is 0). If given is above the highest fraction in list, both lower and higher are that highest fraction (index_return is count-l ).

8.1.5.12 MVEXFractionList
MVEXFraction * MVEXFractionList(ranges,nranges,length_return)
MVEXFractionRange *ranges;
int nranges;
int *length_return;
ranges Specifies the fraction ranges to be expanded.
nranges Specifies the number of fraction ranges.
length_return Returns the number of fractions in the list.

Returns a list of fractions, with 0 occurring at most once. The list is in numerical order, least first, with numerically equivalent fractions in no particular order.

This function is intended for use with small fraction ranges, such as may be found in the VEX_SPEED control description. Fraction ranges in the placements of MVEXVin or MVEXVout structures can be too large for this function, which allocates the memory for the list. If in doubt, use MVEXFractionCount to see how big the list will be before using this function.

To free the data returned by this function, use XFree.

8.1.5.13 MVEXFractionCount
int MVEXFractionCount(ranges,nranges)
MVEXFractionRange *ranges;
int nranges;
ranges Specifies the fraction ranges to be counted.
nranges Specifies the number of fraction ranges.

Returns the number of fractions in the list of fraction ranges, which can be used to determine whether to use MVEXFractionList, above.

8.1.5.14 MVEXMatchRectangle

Bool MVEXMatchRectangle (given,range,enclosed,enclosing)
XRectangle *given;
MVEXRectangleRange *range;
XRectangle*enclosed;
XRectangle *enclosing;
given Specifies a given rectangle.
range Specifies a rectangle range.
enclosed Returns the largest rectangle in the range that is enclosed by the given rectangle, if possible.
enclosing Returns the smallest rectangle in the range that encloses the given rectangle, if possible.

Returns True if given exactly matches a rectangle in range. Then both enclosed and enclosing are returned equal to given.

Returns False otherwise. If given is within the extents of range, then enclosed is the largest rectangle in range that is completely enclosed by given and enclosing is the smallest rectangle in range that completely encloses given. But if given is partially or completely outside the extents of range, then enclosed and enclosing are as close as possible to being enclosed/enclosing while still being rectangles in range.

This function can be used to find either the proper enclosing area around a desired source area or the largest proper destination area within a given boundary, for rendering video or capturing graphics.

8.1.6 Option to the X server

To display video images using the video computer board, the X server visual must be 8-plane PseudoColor or GrayScale. (The displaying operation in other X server visual environments is not guaranteed.)

In other environments, add mvexOff to the X server starting-up option to use the video capture board, so that the MVEX extension cannot works.

8.2 NOTES

8.2.1 Notes on Port Identifiers and Signal Formats

The following three types of video board are available.

  • Full-Color graphics adapter (with video functions)
    Supports input of three kinds of video signals (NTSC format, PAL format, and SECAM format).
    Three ports (S terminal, RCA terminal l, and RCA terminal 2) are available.
  • Multimedia graphics adapter
    Supports input of four kinds of video signals (NTSC format, PAL format, SECAM format, and YUV format).
    Four ports (S terminal, RCA terminal 1, RCA terminal 2, and YUV terminal) are available.
  • Video capture board
    Supports input of two kinds of video signals (NTSC format and Input format from an application program).
    Four ports (S terminal, RCA terminal l, RCA terminal 2, and Input from an application program) are available.

In MVEXGetVins, as many MVEXVin structure pointers as there are corresponding signal formats are returned and the start address of the consecutively stored addresses is returned. An atom number for each terminal is set in the port atom array of each MVEXVin structure member. These specifications are made by specifying the MVEXRenderVideo argument 5 port when MVEXRenderVideo is executed. The atom names of the ports corresponding to the signal formats are listed below.

NTSC format
(1, 2, and 3)		 : "ntsc-s "
"ntsc-rcal "
" ntsc-rca2 "		 /* s terminal */
/* RCA terminal 1 */
/* RCA terminal 2 */
NTSC format
(1 and 2)		 : " pal-s "
" pal-rcal "
" pal-rca2 "		 /* s terminal */
/* RCA terminal 1 */
/* RCA terminal 2 */
SECAM format
(1 and 2)		 : " secam-s "
" secam-rcal "
" secam-rca2 "		 /* s terminal */
/* RCA terminal 1 */
/* RCA terminal 2 */
YUV format
(2 only)		 : " yuv " /* YUV terminal (at 2 mounting only) */
Input format from
an application
program.(3 only)		 : " apl " /* Data input from an application program. (at 3 mounting only)*/

8.2.2 Notes on VIDEOGEOMETRY

  • src_width and src_height (the width and height of the source) vary with the input signal types. (It is possible to specify values for src_width and src_height that exceed the maximum values of the signals.)

    -NTSC and YUV: 640 (width) 480 (height)

    - PAL and SECAM: 768 (width) 576 (height)

  • Suppose that dst_width is greater than src_width, or that dst_height is greater than src_height. Also, suppose that dst_x or dst_y is an odd number. Both coordinates are changed to even numbers (by adding 1). If, as a result, dst_width or dst_height exceeds the drawable dimensions, I is subtracted. In this way, the width and height of the source are corrected while preserving the width-to-height ratio.


  • Suppose that dst_width is greater than src_width, or that dst_height is greater than src_height. Also, suppose that dst_width or dst_height is an odd number. dst_width and dst_height are changed to even numbers (by subtracting 1). In this way, the width and height of the source are corrected while preserving the width-to-height ratio (MVEXScaleViolation is issued).


  • The maximum specifiable src_x and src_y positions (x- and y-coordinates of the source) depend on the X-window restrictions (-32768 to 32767). However, if the specified source area does not coincide with the input signal area, MVEXPlacementViolation is issued and nothing is displayed.


  • The limit specification positions of specifiable dst_x and dst_y (x- and y-coordinates of the destination) depend on the X-window restrictions. However, if the specified destination area does not coincide with the video drawable area, MVEXPlacementViolation is issued and nothing is displayed.


  • If apl is specified to port, 0 is forced when either crc-x or arc-y is not 0.


  • The MVEXVin structure member (geometry.placement), updated with MVEXQueryVideo and which is returned with MVEXGetVins, is represented as shown below (usable src and dst scales cannot be obtained).


  • For NTSC and YUV
    frame_rate = [30,1]
    src = [base ={-640,-480,1,1},
    limit={639,479,640,480},
    x-inc=1,y-inc =1,
    width-inc=1,height-inc=1,
    type =Linear]
    dst = [base ={-32768,-32768,1,1}
    limit={32767,32767,640,480},
    x-inc=1,y-inc =1,
    width-inc=1,height-inc=1,
    type =Linear]
    x-scale = [num-{base,inc,limit}={1,1,640},
    type =Linear
    denom-{base,inc,limit}={640,1,640}
    type =Linear]
    y-scale = [num-{base,inc,limit}={1,1,480},
    type =Linear
    denom-{base,inc,limit}={480,1,480}
    type =Linear]
    identity-aspect = False
    frame_rate = [30,1]
    src = [base ={-640,-480,1,1},
    limit={639,479,640,480},
    x-inc=1,y-inc =1,
    width-inc=1,height-inc=1,
    type =Linear]
    dst = [base ={-32768,-32768,642,482},
    limit={32767,32767,1280,960},
    x-inc=2,y-inc =2,
    width- inc=2, height-i nc=2,
    type =Linear]
    x-scale = [num-{base,inc,limit}={642,2,1280},
    type =Linear
    denom-{base,inc,limit}={640,1,640}
    type =Linear]
    y-scale = [num-{base,inc,limit}={482,2,960},
    type =Linear
    denom-{base,inc,limit}={480,1,480}
    type =Linear]
    identity-aspect = False
  • For NTSC (video capture board)
    frame_rate = [30,1]
    src = [base={-640,-480,1,1},
    limit={639,479,640,480},
    x-inc=1,y-inc=1,
    width-inc=1,height-inc=1,
    type=Linear]
    dst = [base={-32768,-32768,1,1},
    limit={32767,32767,640,480},
    x-inc=1,y-inc=1,
    width-inc=1,height-inc=1,
    type=Linear]
    x-scale = [num-{base,inc,limit}={1,1,1280}
    type=Linear
    denom-(base,inc,limit)={640,1,640}
    type=Linear]
    y-scale = [num-{base,inc,limit}={1,1,960}
    type=Linear
    denom-{base,inc,limit}={480,1,480}
    type=Linear]
    identity-aspect = False
  • For PAL and SECAM
    frame_rate = [30,1]
    src = [base ={-768,-576,1,1},
    limit={767,575,768,576},
    x-inc=1,y-inc =1,
    width-inc=1,height-inc=l,
    type =Linear]
    dst = [base ={-32768,-32768,1,1},
    limit={32767,32767,768,576},
    x-inc=1,y-inc =1,
    width-inc=1,height-inc=1,
    type =Linear]
    x-scale = [num-{base,inc,limit}={1,1,768},
    type =Linear
    denom-{base,inc,limit}={768,1,768}
    type =Linear]
    y-scale = [num-{base,inc,limit}={1,1,576},
    type =Linear
    denom-{base,inc,limit}={576,1,576}
    type =Linear]
    identity-aspect = False
    frame_rate = [30,1]
    src = [base ={-768,-576,1,1},
    limit=4767,575,768,576},
    x-inc=1,y-inc =1,
    width-inc=1,height-inc=1,
    type =Linear]
    dst = [base ={-32768,-32768,770,578},
    limit={32767,32767,1536,1152},
    x-inc=2,y-inc =2,
    width-inc=2,height-inc=2,
    type =Linear]
    x-scale = [num-{base,inc,limit}={770,2,1536},
    type =Linear
    denom-{base,inc,limit}={768,1,768}
    type =Linear]
    y-scale = [num-{base,inc,limit}={578,2,1152},
    type =Linear
    denom-{base,inc,limit}={576,1,576}
    type =Linear]
    identity-aspect = False
  • For input from an application program (video capture board)
    frame_rate = [30,1]
    src = [base={0,0,1,1},
    limit={639,479,640,480},
    x-inc=1,y-inc=1,
    width-inc=1,height-inc=1,
    type=Linear]
    dst = [base={-32768,-32768,1,1},
    limit={32767,32767,640,480},
    x-inc=1,y-inc=1,
    width-inc=1,height-inc=1,
    type=Linear]
    x-scale = [num-{base,inc,limit}={1,1,2}
    type=Linear
    denom-{base,inc,limit}={1,1,1}
    type=Linear]
    y-scale = [num-{base,inc,limit}={1,1,2}
    type=Linear
    denom-{base,inc,limit}={1,1,1}
    type=Linear]
    identity-aspect = False
  • Usable src and dst scales cannot be obtained from the MVEXVin structure member (geometry.placement->x_scale and y_scale), updated with MVEXQueryVideo and which is returned with MVEXGetVin (the contents of the structure are as described above). This is because the flexible scaling feature of the hardware cannot be represented by the MVEX protocol. When usable src and dst scales must be judged, create a routine according to the explanation given in the description of VIDEOGEOMETRY.

    Example (for NTSC)

    Check Scale(src_x src_y ,src_width ,src_height ,dst_width ,dst_height)
    int    src_x;
    int    src_y;
    int    src_width;
    int    src_height;
    int    dst_width;
    int    dst_height;
{
    if(src_x <0 || src_x + src_width > 640 || src_width <= 0
        || src_y <0 || src_y + src_height > 480 || src_height <= 0)
            return(FALSE);
    if(dst_width > src_width || dst_height > src_height){
            if(dst_width / 2*2!=dst_width)
                return(FALSE);
            if(dst_height / 2*2!=dst_height)
                return(FALSE);
            }
            if(dst_width > src_width * 2)
                return(FALSE);
            if(dst_height > src_height * 2)
                return(FALSE);
            return(TRUE);
            }
  • Suppose that dst_width is greater than src_width, or that dst_height is greater than src_height. The size of the source rectangle is reduced by half, then displayed in double mode. Note that images are displayed in relatively low resolution.

8.2.3 Notes on Saturation, Contrast, Hue, and Brightness

The saturation, contrast, hue, and brightness of video images can be changed by specifying the MVEXVideoValues structure of MVEXRenderVideo argument 15 (see Section 8.1.2). Specify any member of the MVEXFraction list for the members (saturation, contrast, hue, and brightness) of the MVEXVideoVideo structure. The MVEXFraction list is contained in the MVEXVin structure obtained by MVEXGetVins. If the MVEXVideoValues structure is set and MVEXRenderVideo is executed, render processing is performed according to the information specified by value_mask.

The members of the MVEXVin structure are represented by the following FRACTIONRANGE:

saturation { 0, 1, 255, Linear, 255, 1, 255,Linear }
contrast { 0, 1, 100, Linear, l00, 1, 100, Linear }
hue { -128, 1, 127, Linear, 127, 1, 127, Linear }
brightness { 0, 1, 100, Linear, 100, 1, 100, Linear }

If these settings are omitted, the default values are assumed. The default values are the intermediate values of FRACTIONRANGE, listed below.

Saturation default value { 127(numerator),255(denominator) }
Contrast default value { 50(numerator), 100(denominator)}
Hue default value { 0(numerator), 127(denominator) }
Brightness default value { 50(numerator), 100(denominator) }
  • The hue and saturation settings for SECAM and YUV cannot be changed due to hardware restrictions. (The intermediate values are fixed).

  • If apl is specified to port, the saturation, contrast, hue, and brightness settings cannot be changed due to hardware limitations.

  • If the denominator of the specified value differs from the denominator of FRACTIONRANGE, it is reduced to a common denominator. If the value thus obtained is other than FRACTIONRANGE, it is adjusted to an intermediate value and violation(fail) is issued. If a numerically equal value exists in FRACTIONRANGE, the value obtained by reduction to a common denominator is used for execution. If the value is within FRACTIONRANGE but it is not numerically equal, the rounded value (numerator/denominator x denominator of each FRACTIONRANGE + 0.5) is used for execution and violation(subset) is issued.

  • If MVEXRenderVideo is executed with no value specified, it is executed with an intermediate value.

Home

Contents Previous Chapter Chapter 8, Part 2