In file mydocsrc/mvl_macv.h:

class mvl_video_manager

A class for displaying 2-dimensional images either singly or in a movie sequence

Public

A: Informational Variables
1: Operating system and hardware information.
IML_LINT DisplayNumber
Keeps track of which monitor is used for display; 0, 1, etc.
IML_LINT HasGestalt
True if this MAC-OS version is new enough for Gestalt()
IML_LINT SystemOSVersion
Tells the MAC-OS version in hex. (e.g. 0x710 is 7.1.0)
IML_LINT SystemArchitecture
Tells what cpu architecture is used in this pc
IML_LINT CPUType
Tells the cpu type in more detail than SystemArchitecture
IML_LINT IsPowerPC
True if CPU is one of (601,603,604.... i.e. SystemArchitecture == 2)
IML_LINT FPUType
Tells what kind of FPU is present if SystemArchitecture == 1
IML_LINT QuickDrawVersion
Tells what version of QuickDraw is used on this computer
IML_LINT Has8BitQD
True if (QuickDrawVersion >= gestalt8BitQD) is true.
IML_LINT NewPaletteManagerPresent
True if (SystemOSVersion >= 0x605) is true.
IML_LINT DeviceIsColor
Seems archaic, but verifies that the monitor is a color one.
IML_LINT StackSize
Tells the current stack size, including after calling extend_stack().
2: Monitor specific information.
IML_LINT DacSize
The width of a D-to-A (DAC) converter slot in bits. Usually it's 8.
IML_LINT MaxDac
The the last DAC entry address: 2**DacSize - 1, where '**' denotes exponentiation.
IML_LINT LeftShift
Used for loading values into the system DAC; LeftShift = 16 - DacSize.
IML_LINT CLUTSize
How long is the clut; not necesarily the same as 2**DacSize (where '**' denotes exponentiation).
IML_LINT XResolution
Pixel resolution across the screen.
IML_LINT YResolution
Pixel resolution down the screen.
IML_LINT InitialPixelSize
Pixel depth (in bits) before we changed it to 8.
IML_LINT UsingAttenuator
This is actually supplied by the user, since the software does not know.
B: Behavioral Variables.
IML_LINT ExitOnError
Exit on various bad errors, if and when they occur.
IML_USINT StartCLUTSegment
Starting place for linearization procedure
IML_USINT CLUTSegmentLength
Number of CLUT entries to use in the linearization procedure
IML_DOUBLE MaxLuminance
Current max luminance.
IML_DOUBLE MinLuminance
Current min luminance.
IML_DOUBLE MeanLFraction
Current mean luminance as a fraction of the maximum range
IML_DOUBLE MeanLuminance
Current mean luminance
IML_DOUBLE MaxContrast
Current maximum contrast (determined by the CLUT entries) as a fraction of mean luminance.
C: Constructors.
mvl_video_manager (IML_USINT MaxImageSequences = 8, IML_USINT MaxBlitSequences = 64, IML_USINT MaxBlitGroups = 32, IML_ULINT ExitOnErr = TRUE)
There is only one constructor with all arguments having defaults
D: Initialization routines.
void initialize_screen (IML_SINT DispNumber, IML_SINT ThunderCardVideo=FALSE)
Tells the mac video manager about the display
IML_LINT set_dgp_calibration (const char * FileName=NULL)
This call trys to load display linearization information (DG Pelli's library format) from a file
void set_attenuator_red_steps ( IML_FLOAT RedSteps )
This call tells the video manager how many luminance steps the red gun provides relative to one step of the blue gun when using a resistive network for combining red, green and blue guns of your CRT
void set_mvl_calibration (IML_FLOAT B, IML_FLOAT G, IML_FLOAT MinL, IML_FLOAT MaxL)
This call suplies the video manager with linearization data as obtained from the linearization program supplied with this software
void set_mvl_calibration (polynomial IML_REF CalibrationInfo, IML_FLOAT MinL, IML_FLOAT MaxL)
This call suplies the video manager with linearization data as obtained from the linearization program supplied with this software
IML_DOUBLE get_min_luminance (void)
FYI -- Especially if calibration was loaded from a file.
IML_DOUBLE get_max_luminance (void)
FYI -- Especially if calibration was loaded from a file.
void use_dgp_calibration (void)
Tells the video manager to use DGP's linearization methods
void use_mvl_calibration (void)
Tells the video manager to use MVL gamma correction; this is the default (cf
void use_mvl_window_filling (IML_USINT Speed = 64)
Tells the video manager to use MVL style window filling
E: Color Lookup Table (CLUT) manipulation routines.
void set_default_clut_segment (IML_USINT StartC, IML_USINT CLength)
Set the two behavioral variables, StartCLUTSegment and CLUTSegmentLength
void linearize_clut (IML_DOUBLE MeanL, IML_DOUBLE MaxC)
Set the hardware CLUT to the requested mean luminance (MeanL) and maximum contrast (MaxC) using the linearization information from intialization calls
void linearize_clut (IML_DOUBLE MeanL, IML_DOUBLE MaxC, IML_USINT Start, IML_USINT Length)
Set the hardware CLUT to the requested mean luminance (MeanL) and maximum contrast (MaxC) using the linearization information previously defined in intialization calls
void set_clut_entry (IML_SINT Entry, IML_SINT R, IML_SINT G, IML_SINT B)
Set a single entry in the hardware CLUT to the requested (R,G,B) combination
void set_clut_entry (IML_SINT Entry, mvl_rgb IML_REF RGB)
Set a single entry in the hardware CLUT to the requested (R,G,B) combination
void identity_clut (IML_UBYTE RorGorB, IML_USINT StartCLUTEntry, IML_USINT Length, IML_FLOAT StartDacValue, IML_FLOAT DeltaDac)
Fill the hardware CLUT with an un-gamma-corrected, linear sequence of DAC values
mvl_clut IML_PTR get_clut_copy (void)
Get a copy of the current CLUT (that is, the one currently displayed by the video hardware)
void set_default_clut (mvl_clut IML_REF CLUT)
Load the given CLUT information into the video hardware and copy it into the default CLUT
void load_clut (mvl_clut IML_REF CLUT)
Load all entries from the given CLUT into the video hardware but DON'T copy it into the default CLUT
void load_clut_entry (mvl_clut IML_REF CLUT, IML_SINT Entry)
Load a single entry from the given CLUT into the video hardware but DON'T copy it into the default CLUT
F: Image storage and display-preparation routines.
void clear_window (void)
Fill the display window with a mean luminance value as described by the current calibration information
void fill_window_relative (IML_FLOAT Luminance)
Fill the display window with a luminance value as described by the calibration information
void fill_window_absolute (IML_SINT CLUT_Index)
Fill the display window with a "color" given in the requested CLUT entry
void draw_fixation_marker (mvl_screen_position IML_REF DestPos, IML_LINT Size)
Draw a fixation marker at the requested position, of the requested size, in pixels
IML_SINT store_image_sequence (iml_ubyte_image IML_REF Image)
Store one or more image frames so that they can be displayed quickly using DGP's blitting code
IML_SINT store_image_sequence (iml_byte_image IML_REF Image)
Same as above, but expects signed byte images
IML_SINT update_image_sequence (iml_ubyte_image IML_REF Image, IML_USINT ImSeqID)
Update the pixels of an image sequence previously stored with store_image_sequence()
void clear_image_sequences (void)
Clear out all previously stored image sequences
IML_SINT create_blit_sequence (IML_USINT ImSeqID, mvl_screen_position IML_REF DestPos, iml_imageframe_sequence IML_REF FrameSeq)
Create an internal blit sequence for use in showing a movie
void clear_blit_sequences (void)
Clear out all the blit sequences
IML_SINT add_to_group (IML_USINT BlitSeqID, IML_USINT GroupID=0)
Add a blit sequence to a target group that will be played together (simultaneously)
IML_SINT clear_group (IML_SINT GroupID = -1)
Clear out one or all blit sequence groups
G: Movie sequence and 2D image/movie-frame display routines.
IML_FLOAT play_blit_sequence (IML_USINT BlitSeqID)
Play the requested blit sequence as a movie using the current temporal window setup
IML_FLOAT play_blit_group (IML_SINT GroupID = -1)
Play all the blit sequences in the given group simultaneously
IML_SINT display_frame (IML_USINT ImSeqID, IML_USINT Frame, mvl_screen_position IML_REF DestPos)
Show a single frame from a previously stored image frame sequence
IML_SINT display_image ( iml_ubyte_image IML_REF Image, mvl_screen_position IML_REF DestPos)
Copy the requested image directly to the display without having to copy it to off screen memory and make a blit sequence
IML_SINT display_image ( iml_byte_image IML_REF Image, mvl_screen_position IML_REF DestPos)
Same as above, but for *signed* byte images
H: Easy methods for choosing image presentation locations.
IML_USINT get_display_array_size (IML_USINT XSize, IML_USINT YSize, IML_USINT Spacing=0)
Calculates the number of images what will fit on the display, given XSize, YSize, and Spacing
IML_USINT get_display_array_size (iml_image IML_REF Image, IML_USINT Spacing=0)
Same as above, but gets image XSize and YSize from the image passed in
mvl_screen_position get_grid_size (IML_USINT XSize, IML_USINT YSize, IML_USINT Spacing=0)
Just like the calls above, this call calculates the number of images what will fit on the display, given XSize, YSize, and Spacing
mvl_screen_position get_grid_size (iml_image IML_REF Image, IML_USINT Spacing=0)
Same as above, but gets image XSize and YSize from the image passed in
mvl_screen_position get_screen_position (IML_SINT ImageIndex, IML_USINT XSize, IML_USINT YSize, IML_USINT Spacing=0)
Calculate an mvl_screen_position that will place an image of the specified size into the requested location
mvl_screen_position get_screen_position (IML_SINT ImageIndex, iml_image IML_REF Image, IML_USINT Spacing=0)
Same as above, but gets image XSize and YSize from the image passed in
mvl_screen_position get_screen_position (mvl_screen_position & XY, IML_USINT XSize, IML_USINT YSize, IML_USINT Spacing=0)
Just like the calls above, this call calculates an mvl_screen_position that will place an image of the specified size into the requested location
mvl_screen_position get_screen_position (mvl_screen_position & XY, iml_image IML_REF Image, IML_USINT Spacing=0)
Same as above, but gets image XSize and YSize from the image passed in

Documentation

A class for displaying 2-dimensional images either singly or in a movie sequence. The class allows manipulation of the color lookup table (CLUT) and provides easy access to information about the operating system and the video characteristics.

An important requirment for image display in psychophysical experiments is fine control of pixel luminance. To this end the mvl_video_manager class provides two methods for CLUT linearization. First, you can use the linearization method provided for in Denis Pelli's VideoToolbox. All you need is the file created by that calibration program. That data includes information regarding your ISR video-attenuator, if you have one.

Alternatively, you can use the linearization method provided by this package. The method also allows for use of a resistive network (ISR Video Attenuator or otherwise) for increasing luminance resolution but requires neither a photometer nor a voltmeter. Instead the monitor-luminance and attenuator characteristics are measured psychophysically.

The MVL Linearization Method

Our task in linearization is to produce a sequence of DAC values (perhaps RGB, or reg/green/blue DAC-value triplets) that produce a linear change of perceived luminance on the target display with linear changes of pixel value. That is, we want to to have


Perceived_Luminance(Pixel_Value) = MinLuminance + Konstant*Pixel_Value

The relationship of the function that maps a video DAC value to a screen luminance in cathode ray tubes(CRT's)

L = f(DAC value)

is generally nonlinear. This is the function normally measured using a photometer. In practice we use the inverse of f(), call it g(), to compute the DAC value required for the requested luminance. The linearization method provided by this package g() takes the form

DAC value = g(LF)

where LF is a fraction of the luminance range. If a DAC value of 0 produces LMin, and a maximum dac value (that is, (2**DacBits-1), where ** denotes exponentiation) produces LMax, then LF = (L-LMin)/(LMax-LMin).

Historically this process (that is, use of g()) has been galled gamma correction because f() was often taken to be of the form alpha+beta*(L**gamma). This is not really adequate for good linearization of any monitor, so we adopt a form for g() of:


DAC value = exp(p)  

where exp(p) is the Natural Exponential function, p is a polynomial in ln(LF), and ln() is the Natural Logarithm. The nth order polynomial p has parameters {a0, a1, ... an}. A first order polynomial produces a two parameter a0*(L**(1/a1)). This is equivalent to the historical gamma function: Beta*L**Gamma where Beta=a0 and Gamma=(1/a1). Since a first order polynomial is not generally adequate for all hardware we allow higher order polynomials in our calibration.

The Attenuator Characteristics

Generally, the resistive network (e.g. Video Attenuator) produces a (linear) weighted sum of the voltages from the red, blue and green guns and the result is output onto the green channel:


Vgreen_out = Ar*Vred + Ag*Vgreen + Ab*Vblue 

where Ar, Ag, and Ab are constants that satisfy

Ar + Ag + Ab = 1.0

and where (at least, for the Video Attenuator)

Ab > Ag > Ar

For the Video Attenuator, Ar > Ab/256. Assuming this to be true for any attanuator used with this software, we can use the red gun (alone) to interpolate between luminances produced by integral values of the blue gun. To measure this, the calibration program included with this software finds the red gun dac value that makes

BlueDacValue + RedDacValue == BlueDacValue+Delta

true for some Delta. The number of red gun steps per blue step is all we need to know, assuming that the gains for each of the red, green and blue guns are independent. (This is unlikely, but the assumption works well enough.) This 'step-count' is used in the linearization process.
A: Informational Variables
These variables are intended to provide information to the knowledgable user. They are not protected, because the knowledgeable user knows that changing them is either useless, or a bad idea. :-) In other words, you can copy them or print them out, but don't change them.

1: Operating system and hardware information.

IML_LINT SystemArchitecture
Tells what cpu architecture is used in this pc. Possible MAC-OS macro names and integer values are:

gestalt68k:     1  -- Motorola MC68k 
gestaltPowerPC: 2  -- IBM PowerPC

IML_LINT CPUType
Tells the cpu type in more detail than SystemArchitecture. Possible MAC-OS macro names and integer values are:

gestaltCPU68000: 1	-- Various 68k CPUs...
gestaltCPU68010: 2
gestaltCPU68020: 3
gestaltCPU68030: 4
gestaltCPU68040: 5
gestaltCPU601:   0x101,		-- IBM 601, etc.
gestaltCPU603:   0x103,
gestaltCPU604:   0x104

IML_LINT FPUType
Tells what kind of FPU is present if SystemArchitecture == 1. Possible MAC-OS macro names and integer values are:

gestaltNoFPU:    0  -- no FPU 
gestalt68881:    1  -- 68881 FPU 
gestalt68882:    2  -- 68882 FPU 
gestalt68040FPU: 3  -- 68040 built-in FPU

IML_LINT QuickDrawVersion
Tells what version of QuickDraw is used on this computer. Possible MAC-OS macro names and integer values are:

gestaltOriginalQD: 0x000 -- original 1-bit QD 
gestalt8BitQD:     0x100 -- 8-bit color QD 
gestalt32BitQD:    0x200 -- 32-bit color QD 
gestalt32BitQD11:  0x201 -- 32-bit color QDv1.1 
gestalt32BitQD12:  0x220 -- 32-bit color QDv1.2 
gestalt32BitQD13:  0x230 -- 32-bit color QDv1.3 

2: Monitor specific information.
This information gives details about using the specified monitor in the 256 color video mode. These are set when the user calls initalize_screen().

B: Behavioral Variables.
These variables are set by the user in order to change the way the images are displayed, or what to do in case of errors. *DONT* change these yourself! Go through the provided system calls.

IML_USINT StartCLUTSegment
Starting place for linearization procedure. Together with CLUTSegmentLength this allows you to store more than one linearized sequence, or to use all or only a segment of the CLUT for a linear sequence.

IML_USINT CLUTSegmentLength
Number of CLUT entries to use in the linearization procedure. Together with StartCLUTSegment this allows you to store more than one linearized sequence, or to use all or only a segment of the CLUT for a linear sequence.

IML_DOUBLE MeanLuminance
Current mean luminance. This is equal to
MinLuminance + MeanLFraction*(MaxLuminance+MinLuminance).

C: Constructors.

mvl_video_manager(IML_USINT MaxImageSequences = 8, IML_USINT MaxBlitSequences = 64, IML_USINT MaxBlitGroups = 32, IML_ULINT ExitOnErr = TRUE)
There is only one constructor with all arguments having defaults. The MaxImageSequences, MaxBlitSequences, and MaxBlitGroups are currently required because I was lazy in the design phase. :-) Later on I plan to make the data structures whose sizes depend on these inputs dynamically allocated. Then the only required input will be whether to ExitOnErr.

D: Initialization routines.

void initialize_screen(IML_SINT DispNumber, IML_SINT ThunderCardVideo=FALSE)
Tells the mac video manager about the display. The input arguments are which video display to use, whether the video hardware is a Radius PCI Thunder30 card.

IML_LINT set_dgp_calibration(const char * FileName=NULL)
This call trys to load display linearization information (DG Pelli's library format) from a file. A NULL input represents a request for a default file. You take your chances with that, since I don't know if the compiled-in information is any good for a particular display.

void set_attenuator_red_steps( IML_FLOAT RedSteps )
This call tells the video manager how many luminance steps the red gun provides relative to one step of the blue gun when using a resistive network for combining red, green and blue guns of your CRT. If RedSteps == 0.0 indicates that an attenuator is not used. If RedSteps is > 1.0 then linear cluts are calculated assuming that the blue and red guns are combined using the attenuator, and that the red gun provides the least significant (small step) bits. The Attenuator Characteristics

Generally, the resistive network (e.g. ISR Video Attenuator) produces a linear, weighted sum of the voltages from the red, blue and green CRT guns, and the resulting voltage is output to the green channel:


Vgreen_out = Ar*Vred + Ag*Vgreen + Ab*Vblue 

where Ar, Ag, and Ab are constants that satisfy

Ar + Ag + Ab ~ 1.0

and where (at least, for the Video Attenuator)

Ab > Ag > Ar

For the Video Attenuator, Ar > Ab/(MaxDac+1). Assuming this to be true for any attanuator used with this software, we can use the red gun (alone) to interpolate between luminances produced by integral values of the blue gun. To measure this, the calibration program included with this software finds the red gun dac value that makes

BlueDacValue + RedDacValue == BlueDacValue+Delta

true for some Delta. The number of red gun steps per blue step is all we need to know, assuming that the gain for each of the red, green and blue guns are independent. (This is unlikely, but the assumption works well enough.) This 'step-count' is used in the linearization process.

void set_mvl_calibration(IML_FLOAT B, IML_FLOAT G, IML_FLOAT MinL, IML_FLOAT MaxL)
This call suplies the video manager with linearization data as obtained from the linearization program supplied with this software. The model in this case is

DacValue = B*L**(1/G)

where '**' denotes exponentiation. B should usually be set to (or be close to) MaxDac. MinL and MaxL are the minimum and maximum luminance values as measured with a photometer. MinL and MaxL values are not necessary for the linearization. L is a luminance as a fraction of maximum; L=0.0 at MinL and L=1.0 at MaxL.

void set_mvl_calibration(polynomial IML_REF CalibrationInfo, IML_FLOAT MinL, IML_FLOAT MaxL)
This call suplies the video manager with linearization data as obtained from the linearization program supplied with this software. The model in this case is

DAC value = exp(p)  

where exp(p) is the Natural Exponential function, p is a polynomial in ln(LF), and ln() is the Natural Logarithm. The nth order polynomial p has parameters {a0, a1, ... an}. MinL and MaxL are the minimum and maximum luminance values as measured with a photometer. L is a luminance as a fraction of maximum; L=0.0 at MinL and L=1.0 at MaxL. Accurate values of MinL and MaxL are not necessary for linearization, only for your publications ;).

void use_dgp_calibration(void)
Tells the video manager to use DGP's linearization methods. 'DGP' is D.G. Pelli (cf. use_mvl_calibration()). You should also call set_dgp_calibration() with the file name created by DGP's calibration program before creating a linear CLUT.

void use_mvl_calibration(void)
Tells the video manager to use MVL gamma correction; this is the default (cf. use_dgp_calibration()). You should also call one of the set_mvl_calibration() before creating a linear CLUT.

void use_mvl_window_filling(IML_USINT Speed = 64)
Tells the video manager to use MVL style window filling. This is necessary only in the cases where you would like to fill the window with CLUT values of 0 or MaxDac. This occurs because, according to Apple's manuals on the Color Manager, the Color Manager is not normally guaranteed to honor that palette color N will be stored as N in each pixel. For example, the calls
PmBackColor( CLUT_Entry );

EraseRect( &Rect );
with CLUT_Entry value of 0 or 255 (for 8-bit DAC video hardware) will often fail because the Color manager strongly objects to meddling with the first and last CLUT entries. If you do this after filling the CLUT with a linearized sequence, the Color Manager will likely re-fill the first and last entries with white and black (full and no luminance) respectively.

THIS IS A ROYAL PAIN.

So, this method does window filling (clearing) using a pre-set image of size Speed x Speed pixels. :-)

