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
    Posn?L = Mouse wheeL count
    Posn?m = Mouse left button state (1=down, 0=up)

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

Posn?m only reads the mouse left button state when the mouse is in the main Daqarta window below the toolbar.

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.


Posn?L reads the mouse wheel counter, which counts the steps of the mouse wheel. Forward motion (up or away from the user) increases the count, while backward motion (down or toward the user) decreases the count or drives it negative. You can clear the count via Posn#L=0. You can use these commands to control any Daqarta parameter via a macro task or loop that reads the current Posn?L and computes a new value for the desired parameter.

You will probably want to clear the count before you begin the task or loop. Then while it is running you should test to see that the value has actually changed since the prior read, to avoid rapid "do-nothing" parameter changes. For example, you can initially set UA=Posn?L and then in the task or loop you read Posn?L and compare it to UA. If they are the same, do nothing; otherwise update UA with the new value, and also compute and set the new parameter:

    ;This runs inside a task or loop:
    UX=Posn?L
    IF.UX=UA
      ;< Compute and set new parameter here >
      UA=UX
    ENDIF.

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

    Posn?0 to Posn?9 Special integers
    Posn?i to Posn?o Special fixed-point
    Posn?A Read Active channels as bitmap
    Posn?C Read CPU Time Stamp Counter (TSC)
    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?z Most-recent FileName size

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.

Similarly, Posn?i to Posn?o read special fixed-point values with 32-bit integer and 32-bit fraction resolution. They are set via Posn#i to Posn#o. In MIDI scripts they are read by mi to mo and they are set by ?i to ?o. They share the same non-clearing status as the above special integers.

Please note that Posn?0 to Posn?9 and Posn?i to Posn?o are also not included in the Save/Restore Variables To/From Buffer Block operations Buf0#Bs=N and Buf0#Br=N


Posn?A reads the active channels as a bitmap:

    b0001    Left In
    b0010    Right In
    b0100    Left Out
    b1000    Right Out

The same channel mapping applies if a file is open, but in addition the File Source flag is set at bit 4:

    b10000   File Source Flag

Posn?C reads the CPU Time Stamp Counter, which is a running count of CPU clock ticks since power-up (or awakening from sleep or hibernation). It is a 64-bit value, which is returned as a fixed-point number with the most-significant 32 bits as the integer portion, and the least-significant as the fraction. In general, you should not use this for timing purposes; use the Timer or Time macros instead.


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.

Note that Posn?D will overflow Daqarta's 32-bit signed integer variable format (U0-UZ and Q0-QZ) or 64-bit fixed-point format (Var0-Z) at 2^31 samples, which is about 12.43 hours at the default sample rate of 48000 Hz. Be sure to use 80-bit floating-point variables A-Z for long durations.


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. Like Posn?D, you should use it with floating-point variables A-Z.


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). Note that these values will overflow Daqarta's 32-bit signed integer variable format (U0-UZ and Q0-QZ) or 64-bit fixed-point format (Var0-Z) at 2^31 samples, which is about 12.43 hours at the default sample rate of 48000 Hz. Be sure to use 80-bit floating-point variables A-Z for long durations.


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.


Posn?z reads the most-recent FileName size. FileName may be used with query (?) characters to obtain various portions of a file name that was selected or entered by the user from a File Open or Save dialog. Posn?z then returns the size of the indicated portion of the name:

  • FileName = Entire path, name, and extension.
  • FileName?p = Path only.
  • FileName?P = Path and name only.
  • FileName?n = Name only.
  • FileName?N = Name with extension.
  • FileName?E = Extension only, without period.

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 35 Years of Innovative Instrumentation
© Copyright 2007 - 2023 by Interstellar Research
All rights reserved