Vertical Retrace Interfaces. More...

#include <MacTypes.h>
#include <OSUtils.h>

Data Structures
struct	VBLTask

Macros
#define	NewVBLUPP(userRoutine)

#define	DisposeVBLUPP(userUPP) DisposeRoutineDescriptor(userUPP)

#define	InvokeVBLUPP(vblTaskPtr, userUPP) CALL_ONE_PARAMETER_UPP((userUPP), uppVBLProcInfo, (vblTaskPtr))

#define	NewVBLProc(userRoutine) NewVBLUPP(userRoutine)

#define	CallVBLProc(userRoutine, vblTaskPtr) InvokeVBLUPP(vblTaskPtr, userRoutine)

Typedefs
typedef struct VBLTask	VBLTask

typedef VBLTask *	VBLTaskPtr

Enumerations
enum	{ uppVBLProcInfo = 0x00009802 }

Functions
typedef	CALLBACK_API_REGISTER68K (void, VBLProcPtr,(VBLTaskPtr vblTaskPtr))

typedef	REGISTER_UPP_TYPE (VBLProcPtr) VBLUPP

VBLUPP	NewVBLUPP (VBLProcPtr userRoutine)

void	DisposeVBLUPP (VBLUPP userUPP)

void	InvokeVBLUPP (VBLTaskPtr vblTaskPtr, VBLUPP userUPP)

	while (qep !=0)

OSErr	SlotVInstall (QElemPtr vblBlockPtr, short theSlot)

OSErr	SlotVRemove (QElemPtr vblBlockPtr, short theSlot)

OSErr	AttachVBL (short theSlot)

OSErr	DoVBLTask (short theSlot)

OSErr	VInstall (QElemPtr vblTaskPtr)

OSErr	VRemove (QElemPtr vblTaskPtr)

Variables
</pre > *par	Copyright

Detailed Description

Vertical Retrace Interfaces.

Introduced In: System 7.5

Avaliable From: Universal Interfaces 3.4.1

Copyright: © 1985-2001 by Apple Computer, Inc., all rights reserved

For bug reports, consult the following page on the World Wide Web:

http://developer.apple.com/bugreporter/

Macro Definition Documentation

◆ NewVBLUPP

#define NewVBLUPP ( userRoutine )

Value:

(VBLUPP) NewRoutineDescriptor((ProcPtr)(userRoutine), uppVBLProcInfo, \

GetCurrentArchitecture())

NewRoutineDescriptor

UniversalProcPtr NewRoutineDescriptor(ProcPtr theProc, ProcInfoType theProcInfo, ISAType theISA)

Function Documentation

◆ AttachVBL()

OSErr AttachVBL ( short theSlot )

\brief Make specified slot the primary video slot

<pre>AttachVBL makes theSlot the primary video slot, allowing correct cursor

updating. theSlotis the slot number of the slot to be made the primary video slot. You can use the Slot Manager routine SGetSRsrc to index through all the slots on a particular machine.

Returns

an Error Code indicating success or failure of the function. It will
be one of:
noErr(0) no error
slotNumErr (-360) Invalid slot number

Copyright: THINK Reference © 1991-1992 Symantec Corporation

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: not available

Mac OS X: not available

◆ DisposeVBLUPP()

void DisposeVBLUPP ( VBLUPP userUPP )

DisposeVBLUPP()

Non-Carbon CFM: available as macro/inline

Carbon Lib: not available

Mac OS X: not available

◆ DoVBLTask()

OSErr DoVBLTask ( short theSlot )

\brief Execute VBL tasks in the queue for a specified slot

<pre>DoVBLTask causes any VBL tasks in the queue for a specified slot to be

executed. If the specified slot is the primary video slot, the position of the cursor will also be updated. theSlotis the slot number of the slot whose tasks should be executed. You can use the Slot Manager routine SGetSRsrc to index through all the slots on a particular machine.

Returns

an Error Code indicating success or failure of the function. It will
be one of:
noErr(0) no error
slotNumErr (-360) Invalid slot number

Note

Instead of maintaining a single verticle retrace queue, the
Vertical Retrace Manager maintains a separate queue for each video
device; associated with that queue is the rate at which the device's vertical
retrace interrupt occurs. When interrupts occur for a particular video
slot, the Vertical Retrace Manager executes any tasks in the queue for
that slot.

Copyright: THINK Reference © 1991-1992 Symantec Corporation

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: not available

Mac OS X: not available

◆ InvokeVBLUPP()

void InvokeVBLUPP	(	VBLTaskPtr	vblTaskPtr,
		VBLUPP	userUPP
	)

InvokeVBLUPP()

Non-Carbon CFM: available as macro/inline

Carbon Lib: not available

Mac OS X: not available

◆ NewVBLUPP()

VBLUPP NewVBLUPP ( VBLProcPtr userRoutine )

NewVBLUPP()

Non-Carbon CFM: available as macro/inline

Carbon Lib: not available

Mac OS X: not available

◆ SlotVInstall()

OSErr SlotVInstall	(	QElemPtr	vblBlockPtr,
		short	theSlot
	)

\brief Install vertical retrace interrupt task for a slot

<pre>SlotVInstall sets up to perform a task periodically. It installs an element

into the vertical retrace task queue of a particular slot. The task will be executed whenever that device's vertical retrace interrupt occurs. vblTaskPtr is the address of a 14-byte VBLTask structure. You must initialize the fields of the structure before making the call. theSlotis the slot number of the slot whose queue the task should be installed in. You can use the Slot Manager routine SGetSRsrc to index through all the slots on a particular machine.

Returns

an error return code indicating success or failure of the function. It
will be one of:
noErr(0) No error
vTypErr (-2) Invalid queue element
slotNumErr (-360) Invalid slot number