E: Color Lookup Table (CLUT) manipulation routines.

void set_default_clut_segment(IML_USINT StartC, IML_USINT CLength)
Set the two behavioral variables, StartCLUTSegment and CLUTSegmentLength. Their values are used when loading the hardware CLUT with a linearized sequence by a call to set_display_CLUT(IML_DOUBLE MeanL, IML_DOUBLE MaxC).

void linearize_clut(IML_DOUBLE MeanL, IML_DOUBLE MaxC)
Set the hardware CLUT to the requested mean luminance (MeanL) and maximum contrast (MaxC) using the linearization information from intialization calls. The linearized sequence is stored in the CLUT segment given by two behavioral variables, StartCLUTSegment and CLUTSegmentLength. These are set with set_default_clut_segment(). The linearize_clut() call stores a copy for use in movie (blit sequence) displays.

void linearize_clut(IML_DOUBLE MeanL, IML_DOUBLE MaxC, IML_USINT Start, IML_USINT Length)
Set the hardware CLUT to the requested mean luminance (MeanL) and maximum contrast (MaxC) using the linearization information previously defined in intialization calls. The linearized sequence is stored in the CLUT segment given by Start and Length. The linearize_clut() call stores a copy for use in movie (blit sequence) displays.

void set_clut_entry(IML_SINT Entry, IML_SINT R, IML_SINT G, IML_SINT B)
Set a single entry in the hardware CLUT to the requested (R,G,B) combination. The entry is also stored in the default CLUT and will be used in movie sequences.

