Daqarta
Data AcQuisition And Real-Time Analysis
Scope - Spectrum - Spectrogram - Signal Generator
Software for Windows
Science with your Sound Card!
The following is from the Daqarta Help system:

Features:

Oscilloscope

Spectrum Analyzer

8-Channel
Signal Generator

(Absolutely FREE!)

Spectrogram

Pitch Tracker

Pitch-to-MIDI

DaqMusiq Generator
(Free Music... Forever!)

Engine Simulator

LCR Meter

Remote Operation

DC Measurements

True RMS Voltmeter

Sound Level Meter

Frequency Counter
    Period
    Event
    Spectral Event

    Temperature
    Pressure
    MHz Frequencies

Data Logger

Waveform Averager

Histogram

Post-Stimulus Time
Histogram (PSTH)

THD Meter

IMD Meter

Precision Phase Meter

Pulse Meter

Macro System

Multi-Trace Arrays

Trigger Controls

Auto-Calibration

Spectral Peak Track

Spectrum Limit Testing

Direct-to-Disk Recording

Accessibility

Applications:

Frequency response

Distortion measurement

Speech and music

Microphone calibration

Loudspeaker test

Auditory phenomena

Musical instrument tuning

Animal sound

Evoked potentials

Rotating machinery

Automotive

Product test

Contact us about
your application!

Mouse and Miscellaneous Position Macros


Macro: Posn?

Posn? is a read-only macro that can read the current mouse cursor X or Y position, as well as the screen extents and other position information.

    Posn?X = X-position, pixels
    Posn?Y = Y-position
    Posn?W = Screen Width
    Posn?H = Screen Height

The above X and Y positions are in pixels, relative to 0,0 at the upper left screen corner.

If you want to use the mouse to set some variable V over a given range R, you can use the Width and Height to scale the X and Y values. V=R * Posn?X / Posn?W will set the value of V to 0 when the mouse cursor is at the left side of the screen, and to R when it is at the right side.

Similarly, H=R * Posn?Y / Posn?H will set H to 0 when the mouse cursor is at the top of the screen, and to R when it is at the bottom.

For example, the color function colr(Hue,Sat) accepts Hue values from 0 to 1791 and Sat values from -255 to +255. To use the horizontal mouse position to control Hue and the vertical position to control Sat for setting the color of (say) the Left Input trace, you can create a Task macro that includes:

    H=1791 * Posn?X/Posn?W
    S=255 - 510 * Posn?Y/Posn?H
    ColorNum#L=colr(H,S)

As the mouse moves left to right across the screen, H varies from 0 to 1791 and the color varies from red through the color spectrum, then from black through shades of gray to white.

As the mouse moves vertically, S is +255 at the top of the screen and -255 at the bottom. At the vertical center where S = 0, the colors are fully saturated. They become lighter when the mouse moves up, and darker when it moves down.


Alternatively, you can read the positions and dimensions in "dialog units" by using lowercase letters:

    Posn?x = X-position, dialog units
    Posn?y = Y-position, dialog units
    Posn?w = Daqarta client area width
    Posn?h = Daqarta client area height

In this case, the positions will be relative to 0,0 at the upper left corner of the Averager button on the main Daqarta toolbar. Posn?w and Posn?h will give the dialog units at the bottom right corner of the Daqarta client area.

Note that if the mouse is above or to the left of the Averager button, the Posn?x and Posn?y values may be negative. If the mouse is below or to the right of the Daqarta client area, the position values may exceed the Posn?w and Posn?h limits.


Besides screen positions, the following Posn? functions read miscellaneous values, discussed below:

    Posn?0 to Posn?9 Special integers
    Posn?c Most recent right-clicked Help topic
    Posn?D Display start absolute sample number
    Posn?d Display Trigger absolute sample
    Posn?S Samples used for triggered RMS
    Posn?I Input pointer position
    Posn?O Output pointer position
    Posn?F Pitch Track Frequency, Hz
    Posn?N Pitch Track MIDI Note number
    Posn?V Pitch Track peak magnitude
    Posn?v Pitch Track velocity
    Posn?P Pitch Track threshold event count
    Posn?M Pitch-to-MIDI acquired note count
    Posn?B Pitch-to-MIDI elapsed beats
    Posn?T Pitch-to-MIDI elapsed time
    Posn?t MIDI Record elapsed time
    Posn?f File Save or Open dialog status
    Posn?p Buffer peak index
    Posn?U Check for updated Daqarta version
    Posn?u Display update count
    Posn?R 32-bit rnd() random number
    Posn?r 32-bit seed for above
    Posn?s MIDI random seed
    Posn?Z Macro and MIDI 0/0 division handling

