~ubuntu-branches/ubuntu/natty/libxxf86vm/natty

XF86VidModeQueryExtension, XF86VidModeQueryVersion, XF86VidModeSetClientVersion, XF86VidModeGetModeLine, XF86VidModeGetAllModeLines, XF86VidModeDeleteModeLine, XF86VidModeModModeLine, XF86VidModeValidateModeLine, XF86VidModeSwitchMode, XF86VidModeSwitchToMode, XF86VidModeLockModeSwitch, XF86VidModeGetMonitor, XF86VidModeGetViewPort, XF86VidModeSetViewPort, XF86VidModeGetDotClocks, XF86VidModeGetGamma, XF86VidModeSetGamma, XF86VidModeGetGammaRamp, XF86VidModeSetGammaRamp, XF86VidModeGetGammaRampSize, XF86VidModeGetPermissions \- Extension libary for the XFree86-VidMode X extension

.SH SYNTAX

.nf

.LP

\&#include <X11/extensions/xf86vmode.h>

.LP

Bool XF86VidModeQueryExtension(

Display *\fIdisplay\fP\^,

int *\fIevent_base_return\fP\^,

int *\fIerror_base_return\fP\^);

.LP

Bool XF86VidModeQueryVersion(

Display *\fIdisplay\fP\^,

int *\fImajor_version_return\fP\^,

int *\fIminor_version_return\fP\^);

.LP

Bool XF86VidModeSetClientVersion(

Display *\fIdisplay\fP\^);

.LP

Bool XF86VidModeGetModeLine(

Display *\fIdisplay\fP\^,

int \fIscreen\fP\^,

int *\fIdotclock_return\fP\^,

XF86VidModeModeLine *\fImodeline\fP\^);

.LP

Bool XF86VidModeGetAllModeLines(

Display *\fIdisplay\fP\^,

int \fIscreen\fP\^,

int *\fImodecount_return\fP\^,

XF86VidModeModeInfo ***\fImodesinfo\fP\^);

.ig

.LP

Bool XF86VidModeAddModeLine(

Display *\fIdisplay\fP\^,

int \fIscreen\fP\^,

XF86VidModeModeInfo *\fImodeline\fP\,

XF86VidModeModeInfo *\fIaftermode\fP\^);

.LP

Bool XF86VidModeDeleteModeLine(

Display *\fIdisplay\fP\^,

int \fIscreen\fP\^,

XF86VidModeModeInfo *\fImodeline\fP\^);

.LP

Bool XF86VidModeModModeLine(

Display *\fIdisplay\fP\^,

int \fIscreen\fP\^,

XF86VidModeModeLine *\fImodeline\fP\^);

.LP

Status XF86VidModeValidateModeLine(

Display *\fIdisplay\fP\^,

int \fIscreen\fP\^,

XF86VidModeModeLine *\fImodeline\fP\^);

.LP

Bool XF86VidModeSwitchMode(

Display *\fIdisplay\fP\^,

int \fIscreen\fP\^,

int \fIzoom\fP\^);

.LP

Bool XF86VidModeSwitchToMode(

Display *\fIdisplay\fP\^,

int \fIscreen\fP\^,

XF86VidModeModeInfo *\fImodeline\fP\^);

.LP

Bool XF86VidModeLockModeSwitch(

Display *\fIdisplay\fP\^,

int \fIscreen\fP\^,

int \fIlock\fP\^);

.LP

Bool XF86VidModeGetMonitor(

Display *\fIdisplay\fP\^,

int \fIscreen\fP\^,

XF86VidModeMonitor *\fImonitor\fP\^);

.LP

Bool XF86VidModeGetViewPort(

Display *\fIdisplay\fP\^,

int \fIscreen\fP\^,

int *\fIx_return\fP\^,

int *\fIy_return\fP\^);

.LP

Bool XF86VidModeSetViewPort(

Display *\fIdisplay\fP\^,

int \fIscreen\fP\^,

int \fIx\fP\^,

100

int \fIy\fP\^);

101

.LP

102

XF86VidModeGetDotClocks(

103

Display *\fIdisplay\fP\^,

104

int \fIscreen\fP\^,

105

int *\fIflags return\fP\^,

106

int *\fInumber of clocks return\fP\^,

107

int *\fImax dot clock return\fP\^,

108

int **\fIclocks return\fP\^);