void set_clut_entry(IML_SINT Entry, mvl_rgb IML_REF RGB)
Set a single entry in the hardware CLUT to the requested (R,G,B) combination. The entry is also stored in the default CLUT and will be used in movie sequences.

void identity_clut(IML_UBYTE RorGorB, IML_USINT StartCLUTEntry, IML_USINT Length, IML_FLOAT StartDacValue, IML_FLOAT DeltaDac)
Fill the hardware CLUT with an un-gamma-corrected, linear sequence of DAC values. The sequence is stored in the CLUT segment given by Start and Length. This call also stores a copy for use in movie (blit sequence) displays. The DAC values stored in the CLUT are

(short int)(0.5 + StartDac + (CLUTEntry-StartCLUT)*DeltaDac)

for CLUTEntry going from StartCLUT to StartCLUT+CLUTLength-1. The values are stored in any combination of red, green and blue DAC entries as designated by the RorGorB parameter. RorGorB should be one of

mvl_video_manager::RED_GUN
mvl_video_manager::GREEN_GUN
mvl_video_manager::BLUE_GUN
mvl_video_manager::ALL_GUNS

or any bit-wise OR'ed combination. ALL_GUNS is equivalent to

mvl_video_manager::RED_GUN | mvl_video_manager::GREEN_GUN | mvl_video_manager::BLUE_GUN