Posn?0 to Posn?9 read "special" integers that can also be set via Posn#0 to Posn#9. The "special" property is that they are shared with Pitch-to-MIDI performances, where they can be read by m0 to m9 and set by ?0 to ?9. Unlike the normal MIDI User Variable integers UA to UZ, these are not cleared at the start of a performance. This allows a macro or a full Custom Controls mini-app to modify the behavior of a MIDI setup before and during a performance.

Posn?c returns the most recent right-clicked Help topic number for any control. Unlikely to be of general use, though possibly for unusual macro Help application.

Posn?D reads the absolute sample number corresponding to the start of the data currently displayed. This is typically used with Macro Array Edge/Event/Trigger Detection (which returns values relative to the start of the array buffer) to determine absolute sample distance (and hence time) between events in buffers acquired at different times. Posn?D is used by the _Multi_Mtr_Task of the Multiple Meters mini-app to measure very low frequencies using this method.

Posn?d is the absolute sample number corresponding to the main Trigger of the current display. This may differ from the Posn?D value if Trigger Delay is active. In addition, the value may have a fractional part. This is due to interpolation to find the effective (fractional) sample number where the signal would have exactly hit the Trigger Level between integer sample numbers.

Posn?S is the number of samples used for RMS measurements when Trigger is active. It is the number of samples contained in the maximum number of triggered waveform cycles that will fit into the 1024-sample waveform display. This value may have a fractional part, due to the above-noted interpolation. Posn?S returns 1024 if the frequency is so low that one cycle exceeds 1024 samples (below 46.875 Hz at 48000 Hz sample rate.) Note that Posn?S is still valid even if the Voltmeter is not active, or is active but using some other mode. See Voltmeter RMS for more information, with a typical macro application under Macro Notes. Posn?S is also used by the _Multi_Mtr_Task of the Multiple Meters mini-app for RMS readings in Main Trig Sync mode.

Posn?I reads the current position of the ADC input pointer, and Posn?O reads the current position of the DAC output pointer. Both positions are in samples since the last Input or Generator start (or restart).

If Spectrum Cursor Peak and Track are active, as in Pitch Track operation, Posn?F returns the tracked frequency in Hz and Posn?N returns the corresponding MIDI note number.

Posn?V returns the magnitude of the tracked peak, scaled up such that 100% of full scale is 2^30. (To get percent of full scale, use Posn?V >> 30 * 100.) Posn?v returns the equivalent MIDI velocity scale factor 0-255.

Posn?P reads the count of Pitch Track above-threshold events found since it was toggled on. The count will be incremented on every trace update if the input is sustained.

Posn?M reads the count of MIDI notes accepted since the current Pitch-to-MIDI performance started. This count is only incremented when a new note goes on. It is not the same as MIDI notes played, which is typically less if Tempo is used.

Posn?B reads the number of beats since Pitch-to-MIDI started. This same value is also returned by PitchMIDI?B or by the MIDI Changes script mB option of the Changes Script Mouse and Miscellaneous Position command.

Posn?T reads the elapsed time in milliseconds since Pitch-to-MIDI started, updated on every trace update (10 msec default). This same value is returned by PitchMIDI?m and by the mT Changes script option.

Posn?t reads the elapsed time in milliseconds since MIDI Record was toggled on, also updated on every trace update. This same value is returned by MIDIrec?m and by the mt Changes script option.

Posn?f returns a status flag after a File Save or Open dialog exits: 1 = valid filename found, 0 = operation cancelled, or no valid filename found. This can be used by macros to exit gracefully if the user hits Cancel.

Posn?p reads the position (element index) of the most-recent positive peak found by the pkB({\i N}) or pkb(N) Peak Functions on a Buf0-Buf7 array. It likewise returns the peak index after macro array peak functions such as Buf0?p to find the most-positive value in Buf0, or Buf0?n to find the most-negative value.

Posn?U connects briefly to the Internet and returns 0 if your Daqarta version is the same as the latest release on the Daqarta Website, or else 1 if a newer version is available. If the Internet connection fails, it returns -1. This is the same Internet connection and test employed by Auto-Update Check, but takes no further action. See that topic for a discussion of firewall issues. Posn?U is not available on Win9x systems, and always returns -1.

Posn?u reads the number of main display updates since the start of the session. This value is incremented every time the display is updated. This includes normal Trace Update intervals, whether for a full waveform or Spectrum trace or a single vertical Spectrogram line. It also includes updates caused by moving the trace cursors, even if the display is Paused, as well as redraws due to PgUp/PgDn display magnification or other control changes.