Note

Instead of maintaining a single vertical retrace queue, the
Vertical Retrace Manager maintains a separate queue for each video
device; associated with that queue is the rate at which the device's vertical
retrace interrupt occurs. When interrupts occur for a particular video
slot, the Vertical Retrace Manager executes any tasks in the queue for
that slot.
See VInstall for more information on writing tasks that need to execute
periodically and a code example which demonstrates the installation of a VBL
Task.

Copyright: THINK Reference © 1991-1992 Symantec Corporation

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: not available

Mac OS X: not available

◆ SlotVRemove()

OSErr SlotVRemove	(	QElemPtr	vblBlockPtr,
		short	theSlot
	)

\brief Remove vertical retrace interrupt task for a slot

<pre>SlotVRemove removes a previously-installed vertical retrace task from the

VBL queue for a particular slot and stops the task from being executed on subsequent retrace interrupts. vblTaskPtr is the address of a 14-byte VBLTask structure you installed previously via SlotVInstall . theSlotis the slot number of the slot whose queue the task should be removed from. You can use the Slot Manager routine SGetSRsrc to index through all the slots on a particular machine.

Returns

an Error Code indicating success or failure of the function. It will
be one of:
noErr(0) no error
qErr(-1) Invalid queue element
slotNumErr (-360) Invalid slot number

Note

Instead of maintaining a single vertical retrace queue, the
Vertical Retrace Manager maintains a separate queue for each video
device; associated with that queue is the rate at which the device's vertical
retrace interrupt occurs. When interrupts occur for a particular video
slot, the Vertical Retrace Manager executes any tasks in the queue for
that slot.
It is probably NOT wise to remove tasks you did not install.

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: not available

Mac OS X: not available

◆ VInstall()

OSErr VInstall ( QElemPtr vblTaskPtr )

\brief Install vertical retrace interrupt task

<pre>VInstall sets up to perform a task periodically. It installs an element into

the vertical retrace task queue that will be executed as often as 60 times per second. vblTaskPtr is the address of a 14-byte VBLTask structure. You must initialize the fields of the structure before making the call.

Returns

an error return code indicating success or failure of the function. It
will be one of:
noErr(0) No error
vTypErr (-2) VBLTask.qType must be vType

Note

The VBL (Vertical BLanking) interrupt occurs 60.15 times per second.
Orginally, on the Macintosh Plus, this corresponded to the period when the
video display beam was sweeping back up to the top of the screen after each
refresh of the screen image. This 1/60-th second interval is often called a
"tick" and occurs once every 16.66 ms.
With the advent of slots, a variety of screens are available, each with a
potentially vertical retrace period. A slot-specific version of VInstall ,
SlotVInstall is now available. You should use SlotVInstall if you are
trying to synchronize the execution of a task with the refresh rate of a
particular device. VInstall is still useful as a way of performing periodic
tasks based on ticks, though. A special system-generated interrupt that
occurs 60.15 times per second handle the execution of tasks installed via
VInstall .
The system initially installs its own set of VBL tasks, including code to
move the mouse cursor, post disk-insert events, and the task that updates
the Ticks variable. (Note that if you wait until this variable changes, and
then take action quickly, you can draw smooth animation on the screen).
Before calling VInstall , you must prepare all fields of the VBLTask
structure except for the qLink field:
qType Set this to vType (defined as 1 in OSUtil.h)
vblAddr Address of the routine to be executed.
vblCount Number of 1/60-th second (16.66ms) intervals to pass
between calls. ( Note: This gets decremented to 0 before your
VBL task gets called. If you want to get another timeslice, you
must set this back each time.)
vblPhase Ticks to skip before installing this task (usually 0). This is
needed if you install several tasks and wish them to take place at
different ticks (to avoid overloading the system).
The code of the task is executed at interrupt time , and so must be

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: not available

Mac OS X: not available

◆ VRemove()

OSErr VRemove ( QElemPtr vblTaskPtr )

\brief Remove vertical retrace interrupt task

<pre>VRemove removes a previously-installed vertical retrace task from the VBL

queue and stops the task from being executed on subsequent retrace interrupts. vblTaskPtr is the address of a 14-byte VBLTask structure you installed previously via VInstall .

Returns

an Error Code indicating success or failure of the function. It will
be one of:
noErr(0) no error
qErr(-1) No such task exists
vTypErr (-2) VBLTask.qType must be vType

Note

It is probably NOT wise to remove tasks you did not install.

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: not available

Mac OS X: not available

◆ while()

while ( qep ! = 0 )

\brief Get the address of the VBL queue header

<pre>Use GetVBLQHdr if you want to examine the queue of vertical retrace tasks.

Returns

a 32-bit QHdrPtr (the address of a 10-byte QHdr structure). The
qHead field of that structure points to a VBL queue element (a
VBLTask structure).

Note

C programmers may prefer to access the global variable VBLQueue (at
0x0160).
Apple tells us that bit 6 of the VBLTask.qFlags is set if any of the VBL tasks
are currently executing. Thus:
VBLTask *qep;
printf( "a VBL task %s executing\n",
(VBLQueue .qHead & 0x40) ? "IS" : "IS NOT");
qep = (VBLTask *)VBLQueue .qHead; /* get global variable

Data Structures

Macros

Typedefs

Enumerations

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ NewVBLUPP

Function Documentation

◆ AttachVBL()

◆ DisposeVBLUPP()

◆ DoVBLTask()

◆ InvokeVBLUPP()

◆ NewVBLUPP()

◆ SlotVInstall()

◆ SlotVRemove()

◆ VInstall()

◆ VRemove()

◆ while()