mvl_clut IML_PTR get_clut_copy(void)
Get a copy of the current CLUT (that is, the one currently displayed by the video hardware). The call returns a pointer but I recommend attaching it to a reference, that is

mvl_clut & CLUT_Reference = *MacVideo.get_clut_copy();

Then you can alter the copy of the clut to your heart's content, and load it back into the hardware later. But remember to delete the CLUT copy when you're done! That is:

delete &CLUT_Reference;

void set_default_clut(mvl_clut IML_REF CLUT)
Load the given CLUT information into the video hardware and copy it into the default CLUT. The default CLUT is used in movie (blit sequence) displays.

void load_clut(mvl_clut IML_REF CLUT)
Load all entries from the given CLUT into the video hardware but DON'T copy it into the default CLUT. Movie (blit sequence) displays will use the current default instead.

void load_clut_entry(mvl_clut IML_REF CLUT, IML_SINT Entry)
Load a single entry from the given CLUT into the video hardware but DON'T copy it into the default CLUT. Movie (blit sequence) displays will use the current default instead

F: Image storage and display-preparation routines.

void fill_window_relative(IML_FLOAT Luminance)
Fill the display window with a luminance value as described by the calibration information. Luminance is in the range 0.0 to 1.0 and produces a luminance of

MinLuminance + Luminance*(MaxLuminance-MinLuminance).