Posn?R returns a 32-bit random integer using the same random number generator used by the rnd() math function. (Note that this is not the random generator used for rand(), nor the one used for MIDI.)

Posn?r returns the current seed of that 32-bit random number generator, which is also the most-recent random value returned by Posn?R. It will be used to compute the next value by Posn?R or rnd().

Unlike the above Posn? functions, Posn#r is a write-only function that sets the seed of the 32-bit random number generator. You can use this to repeat a sequence of random values by setting the same seed that it started with, previously saved via Posn?r. For example, you could use VarR=Posn?r to get the current seed, then perform some operations that use rnd() or Posn?R random values. When you want to repeat that same series, you would use Posn#r=VarR.

Note that a seed value of 0 is not allowed; if attempted a seed value of 1 is set instead.

Alternatively, if you want to end the Daqarta session before a long series is completed, you can use VarR=Posn?r before exiting Daqarta. The fixed-point variables Var0-Z are retained across sessions, so at the start of the next session you would first use Posn#r=VarR and then continue where you left off.

Posn?s returns the current seed of the main MIDI random generator ?(min,max), which is identical to but independent from the above 32-bit rnd() generator. Posn#s is a write function that sets this seed, in the same way that Posn#r sets the rnd() seed.

MIDI Changes scripts can use both random generators. The rnd() generator is invoked in a script via ?r(min,max). Macros can control running MIDI scripts by changing the random seeds.

Posn?Z reads and Posn#Z sets the state of the special 0/0 division handler for macros and MIDI scripts that use the / division operator, or the \ reverse division operator for Macro Array buffers. Your system's hardware Floating Point Unit returns a "negative infinity" error value for 0/0 operations, which could upset subsequent math or display operations. Daqarta intercepts this error value and replaces with 1.00 by default. You can control the 0/0 behavior by setting:

    Posn#Z=1   Return 1 for 0/0 (default)
    Posn#Z=0   Return 0 for 0/0
    Posn#Z=-1  Return hardware error (-infinity)

Note that this special handling only applies to 0/0 operations. If a positive or negative value is divided by 0 the result is positive or negative infinity, respectively. These are proper and expected results. If converted to fixed-point values or displayed they will be the largest supported signed values, typically +/-2^31.


Advanced Users:

You can control the constants used by the linear conguential generators (LCGs) for the rnd() math function and the MIDI random generators. These linear conguential generators have the form:

x[n] = (a * x[n-1] + c) mod 2^b

Here x[n] is the current random value, x[n-1] is the previous value or seed, a is a multiplier such that a mod 8 = 5, and c is an odd constant. b is the bit width of the random value, defaulting to 32. The default (and highly recommended) value for a is 2891336453, the optimal value for a 32-bit LCG found by L'Ecuyer (see Reference below). The default c constant is 1.

With the default values, the generator produces 2^32 random values before repeating. Other values that meet the above a mod 8 = 5 and c = odd requirements will also produce this repeat length, but may not appear as random in statistical tests. In general, any odd value of c should be fine, but a values are much more critical.

You can set other values for a, b, and c via the following write-only commands:

    Posn#A sets a multiplier for rnd()
    Posn#B sets b bit width for rnd()
    Posn#C sets c constant for rnd()
    Posn#a sets a multiplier for MIDI
    Posn#b sets b bit width for MIDI
    Posn#c sets c constant for MIDI

Note that these values are treated as integers by the linear congruential generator, but Daqarta doesn't accept unsigned integers above 2^31-1 = 2147483647. To enter higher values up to 2^32-1 = 4294967295, either use hexadecimal notation, or the equivalent negative integer. (To find the negative equivalent of a large positive value, subtract 2^32 from it.)

For example, the default a multiplier can be entered as Posn#A=hAC564B05, or as Posn#A=-1403630843.

The MIDI a, b and c values can also be set from a Changes script via ?a, ?b, and ?c, and the rnd() values by ?A, ?B, and ?C.

Default values are set automatically for both generators each time Daqarta starts. The MIDI generator is also reset at the start of each Pitch-To-MIDI performance. In addition, you can manually reset either generator by attempting to set multiplier a or bits b to zero (which would otherwise be invalid anyway.)


Reference:

"Tables of Linear Congruential Generators of Different Sizes and Good Lattice Structure", by Pierre L'Ecuyer, Mathematics of Computation, volume 68, number 225, January 1999, pp 249-260.


See also Macro Overview


GO:

Questions? Comments? Contact us!

We respond to ALL inquiries, typically within 24 hrs.
INTERSTELLAR RESEARCH:
Over 30 Years of Innovative Instrumentation
© Copyright 2007 - 2017 by Interstellar Research
All rights reserved