109

.LP

110

XF86VidModeGetGamma(

111

Display *\fIdisplay\fP\^,

112

int \fIscreen\fP\^,

113

XF86VidModeGamma *\fIGamma\fP\^);

114

.LP

115

XF86VidModeSetGamma(

116

Display *\fIdisplay\fP\^,

117

int \fIscreen\fP\^,

118

XF86VidModeGamma *\fIGamma\fP\^);

119

.LP

120

XF86VidModeGetGammaRamp(

121

Display *\fIdisplay\fP\^,

122

int \fIscreen\fP\^,

123

int \fIsize\fP\^,

124

unsigned short *\fIred array\fP\^,

125

unsigned short *\fIgreen array\fP\^,

126

unsigned short *\fIblue array\fP\^);

127

.LP

128

XF86VidModeSetGammaRamp(

129

Display *\fIdisplay\fP\^,

130

int \fIscreen\fP\^,

131

int \fIsize\fP\^,

132

unsigned short *\fIred array\fP\^,

133

unsigned short *\fIgreen array\fP\^,

134

unsigned short *\fIblue array\fP\^);

135

.LP

136

XF86VidModeGetGammaRampSize(

137

Display *\fIdisplay\fP\^,

138

int \fIscreen\fP\^,

139

int *\fIsize\fP\^);

140

.fi

141

.SH ARGUMENTS

142

.IP \fIdisplay\fP 2i

143

Specifies the connection to the X server.

144

.IP \fIscreen\fP 2i

145

Specifies which screen number the setting apply to.

146

.IP \fIevent_base_return\fP 2i

147

Returns the base event number for the extension.

148

.IP \fIerror_base_return\fP 2i

149

Returns the base error number for the extension.

150

.IP \fImajor_version_return\fP 2i

151

Returns the major version number of the extension.

152

.IP \fIminor_version_return\fP 2i

153

Returns the minor version number of the extension.

154

.IP \fIdotclock_return\fP 2i

155

Returns the clock for the mode line.

156

.IP \fImodecount_return\fP 2i

157

Returns the number of video modes available in the server.

158

.IP \fIzoom\fP 2i

159

If greater than zero, indicates that the server should switch to

160

the next mode, otherwise switch to the previous mode.

161

.IP \fIlock\fP 2i

162

Indicates that mode switching should be locked, if non-zero.

163

.IP \fImodeline\fP 2i

164

Specifies or returns the timing values for a video mode.

165

.ig

166

.IP \fIaftermode\fP 2i

167

Specifies the timing values for the video mode after which the

168

new mode will added.

169

170

.IP \fImodesinfo\fP 2i

171

Returns the timing values and dotclocks for all of the available

172

video modes.

173

.IP \fImonitor\fP 2i

174

Returns information about the monitor.

175

.IP \fIx\fP 2i

176

Specifies the desired X location for the viewport.

177

.IP \fIx_return\fP 2i

178

Returns the current X location of the viewport.

179

.IP \fIy\fP 2i

180

Specifies the desired Y location for the viewport.

181

.IP \fIy_return\fP 2i

182

Returns the current Y location of the viewport.

183

.SH STRUCTURES

184

.nf

185

.ta 2.25i 3.5i

186

\fIVideo Mode Settings:\fP

187