void fill_window_absolute(IML_SINT CLUT_Index)
Fill the display window with a "color" given in the requested CLUT entry. CLUT_Index is restricted to the range from 0 to CLUTSize-1.

IML_SINT store_image_sequence(iml_ubyte_image IML_REF Image)
Store one or more image frames so that they can be displayed quickly using DGP's blitting code. Images are stored in off-screen graphics memory. The memory type is assumed to be unsigned byte.
Returns:
On successful completion the function returns an image sequence identity. The identity is used in other function calls, such as create_blit_sequence() or display_frame(). If the request could not be completed for some reason, an error message is printed to the console window and a value of -1 is returned.

IML_SINT update_image_sequence(iml_ubyte_image IML_REF Image, IML_USINT ImSeqID)
Update the pixels of an image sequence previously stored with store_image_sequence(). The memory type is assumed to be unsigned byte.
Returns:
On successful completion the function returns the image sequence identity passed in. If the request could not be completed for some reason, an error message is printed to the console window and a value of -1 is returned.

IML_SINT create_blit_sequence(IML_USINT ImSeqID, mvl_screen_position IML_REF DestPos, iml_imageframe_sequence IML_REF FrameSeq)
Create an internal blit sequence for use in showing a movie. ImSeqID is the value returned from store_image_sequence(). FrameSeq is the iml_imageframe_sequence object which dictates the index sequence of image frames to blit.
Returns:
On successful completion the function returns a blit sequence identity. The identity is used in other function calls, such as add_to_group() or play_blit_sequence(). If the request could not be completed for some reason, an error message is printed to the console and a value of -1 is returned.

void clear_blit_sequences(void)
Clear out all the blit sequences. This sets the sequence count to zero and invalidates any previously held blit sequence ID's.

IML_SINT add_to_group(IML_USINT BlitSeqID, IML_USINT GroupID=0)
Add a blit sequence to a target group that will be played together (simultaneously). That is, all blit sequences in a blit-group will be played in frame synchronization. Note that if portions of the image sequences overlap spatially, the overlap region will show the image added most recently to the group. GroupID defaults to group identity zero if no group identity is supplied.
Returns:
On successful completion the function returns TRUE. If the request could not be completed for some reason, an error message is printed to the console and FALSE is returned.

IML_SINT clear_group(IML_SINT GroupID = -1)
Clear out one or all blit sequence groups. This invalidates the previously held group ID(s). Passing in a negative number requests clearing of all groups.
Returns:
On successful completion the function returns TRUE. If the request could not be completed for some reason, an error message is printed to the console and FALSE is returned. GroupID defaults to group identity -1 if no group identity is supplied. A negative-valued group identity requests clearing of all groups.

G: Movie sequence and 2D image/movie-frame display routines.

IML_FLOAT play_blit_sequence(IML_USINT BlitSeqID)
Play the requested blit sequence as a movie using the current temporal window setup. BlitSeqID is the value returned by create_blit_sequence(). Use the return value to check that video synchronization is working.
Returns:
On successful completion the function returns the total playing time for the blit sequence, in seconds. If the request could not be completed for some reason, an error message is printed to the console and a value of 0.0 seconds is returned.