typedef struct {

188

unsigned short hdisplay; /\(** Number of display pixels horizontally */

189

unsigned short hsyncstart; /\(** Horizontal sync start */

190

unsigned short hsyncend; /\(** Horizontal sync end */

191

unsigned short htotal; /\(** Total horizontal pixels */

192

unsigned short vdisplay; /\(** Number of display pixels vertically */

193

unsigned short vsyncstart; /\(** Vertical sync start */

194

unsigned short vsyncend; /\(** Vertical sync start */

195

unsigned short vtotal; /\(** Total vertical pixels */

196

unsigned int flags; /\(** Mode flags */

197

int privsize; /\(** Size of private */

198

INT32 *private; /\(** Server privates */

199

} XF86VidModeModeLine;

200

.sp

201

typedef struct {

202

unsigned int dotclock; /\(** Pixel clock */

203

unsigned short hdisplay; /\(** Number of display pixels horizontally */

204

unsigned short hsyncstart; /\(** Horizontal sync start */

205

unsigned short hsyncend; /\(** Horizontal sync end */

206

unsigned short htotal; /\(** Total horizontal pixels */

207

unsigned short vdisplay; /\(** Number of display pixels vertically */

208

unsigned short vsyncstart; /\(** Vertical sync start */

209

unsigned short vsyncend; /\(** Vertical sync start */

210

unsigned short vtotal; /\(** Total vertical pixels */

211

unsigned int flags; /\(** Mode flags */

212

int privsize; /\(** Size of private */

213

INT32 *private; /\(** Server privates */

214

} XF86VidModeModeInfo;

215

.LP

216

\fIMonitor information:\fP

217

typedef struct {

218

char* vendor; /\(** Name of manufacturer */

219

char* model; /\(** Model name */

220

float EMPTY; /\(** unused, for backward compatibility */

221

unsigned char nhsync; /\(** Number of horiz sync ranges */

222

XF86VidModeSyncRange* hsync; /\(** Horizontal sync ranges */

223

unsigned char nvsync; /\(** Number of vert sync ranges */

224

XF86VidModeSyncRange* vsync; /\(** Vertical sync ranges */

225

} XF86VidModeMonitor;

226

.sp

227

typedef struct {

228

float hi; /\(** Top of range */

229

float lo; /\(** Bottom of range */

230

} XF86VidModeSyncRange;

231

.LP

232

typedef struct {

233

int type; /\(** of event */

234

unsigned long serial; /\(** # of last request processed by server */

235

Bool send_event; /\(** true if this came from a SendEvent req */

236

Display *display; /\(** Display the event was read from */

237

Window root; /\(** root window of event screen */

238

int state; /\(** What happened */

239

int kind; /\(** What happened */

240

Bool forced; /\(** extents of new region */

241

Time time; /\(** event timestamp */

242

} XF86VidModeNotifyEvent;

243

.LP

244

typedef struct {

245

float red; /\(** Red Gamma value */

246

float green; /\(** Green Gamma value */

247

float blue; /\(** Blue Gamma value */

248

} XF86VidModeGamma;

249

.fi

250

.SH DESCRIPTION

251

These functions provide an interface to the server extension

252

\fIXFree86-VidModeExtension\fP

253

which allows the video modes to be

254

queried and adjusted dynamically and mode switching to be controlled.

255

Applications that use these functions must be linked with

256

.ZN -lXxf86vm

257

.SS "MODELINE FUNCTIONS"

258

The

259

.ZN XF86VidModeGetModeLine

260

function is used to query the settings for the currently selected

261

video mode. The calling program should pass a pointer to a

262

.ZN XF86VidModeModeLine

263

structure that it has already allocated. The function fills in

264

the fields of the structure.

265

.PP

266

If there are any server private values (currently only applicable to

267

the S3 server) the function will allocate storage for them.

268

Therefore, if the

269

.ZN privsize

270

field is non-zero, the calling program should call

271

.ZN Xfree(private)

272

to free the storage.

273

.PP

274

.ZN XF86VidModeGetAllModeLines

275

returns the settings for all video modes.

276

The calling program supplies the address of a pointer which will be

277

set by the function to point to an array of

278

.ZN XF86VidModeModeInfo

279

structures. The memory occupied by the array is dynamically allocated

280

by the

281

.ZN XF86VidModeGetAllModeLines

282

function and should be freed by the caller.

283

The first element of the array corresponds to the current video mode.

284

.PP

285

The

286

.ZN XF86VidModeModModeLine

287

function can be used to change the settings of the current video mode

288

provided the requested settings are valid (e.g. they don't exceed the

289

capabilities of the monitor).

290

.PP

291

.ig

292

To add a mode to the list of available modes, the

293

.ZN XF86VidModeAddModeLine

294

function can be used.

295

Assuming the settings are valid, the video mode will be added after

296

the existing mode which matches the timings specified by the

297

.ZN aftermode

298

parameter.

299

To be considered a match, all of the fields of the given

300

.ZN XF86VidModeModeInfo

301

structure must match, except the

302

.ZN privsize

303

and

304

.ZN private

305

fields.

306

If the

307

.ZN aftermode

308

parameter is zero, the mode will be added

309

after the current mode.

310

.PP

311

312

Modes can be deleted with the

313

.ZN XF86VidModeDeleteModeLine

314

function. The specified mode must match an existing mode.

315

To be considered a match, all of the fields of the given

316

.ZN XF86VidModeModeInfo

317

structure must match, except the

318

.ZN privsize

319

and

320

.ZN private

321

fields.

322

If the mode to be deleted is the current mode, a mode switch

323

to the next mode will occur first. The last remaining mode can not

324

be deleted.

325

.PP

326

The validity of a mode can be checked with the

327

.ZN XF86VidModeValidateModeLine

328

function.

329

If the specified mode can be used by the server (i.e. meets all the

330

constraints placed upon a mode by the combination of the server, card,

331

and monitor) the function returns

332

.ZN MODE_OK ,

333

otherwise it returns a value indicating the reason why the mode is

334

invalid (as defined in \fIxf86.h\fP)

335

.SS "MODE SWITCH FUNCTIONS"

336

When the function

337

.ZN XF86VidModeSwitchMode

338

is called, the server will change the video mode to next (or previous)

339

video mode. The

340

.ZN XF86VidModeSwitchToMode

341

function can be used to switch directly to the specified mode.

342

Matching is as specified in the description of the

343

.ZN XF86VidModeAddModeLine

344

function above.

345

The

346

.ZN XF86VidModeLockModeSwitch

347

function can be used to allow or disallow mode switching whether

348

the request to switch modes comes from a call to the

349

.ZN XF86VidModeSwitchMode

350

351

.ZN XF86VidModeSwitchToMode

352

functions or from one of the mode switch key sequences.

353

.PP

354

.RB Note:

355

Because of the asynchronous nature of the X protocol, a call to

356

.ZN XFlush

357

is needed if the application wants to see the mode change immediately.

358

To be informed of the execution status of the request, a

359

custom error handler should be installed using

360

.ZN XSetErrorHandler

361

before calling the mode switching function.

362

.SS "MONITOR FUNCTIONS"

363

Information known to the server about the monitor is returned by the

364

.ZN XF86VidModeGetMonitor

365

function. The

366

.ZN hsync

367

and

368

.ZN vsync

369

fields each point to an array of

370

.ZN XF86VidModeSyncRange

371

structures. The arrays contain

372

.ZN nhsync

373

and

374

.ZN nvsync

375

elements, respectively.

376

The

377

.ZN hi

378

and

379

.ZN low

380

values will be equal if a discreate value was given in the

381

.ZN XF86Config

382

file.

383

.PP

384

The

385

.ZN vendor ,

386

.ZN model ,

387

.ZN hsync ,

388

and

389

.ZN vsync

390

fields point to dynamically allocated storage that should be freed

391

by the caller.

392

.SS "VIEWPORT FUNCTIONS"

393

The

394

.ZN XF86VidModeGetViewPort

395

and

396

.ZN XF86VidModeSetViewPort

397

functions can be used to, respectively, query and change the location

398

of the upper left corner of the viewport into the virtual screen.

399

.SS "OTHER FUNCTIONS"

400

The

401

.ZN XF86VidModeQueryVersion

402

function can be used to determine the version of the extension

403

built into the server.

404

.PP

405

The function

406

.ZN XF86VidModeQueryExtension

407

returns the lowest numbered error and event values

408

assigned to the extension.

409

.SH BUGS

410

The

411

XF86VidModeSetClientVersion,

412

XF86VidModeGetDotClocks,

413

XF86VidModeGetGamma,

414

XF86VidModeSetGamma,

415

XF86VidModeSetGammaRamp,

416

XF86VidModeGetGammaRamp,

417

XF86VidModeGetGammaRampSize,

418

and

419

XF86VidModeGetPermissions

420

functions need to be documented. In the meantime, check the source

421

code for information about how to use them.

422

.SH SEE ALSO

423

__xservername__(__appmansuffix__), __xconfigfile__(__filemansuffix__), XFlush(__libmansuffix__), XSetErrorHandler(__libmansuffix__), xvidtune(__appmansuffix__)

424

.SH AUTHORS

425

Kaleb Keithley, Jon Tombs, David Dawes, and Joe Moss

Older »