IML_FLOAT play_blit_group(IML_SINT GroupID = -1)
Play all the blit sequences in the given group simultaneously. The return value is the playing time in seconds so you can make sure the frame rate was right.

IML_SINT display_frame(IML_USINT ImSeqID, IML_USINT Frame, mvl_screen_position IML_REF DestPos)
Show a single frame from a previously stored image frame sequence. ImSeqID is the value returned from store_image_sequence(), Frame is the frame number (zero to FrameCount-1) and DestPos indicates the position in which to place the upper left corner of the frame. GroupID defaults to group identity -1 if no group identity is supplied. A negative-valued group identity requests playing of all groups, hence all blit sequences, simultaneously. Blit sequence identities that occur multiple times will be played multiple times.

IML_SINT display_image( iml_ubyte_image IML_REF Image, mvl_screen_position IML_REF DestPos)
Copy the requested image directly to the display without having to copy it to off screen memory and make a blit sequence. There is no guarantee of timing or syncing to CLUT loading with this call. Image is assumed to be unsigned byte.
Returns:
On successful completion the function returns TRUE. If the request could not be completed for some reason, an error message is printed to the console and FALSE is returned.

H: Easy methods for choosing image presentation locations.

IML_USINT get_display_array_size(IML_USINT XSize, IML_USINT YSize, IML_USINT Spacing=0)
Calculates the number of images what will fit on the display, given XSize, YSize, and Spacing. For a 400x400 display, for example, with XSize=100, Ysize=100, and Spacing=0, we have a 4x4 array of image positions, or an array size of 16.

mvl_screen_position get_grid_size(IML_USINT XSize, IML_USINT YSize, IML_USINT Spacing=0)
Just like the calls above, this call calculates the number of images what will fit on the display, given XSize, YSize, and Spacing. The difference is that the screen space is treated as a two-dimensional array rather than as a linear array. For a 400x400 display, for example, with XSize=100, Ysize=100, and Spacing=0, we have a 4x4 array of image positions, or an array size of 16.

mvl_screen_position get_screen_position(IML_SINT ImageIndex, IML_USINT XSize, IML_USINT YSize, IML_USINT Spacing=0)
Calculate an mvl_screen_position that will place an image of the specified size into the requested location. XSize, YSize and Spacing together with the display resolution (see XResolution, YResolution variables) determine a sequence of positions on the display in an array format. For a 400x400 display, for example, with XSize=100, Ysize=100, and Spacing=0, we have a 4x4 array of image positions. For a 400x400 display with XSize=100, Ysize=100, and Spacing=10, we only have a 3x3 array of image positions with some leftover space. ImageIndex is an integer index into the array and is in the range [0,rows*cols-1]. Position value increments from left to right, top to bottom. For example, in a 3x3 image matrix positions are designated by:

 
0   1    2
3   4    5
6   7    8
The second method allows for special positions on the display to be selected. ImageIndex can be passed the values:
mvl_video_manager::CENTER
mvl_video_manager::UPPER_LEFT
mvl_video_manager::UPPER_RIGHT
mvl_video_manager::LOWER_LEFT
mvl_video_manager::LOWER_RIGHT
This selects the obvious centered or justified image positions.

mvl_screen_position get_screen_position(mvl_screen_position & XY, IML_USINT XSize, IML_USINT YSize, IML_USINT Spacing=0)
Just like the calls above, this call calculates an mvl_screen_position that will place an image of the specified size into the requested location. The difference is that the screen space is treated as a two-dimensional array rather than as a linear array. XY and Spacing together with the display resolution (see XResolution, YResolution variables) determine an array of positions on the display. For a 400x400 display, for example, and XSize=100, Ysize=100, and Spacing=0, we have a 4x4 array of image positions. For a 400x400 display with XSize=100, Ysize=100, and Spacing=10, we have a 3x3 array of image positions with some leftover space. XY is a 2-dimensional index into the array and is in the range [0,cols-1; 0,rows-1]. Position value increments from left to right, top to bottom. For example, in a 3x3 image matrix, positions are designated by:

 
0,0   0,1    0,2
1,0   1,2    1,2
2,0   2,1    2,2


This class has no child classes.

alphabetic index hierarchy of classes


generated by doc++