-
Notifications
You must be signed in to change notification settings - Fork 130
/
VERSIONS
4262 lines (3995 loc) · 188 KB
/
VERSIONS
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
------------------
ChucK VERSIONS log
------------------
1.5.3.3
=======
***************** new language feature ***************
- (added) chuck @import system for .ck and .chug files
- for language specification and examples regarding @import, see:
***************************************************
https://chuck.stanford.edu/doc/language/import.html
***************************************************
- the @import mechanism imports classes and operator overloads from another .ck file, or from a
chugin; it is designed to faciliate creating, using, and distributing multi-file programs
and libraries
- @import SYNTAX:
@import "Foo.ck" // import Foo.ck
@import "Bar.chug" // import Bar.chug chugin
@import { "AAA.ck", "BBB.chug", "CCC" } // multiple imports on one line
@import "/Users/ge/chuck/examples/import/foo-user.ck" // absolute path
@import "../dir/Blarg.ck" // relative path
@import "Foo" // can use implicit filename; @import will search and match for
.ck, .chug, and .chug.wasm, in each directory in the chugin/import search paths
- @import picks up all (and only) *public* definitions (classes and operator overloads);
-- this implies that @import will only add new definitions to the type system, but will
NEVER automatically run any code; client code must first instantiate class or use an operator
to execute the contents of imported files
-- this behavior makes it possible to write unit test code for public classes in the same
file in which it is defined; any code outside of public class/operator definition will NOT be
type-checked or run (this code will only scanned for syntax)
- @import is resolved at compile-time, before the rest of the file is evaluated; this makes it
possible for a .ck file to @import one of more files AND use their contents from the same
.ck file (this capability make @import more powerful than Machine.add() for dependency
management; as noted above, @import will only )
- @import can work recursively; can @import files that @import other files
- @import has built-in cycle-detection; if an @import cycle is detected, a compiler error
will be issued and that compilation will be failed
- (updated behavior) .ck files found in chugin/import search paths (e.g., ~/.chuck/lib) NO
LONGER automatically loads; instead these now must be explicitly @imported to be used (FYI
just the file name will suffice, assuming there are no filename conflicts elsewhere in the
import paths)
******************************************************
- (fixed) specific internal UGen connection error now handled without exiting
- (fixed, windows) single letter filenames without extensions (e.g., "A") now
are distinguished from windows drive letters (e.g., "A:\")
1.5.3.2 (October 2024)
=======
*** ChuGL maintanance patch ***
- (updated) backend WebGPU version to wgpu-22.1.0.5
- (added) OpenGL fallback on machines where modern graphics APIs (vulkan, metal, direct3d)
are not supported
- (fixed) shreds can now exit a GG.nextFrame() loop without hanging the window
- (added) GG.unregisterShred() to manually unregister a graphics shred
- (added) new examples
- deep/particles.ck : musical partical system
- deep/sprite_animation.ck : sprite animation via sprite sheets
- (fixed) race condition on window resize
*******************************
- (added) MidiFileIn.bpm()
"Same as beatsPerMinute()."
- (added) MidiFileIn.ticksPerQuarter();
"Get the ticks per quarter (TPQ) value from the MIDI file header."
- (added) MidiFileIn.tpq();
"Same as ticksPerQuarter()."
- (fixed) documentation for MidiMsg.when:
"Duration since the last MidiMsg (only valid for MidiFileIn)."
- (fixed, windows) SndBuf issue when compiled with UNICODE (FYI SndBuf is still ANSI,
but this averts an error due to char width mismatch)
- (changed, developer) chuck global manager getGlobalUGenSamples() now handles multi-channel
implications for Chunity support for stereo
- (added) new examples (FM Synthesis)
examples/stk/jacobass-algo1.ck
(such groove, much Algorithm 1)
examples/stk/nylon-guitar-algo1.ck
(updated/renamed from honkeytonk-algo3.ck)
1.5.3.1 (October 2024)
=======
*** ChuGL maintanance patch ***
- (fixed) crash caused by calling UI functions before calling GG.nextFrame();
now prints a warning with a hint to call GG.nextFrame()
- (fixed) CPU and memory spikes when minimizing a ChuGL window
- (fixed) crash caused by immediately disconnecting GGen after -->
*******************************
- (fixed) ADSR constructors now work correctly
- (fixed) compiler now reports line numbers and caret position correctly after
a multi-line string literal
1.5.3.0 (September 2024)
=======
- (major update) ****** ChuGL.chug v0.2.0 (alpha) ******
* complete under-the-hood engine rewrite
* now uses WebGPU instead of OpenGL as the core graphic library
* some minor API changes, see: https://chuck.stanford.edu/chugl/api/
* new and updated examples, see: https://chuck.stanford.edu/chugl/examples/
* for more information, visit: https://chuck.stanford.edu/chugl/
*********************************************
- (added, macOS and Linux) --chugin: and --chugin-path:
flags now expands '~' in filepath
- (developer) fixed QUERY->getinfo(); previously the function pointer was
NULL and would caused a crash if called
- (developer) updated set/getParam() key names:
was: CHUCK_PARAM_USER_CHUGINS now: CHUCK_PARAM_CHUGIN_LIST_USER
was: CHUCK_PARAM_USER_CHUGIN_DIRECTORIES now: CHUCK_PARAM_CHUGIN_LIST_USER_DIR
1.5.2.5 (July 2024)
=======
- (updated) chugin API version from 10.1 to 10.2
- (added) chugin API for callback on shutdown
- (added) chugin API for setting array elements (thanks azaday)
- (added) overloaded constructors (more to come)
==================
Envelope( dur durationToTarget )
Construct an Envelope with duration to reach target (assumed to be 1.0);
FYI this does not start the Envelope until .keyOn() is called.
Envelope( float secondsToTarget )
Construct an Envelope with duration (in seconds) to reach target (assumed to be 1.0);
FYI this does not start the Envelope until .keyOn() is called.
Envelope( dur durationToTarget, float target )
Construct an Envelope with duration to reach target;
FYI this does not start the Envelope until .keyOn() is called.
Envelope( float durationToTarget, float target )
Construct an Envelope with duration (in seconds) to reach target;
FYI this does not start the Envelope until .keyOn() is called.
ADSR( dur attack, dur decay, float sustain, dur release )
Construct an ADSR with attack, decay, sustain, and release values. Attack,
decay, and release values are durations; sustain is a float value typically
between 0 and 1.
ADSR( float attack, float decay, float sustain, float release )
Construct an ADSR with attack, decay, sustain, and release values. Attack,
decay, and release values are in seconds; sustain is a float value
typically between 0 and 1.
Delay( dur delay, dur max )
Construct a Delay with delay length and delay max.
Delay( dur delay )
Construct a Delay with delay length and, implicitly, delay max.
DelayA( dur delay, dur max )
Construct a DelayA with delay length and delay max.
DelayA( dur delay )
Construct a DelayA with delay length and, implicitly, delay max.
DelayL( dur delay, dur max )
Construct a DelayL with delay length and delay max.
DelayL( dur delay )
Construct a DelayL with delay length and, implicitly, delay max.
Echo( dur delay, dur max )
Construct an Echo with delay length and delay max.
Echo( dur delay )
Construct an Echo with delay length and, implicitly, delay max.
==================
- (added) new member functions
==================
dur Envelope.ramp( dur durationToTarget, float target );
Over the given duration, ramp toward the specified target; returns the given
duration.
dur Envelope.ramp( float secondsToTarget, float target );
Over the given duration (in seconds), ramp toward the specified target; returns
the given duration.
void Delay.set( dur delay, dur max )
Set delay length and delay max; delay should be <= max.
void DelayA.set( dur delay, dur max )
Set delay length and delay max; delay should be <= max.
void DelayL.set( dur delay, dur max )
Set delay length and delay max; delay should be <= max.
void Echo.set( dur delay, dur max )
Set delay length and delay max; delay should be <= max.
==================
- (added) examples/basic/envelope2.ck -- to show Envelope.ramp() in action
- (added) new MidiOut message voice message convenience functions (thanks @cviejo;
previously these are possible only through `MidiOut.send( MidiMsg msg )`:
==================
int send( int status, int data1, int data2 );
Send out a MIDI message consisting of one status byte and two data bytes.
int channelPressure(int channel, int pressure)
Send out a channelPressure message.
int controlChange(int channel, int controller, int value)
Send out a controlChange message.
int noteOff(int channel, int note, int velocity)
Send out a noteOff message.
int noteOn(int channel, int note, int velocity)
Send out a noteOn message.
int pitchBend(int channel, int value)
Send out a pitchBend message.
int pitchBend(int channel, int lsb, int msb)
Send out a pitchBend message with fine and coarse values.
int polyPressure(int channel, int note, int pressure)
Send out a polyPressure message.
int programChange(int channel, int program)
Send out a programChange message.
==================
- (added) examples/midi/midiout2.ck -- demonstrates using the above channel
voice messages
- (added) examples/deep/smb.ck -- a ChucK rendition of Super Mario Bros.
original theme by Koji Kondo; (meticulously) modeled in ChucK by
Wesley Burchell in 2017
- (added) examples/basic/delay2.ck -- example showing DelayL constructor
and modulating delay line length
- (added) examples/basic/blit3.ck -- lounge blit; made for svork concert
lounge music for premiere in May 2024
- (added) examples/special/scream-o-matic/scream-o-matic.ck -- using
multiple LiSas for granular synthesis, to make continuous
scream generator
- (added) command line query system `--query:<name>`
- (added) CKDoc JSON output (terry feng)
- (added) Type type added to CKDoc script and deployed online:
https://chuck.stanford.edu/doc/reference/utils.html#Type
- (added) CKDoc.sort( int ) -- toggle alphabetical sorting of functions and variables
within Type documentation generation (thanks azaday)
- (fixed) globals events system synchronization (FYI this fixes a long-running,
elusive Chunity crashing bug involving various syncers)
- (fixed) STK Moog parameters now consistent (should sound more Moog-y)
- (fixed) local non-control structure local scope Objects now correctly cleaned
up at the end of local scope
- (updated) more and clearer error messages when initializing real-time audio
- (developer) streamline makefile targets 'test' 'doc' 'clean'
1.5.2.4 (April 2024)
=======
- (fixed) runtime exception line number reporting
- (fixed) 3rd-time array ugen link modulo connection between different # of channels
- (fixed) LiSaX crashing on duplicate constructor and destructors (thanks @eswartz)
- (fixed) LiSaX memory leak on creation due to duplicate constructor
- (reinstated) the UGen `bunghole` (a tribute to cultural icon Beavis); equivalent to
blackhole in functionality
1.5.2.3 (April 2024)
=======
- (fixed) regression issue with connecting arrays of mono UGens to
non-mono ugens; e.g., `Gain a[2] => dac;`
FYI examples/stereo/ugen-array.ck now works once again
- (updated) examples/array/array_ugens.ck contains additional
examples of array of ugens connecting with stereo ugens
1.5.2.2 (March 2024)
=======
- (added) Open Sound Control (OSC) address wildcard support
(developer note) internally updated OSC implmentation to liblo v0.32
- (added) OSC wildcard examples
examples/osc/wildcards/r-wildcards.ck
examples/osc/wildcards/s-multi.ck
- (modified) semantics for connecting (=>) arrays of UGens;
1) LHS[X] => RHS: each elements in LHS => to RHS
// Gain A[3] => Gain B;
2) LHS[X] => RHS[X]: one to one mapping
// Gain C[3] => Gain D[3];
3) LHS[X] => RHS[Y]: one to one mapping up to min(X,Y), after
which elements in the smaller array will modulo to the beginning
and connect to remaining elements in larger array
// Gain E[2] => Gain F[3];
4) LHS => RHS[X]: LHS => to each element in RHS
// Gain G => Gain H[3];
- (added) connecting (=^) arrays of Unit Analyzers (UAnae)
- (added) examples/array/array_ugen.ck
- (added) Math.min( int, int ) and Math.max( int, int )
NOTE: these overload the existing (float,float) min/max functions
- (fixed) error reporting for =^ =v --> --< operators
- (fixed) all oscillators Osc( freq, phase ) constructors; previously the phase
was not set correctly
- (fixed) crash in cleaning up certain global objects (specifically those
with default constructors), including OscIn, and ChuGL classes
GGen, Geometry, FileTexture
- (fixed) incorrect CKDoc .help() labeling non-constructors as
constructors in user-defined classes
- (developer) added internal/audio-thread-callable setters for global
int / float arrays
1.5.2.1 (December 2023) ChuGL (alpha) => standard distribution
=======
- (added) ChuGL (alpha) is now part of the standard chuck distribution
(macOS and windows; on linux, build from source)
https://chuck.stanford.edu/chugl/
- (note) this alpha release of ChuGL (ChucK Graphics Library: a real-time
audiovisual programming framework) only works with command-line `chuck`
and does not work from within miniAudicle (miniAudicle support is on
the ChuGL development roadmap)
=======
- (added) chugins can now implement a "info query function" to provide
chugin-specific infomation to be accessible from host, including:
* chugin version (not to be confused with compatibility version)
* chugin author(s)
* chugin description
* (optional) chugin URL
* (optional) contact email
for example, in the chugin source:
```
// chugin info func
CK_DLL_INFO( MyChugin )
{
// set info
QUERY->setinfo( QUERY, CHUGIN_INFO_CHUGIN_VERSION, "v3.6.1" );
QUERY->setinfo( QUERY, CHUGIN_INFO_AUTHORS, "Ana B. Croft" );
QUERY->setinfo( QUERY, CHUGIN_INFO_DESCRIPTION, "what does it do?" );
QUERY->setinfo( QUERY, CHUGIN_INFO_URL, "https://foo.com/FooBar" );
QUERY->setinfo( QUERY, CHUGIN_INFO_EMAIL, "[email protected]" );
}
```
- (updated) revert chugin/host compatibility policy
chugin major version must == host major version
chugin minor version must <= host minor version
(previously in 1.5.2.0) chugin AND host API version must match
1.5.2.0 (November 2023) "Better Late Than Never...constructors"
=======
- (added) class constructors
- (added) overloadable class constructors definitions
============
constructors can be invoked when declaring a variable or with `new`:
```
// connecting UGens, with construtors
SinOsc foo(440) => Gain g(.5) => dac;
// `new` and assignment
new TriOsc(440,pi/2) @=> Osc @ oscillator;
// can combine constructors with arrays
string arr("foo")[10];
```
============
constructors can be defined and overloaded in class definitions:
```
class Foo
{
// a member variable
1 => int num;
// constructor "default"
fun @construct() { 2 => num; }
// another constructor
fun @construct( int x ) { x => num; }
// yet another constructor
fun @construct( int x, int y ) { x*y => num; }
// alternate way of define a constructor, using the class name
fun Foo( int x, int y, int z ) { x*y*z => num; }
// destructor
fun @destruct() { <<< "bye:", this.num >>>; }
}
// constructor "default"
Foo f1();
// another constructor
Foo f2(15);
// yet another constructor
new Foo(8,9) @=> Foo @ f3;
// yet another constructor
new Foo(10,11,12) @=> Foo @ f4;
// print
<<< f1.num, f2.num, f3.num, f4.num >>>;
```
- (added) examples/class/constructors.ck
- (added) examples/class/destructor.ck
- (added) CKDoc and .help() support for constructors
- (added) overloaded functions can now have different return types;
for example:
```
// foo() overload 1 returns float
fun float foo( float b ) { return b; }
// foo() overload 2 returns int
fun int foo( int a ) { return a; }
```
- (fixed) Type.of("int[][]").isArray() now correctly returns true
- (fixed) overzealous dependency validation for member variable usage
from other classes
- (fixed) overzealous dependency validation for file-level variable
usage from functions
- (fixed) disambiguating overloaded functions to choose the "closest" match
by function call argument type inheritance "distance" to function
argument type
- (added) Shred.parent() and Shred.ancestor()
- (added) compiler error for ambiguous function calls when there is no
"closest" match
- (fixed) array popFront() crash on Object-based arrays
- (updated) ChucK API doucmentation for constructors
- (added) overloaded constructors added (more to come)
==================
Gain( float gain );
Construct a Gain with default value.
SndBuf( string path );
Construct a SndBuf with the 'path' to a sound file to read.
SndBuf( string path, float rate );
Construct a SndBuf with the 'path' to a sound file to read, and a default playback 'rate' (1.0 is normal rate)
SndBuf( string path, float rate, int pos );
Construct a SndBuf with the 'path' to a sound file to read, a default playback 'rate' (1.0 is normal rate), and starting at sample position 'pos'
Step( float value );
Construct a Step with a default value.
string( string str );
Construct a string as a copy of another string.
Osc( float freq );
Construct a Osc at specified frequency.
Osc( float freq, float phase );
Construct an Osc at specified frequency and phase.
(similarly for SinOsc, TriOsc, SqrOsc, SawOsc, PulseOsc, Phasor)
==================
chugins API update
==================
- (updated) chugin API version updated to 10.1
-- complete decoupling of chugins interface and chuck core
implementation details
-- new chugins runtime API functions to provide access
to chuck core operations that is safe across the shared/dynamic
library boudaries between chugins and a chuck host
(see Chuck_DL_Api in chuck_dl.h for details)
- (updated) all chugins can now include a single header `chugin.h`
with no additional header dependencies
[see: https://github.com/ccrma/cheaders/tree/main/include]
FYI: this single-header `chugin.h` is generated from a minimal
set of chuck core header files: chuck_def.h chuck_symbol.h
chuck_absyn.h and chuck_dl.h
- (updated) it is highly recommended that all chugins update to
using chugin.h; it is still possible to include chuck headers
directly (either chuck_dl.h or chuck.h), but must #define
__CHUCK_CHUGIN__ macro (if using chugin.h, this macro is always
defined at the top of file)
- (updated) chugin AND host API version must now match
(previously only the major version must match)
- (added) chugins runtime API support for creating arrays from chugins
- (added) chugins support for overloading constructors
1.5.1.8 (October 2023) "Halloween Release"
=======
(note) memory management is ghoulishly frightful!
- (fixed) an issue with memory management / reference counting across
overloaded operations that return Object
- (fixed) an issue with reference count cleanup on recursive functions
that return Objects
- (fixed) an issue with reference count cleanup on 'new' operator,
e.g., (new Foo).f();
- (updated) reduced memory management dependency between language-defined
objects and their "parent" shreds
- (updated) --color:ON and --color now will always output ANSI color
codes, regardless of TTY status; (FYI --color:AUTO is unchanged
and is the same as default, i.e., enable color terminal if TTY
detected; disable otherwise
- (added, developer) chugins API float array access
1.5.1.7 (October 2023) "vec2"
=======
- (added) new type 'vec2' 2D vector type
for 2D animation (ChuGL) as well as texture mapping UV or ST
coordinates; access fields with .x/.y OR .u/.v OR .s/.t
- (added) new examples/vector/vec2.ck
- (reworked) memory management across function calls that return
Object types; now correctly tracks all instances within a
statement and balances reference counts; previously there was
a chance that object refcount were not correctly released,
causing incorrect behavior including memory leaks.
"dangling object references tracking and cleanup"
examples include (assumption: foo() returns an Object):
`foo().bar;` or `foo(), foo()` (multi-expression stmt) or
`while( foo().bar ) { ... }` (loop stmt) and many more.
- (fixed) incorrect reference count for certain usages of 'null'
where the expression was interpreted incorrectly as a
function call, e.g., obj == null
1.5.1.6 (October 2023) patch release
=======
- (fixed) a serious issue accessing vec3/vec4 fields (.x, .y, .z. .w)
where the operand stack was incorrectly cleaned, which could lead
to stack overflow. This issue has been addressed.
=======
NOTE: 1.5.1.5 is the alpha-release / soft launch of ChuGL, a unified
audiovisual programming framework built into the ChucK programming
language. It offers real-time, unified audio synthesis and 3D/2D graphics
programming in a single strongly-timed language.
------
https://chuck.stanford.edu/chugl/
=======
1.5.1.5 (October 2023) "operator overloading + chugins API 9.0"
=======
- (added) operator overloading is here!
Most operator can now be overloaded, within their respective existing
forms in the language (e.g., binary operators such as '+' and '=>'
can be overloaded as binary operators, but not as unary operators).
Similar to class definitions, operator overloads are local in scope
to the file context, unless declared with 'public'. operator
overloading marked as 'public' will persists until 1) the VM stops or
2) the VM is cleared/reset.
//-----------------------------------------------------------
// the general format for overload an operator is as follows:
//-----------------------------------------------------------
// let's say we define a custom class...
public class Foo { int num; }
// PUBLIC operator overloading (transcends contexts and files;
// will persist until stop VM or clear VM. NOTE the use of 'public'
// instead of 'fun' (fun for all!)
public Foo @operator =^( Foo lhs, Foo rhs )
{ /* do stuff for Foo =^ Foo */ return rhs; }
// LOCAL binary operator overload for '=>' (local to this context)
fun Foo @operator =>( Foo lhs, Foo rhs )
{ /* do stuff for Foo => Foo */ return rhs; }
// define binary operator overload for '+'
fun Foo @operator +( Foo lhs, Foo rhs )
{ Foo retval; lhs.num + rhs.num => retval.num; return retval; }
// define binary operator overload for '*'
fun Foo @operator *( Foo lhs, Foo rhs )
{ Foo retval; lhs.num * rhs.num => retval.num; return retval; }
// define unary operator overload for '!'
fun int @operator !( Foo foo )
{ return !foo.num; }
// define postfix operator overload for '++'
fun Foo @operator ( Foo foo ) ++
{ foo.num++; return foo; }
//-----------------------------------------------------------
// using the new overloaded operators
//-----------------------------------------------------------
// create 2 Foos
Foo a, b; 1 => a.num; 2 => b.num;
// operator in action (follows default ck operator precedence)
a + b * b + a @=> Foo c;
// post ++ on c
c++;
// should print 7
<<< c.num >>>;
//-----------------------------------------------------------
- (added) new examples showing basic operator overloading usage
examples/oper/overload_overview.ck
examples/oper/overload_pre_post.ck
examples/oper/overload_public.ck
examples/oper/overload_gru.ck
- (added) the "gruck operator" --> (graphical chuck operator) as part
of ChuGL (ChucK Graphics Library), which will be part of the ChucK
language
- (added) Machine function to on-the-fly control operator overloading stack
static void resetOperators();
Reset operator overloading state to default startup state;
removes all public @operator overloads; use with care.
- (added) new Machine function for getting number of shreds currently in VM
static int numShreds();
Get the number of shreds currently in the VM.
- (added) improved exception reporting and stack-overflow detection and
handling. Overall, these change improve system robustness and runtime
information.
- (added) two new (and somewhat arcane) Shred methods to support "extreme
shredding" use cases:
----
int childMemSize( int sizeInBytes );
Set size hint of per-shred call stack ("mem") for children
shreds subsequently sporked from the calling shred (NOTE this
size hint does not affect the calling shred--only its
descendants); if sizeInBytes <= 0, the size hint is set to
the VM default. (FYI This is an arcane functionality that
most programmers never need to worry about. Advanced usage:
set size hint to small values (e.g., 1K) to support A LOT
(e.g., >10000) of simultaneous shreds; set size hint to large
values (e.g., >65K) to spork functions with extremely deep
recursion, or to support A LOT (>10000) of declared local
variables. Use with care.)
int childMemSize();
Get the memory stack size hint (in bytes) for shreds sporked
from this one.
int childRegSize( int sizeInBytes );
Set size hint of per-shred operand stack ("reg") for children
shreds subsequently sporked from the calling shred (NOTE this
size hint does not affect the calling shred--only its
descendants); if sizeInBytes <= 0, the size hint is set to
the VM default. (FYI This is an arcane functionality
that most programmers never need to worry about. Advanced
usage: set size hint to small values (e.g., 256 bytes) to
support A LOT (>10000) of simultaneous shreds; set size hint
to large values (e.g., >20K) to spork functions with
extremely lengthy (>10000) statements, including array
initializer lists. Use with care.)
int childRegSize();
Get the operand stack size hint (in bytes) for shreds sporked
from this one.
----
- (added) FileIO.open() now takes "special:auto" as the filename (output
only) to write to a new file with auto-generated filename in the
current directory (based on the current system time, precise to
second;NOTE files created into way at the same system time will have
the same auto-generated filename and may conflict or fail to open).
The "auto" prefix and extension can be set and retrieved using the
following new functions to FileIO:
---
string autoExtension();
Get auto extension for "special:auto" filename generation
(applicable to file writing only).
string autoPrefix();
Get auto prefix for "special:auto" filename generation
(applicable to file writing only).
void autoPrefixExtension( string prefix, string extension );
Set auto prefix and extension for "special:auto" filename
generation (applicable to file writing only).
---
- (fixed) float *=> vec4 now works as intended (instead of producing a
a compilation error)
- (fixed) on Windows and --verbose level SYSTEM or higher, when a chugin
fails to load, instead of displaying a cryptic error code (e.g.,
"reason: 1920"), the error code is translating into an error message
and displayed (e.g., "reason: The file cannot be accessed by the system.")
(azaday)
- (fixed) on certain systems, program ending with a single-line // comment
could crash; affects miniAudicle, WebChucK, Machine.eval() containing
code that ending with a trailing comment
- (fixed) on-the-fly programming (OTF) system was incorrectly cleaning
up file descriptors and leading to instability
- (updated) ConsoleInput.prompt( text ) now no longer prints an extra
space (" ") after prompt text
- (updated) chugins headers version incremented to 9.0
- (added; chugins development) overhauled dynamic linking API to access
chuck host-side operations; this greatly expands chugins capabilities
but will unfortunately require API changes that will break chugin
builds that uses the existing API.
(check out chuck_dl.h: `namespace Chuck_DL_Api`)
- (added; chugins development) ability to overload operators from chugin
query functions in C++:
// add binary operator overload; args included
f_add_op_overload_binary add_op_overload_binary;
// add unary (prefix) operator overload; arg included
f_add_op_overload_prefix add_op_overload_prefix;
// add unary (postfix) operator overload; arg included
f_add_op_overload_postfix add_op_overload_postfix;
- (added; chugins development) capability to invoke chuck language-side
member functions (in chuck) from chugins (in C++)
// invoke Object member function (defined either in chuck or c++)
// NOTE this will call the member function in IMMEDIATE MODE,
// marking it as a time-critical function when called in this
// manner; any time/event operations therein will throw an exception
Chuck_DL_Return API->vm->invoke_mfun_immediate_mode(
Chuck_Object * obj, t_CKUINT func_vt_offset, Chuck_VM * vm,
Chuck_VM_Shred * shred, Chuck_DL_Arg * ARGS, t_CKUINT numArgs );
- (added; chugins development) new API->type API for C++/chugins to
lookup types in the type system, virtual function offsets (useful
for API->vm->invoke_mfun_immediate_mode() above)
- (added and updated; chugins development) across all existing
chugins DL API and many additions; the chugins runtime API 9.0
=============================
// C++ chugins runtime API for VM access (access from chugins using API->vm->...)
// get sample rate | 1.5.1.4
t_CKUINT srate( Chuck_VM * vm );
// get chuck now | 1.5.1.4
t_CKTIME now( Chuck_VM * vm );
// create a new lock-free one-producer, one-consumer buffer | 1.5.1.4
CBufferSimple * create_event_buffer( Chuck_VM * vm );
// queue an event; num_msg must be 1; buffer should be created using create_event_buffer() above | 1.5.1.4
t_CKBOOL queue_event( Chuck_VM * vm, Chuck_Event * event, t_CKINT num_msg, CBufferSimple * buffer );
// invoke Chuck_Object member function (defined either in chuck or c++) | 1.5.1.4 (ge & andrew)
// NOTE this will call the member function in IMMEDIATE MODE,
// marking it as a time-critical function when called in this manner;
// any time/event operations therein will throw an exception
Chuck_DL_Return invoke_mfun_immediate_mode( Chuck_Object * obj, t_CKUINT func_vt_offset,
Chuck_VM * vm, Chuck_VM_Shred * shred, Chuck_DL_Arg * ARGS, t_CKUINT numArgs );
// throw an exception; if shred is passed in, it will be halted
void throw_exception( const char * exception, const char * desc, Chuck_VM_Shred * shred );
// log a message in the chuck logging system
void em_log( t_CKINT level, const char * text );
// system function: remove all shreds in VM; use with care
void remove_all_shreds( Chuck_VM * vm );
--------------------------------
// C++ chugins runtime API for object access (access using API->object->...)
// function pointer get_type()
Type get_type( Object object );
// add reference count
void add_ref( Object object );
// release reference count
void release( Object object );
// get reference count
t_CKUINT refcount( Object object );
// instantiating and initializing a ChucK object by type, with reference to a parent shred
// if addRef == TRUE the newly created object will have a reference count of 1; otherwise 0
// NOTE set addRef to TRUE if you intend to keep a reference of the newly created object around
// NOTE set addRef to FALSE if the created object is to be returned without keeping a reference around
Object create( Chuck_VM_Shred *, Type type, t_CKBOOL addRef );
// instantiating and initializing a ChucK object by type, with no reference to a parent shred
// if addRef == TRUE the newly created object will have a reference count of 1; otherwise 0
Object create_without_shred( Chuck_VM *, Type type, t_CKBOOL addRef );
// instantiate and initialize a ChucK string by type
// if addRef == TRUE the newly created object will have a reference count of 1; otherwise 0
String create_string( Chuck_VM *, const char * value, t_CKBOOL addRef );
// function pointers for get_mvar_*()
t_CKBOOL get_mvar_int( Object object, const char * name, t_CKINT & value );
t_CKBOOL get_mvar_float( Object object, const char * name, t_CKFLOAT & value );
t_CKBOOL get_mvar_dur( Object object, const char * name, t_CKDUR & value );
t_CKBOOL get_mvar_time( Object object, const char * name, t_CKTIME & value );
t_CKBOOL get_mvar_string( Object object, const char * name, String & value );
t_CKBOOL get_mvar_object( Object object, const char * name, Object & value );
// function pointer for set_string()
t_CKBOOL set_string( String string, const char * value );
// array_int operations
t_CKBOOL array_int_size( ArrayInt array, t_CKINT & value );
t_CKBOOL array_int_push_back( ArrayInt array, t_CKUINT value );
t_CKBOOL array_int_get_idx( ArrayInt array, t_CKINT idx, t_CKUINT & value );
t_CKBOOL array_int_get_key( ArrayInt array, const std::string & key, t_CKUINT & value );
--------------------------------
// C++ chugins runtime API for type access (new; access using API->type->...)
// lookup type by name
Type lookup( Chuck_VM *, const char * name );
// get vtable offset for named function; if overloaded, returns first;
// (returns < 0 if not found)
t_CKINT get_vtable_offset( Chuck_VM *, Type type, const char * value );
// test if two chuck types are equal
t_CKBOOL is_equal(Type lhs, Type rhs);
// test if lhs is a type of rhs (e.g., SinOsc is a type of UGen)
t_CKBOOL isa(Type lhs, Type rhs);
=============================
1.5.1.3 (September 2023) "ChucK to School"
=======
(note) this release of chuck addresses a number of issues from long-time
language bugs to documentation updates to expanding Machine functions
for VM/shred management to improved Open Sound Control support. Over
the dozen releases since chuck-1.5.0.0, this release is strongly-timed
for students and instructors coming back to school in Fall 2023!
(One of our ongoing priorities is to make the language + tools
better for teaching, research, and of course music making.)
- (updated) Machine.add()/replace()/remove()/status() now re-implemented
internally for both performance and greater compatibility (now can
be used with no dependencies on OTF system, make it possible to call
these from systems like WebChucK).
- (added) new and updated Machine functions
---------
** new ** static int removeLastShred();
Remove the most recently added shred in the VM (could be the
shred calling this function); returns the ID of the removed
shred.
** new ** static int resetShredID();
Reset shred IDs to 1 + the highest current shred ID in the VM;
can be used as shred management to keep shred IDs low, after
a lot of sporks. Returns what the next shred ID would be.
** new ** static void removeAllShreds();
Remove all shreds in the VM (including the shred calling this
function).
** new ** static void clearVM();
Reset the type system, removing all user-defined types and all
global variables; removes all shreds in the VM (including the
shred calling this function). Use with care.
** new ** static void printStatus();
Print (to terminal or console) the current status of the VM.
** new ** static void printTimeCheck();
Print (to terminal or console) the current time information in
the VM.
-------------
** updated ** static int add( string path );
Compile and spork a new shred from file at 'path' into the VM;
returns the new shred ID. It is possible to include arguments
with the file being added, e.g., `Machine.add(
"foo.ck:bar:3:5.0" )`.
** updated ** static int replace( int id, string path );
Replace shred with new shred from file. Returns new shred ID,
or 0 on error. It is possible to include arguments, e.g.,
`Machine.replace( outID, "foo.ck:bar:3:5.0" )`.
** updated ** static int remove( int id );
Remove shred from VM by shred ID (returned by Machine.add).
** updated ** static int status();
Print the current status of the VM;
legacy version of printStatus().
-------------
- (updated) Machine.add( filepath ) no longer introduces a potential
real-time audio interruption on macOS ** for all filepath that does
not contain ~ **; currently, path resolution for ~ or ~[username] in
macOS consistently causes audio clicks, likely due to implementation
of underlying system function (e.g., wordexp()) to resolve ~
(hypothesis: wordexp() function performs IO-blocking)
- (added) function to expand platform specific file path
static string expandPath( string path );
Expand platform-specific filepath to an absolute path, which
is returned. On macOS and Linux expandPath() will attempt to
resolve `~` or `~[username]`; on Windows expandPath() will
attempt to resolve %USERNAME%. (Known issue: (macOS)
expandPath currently introduced an audio click; it
recommended to call expandPath() at the beginning; e.g.,
expanding path ahead of time could avoid a click instead of
calling Machine.add() on a filepath with `~`.)
- (added) a new (3rd) string.replace() function
void replace( string from, string to );
Replace all instances of 'from' in the string with 'to'.
(for reference the existing string.replace() function)
void replace( int position, string str );
Replace characters from 'position' with contents of 'str'.
void replace( int position, int length, string str );
Replace 'length' characters from 'position' with contents of 'str'.
- (added) examples/string/replace.ck
- (updated) move real-time audio system warnings to log level "WARN"; this
should result in less clutter printed, in particular on Linux/ALSA.
- (updated) CKDoc now prints class functions before variables
- (added, chugin development) new backend chugin <=> chuck host API
functions for array.size(), array.get_idx(), array.get_key()
(@nshaheed)
- (fixed) various documentation misspellings (thanks @barak)
- (fixed) variable look-up priorities when multiple variables of the same
name are declared in various situations in the same file (shadowing);
this resolves issues within a subclass incorrectly accessing
variables of the same name (declared as local variable vs. member in
a parent class vs. global-scope variables), depending on where it's
accessed from.
---
updated convention for value lookup priority (in case of shadowing)
1) first look in the same scope
2) if not found, and if inside a class def, look up-scope within
class (but no further)
3) if not found, and if inside a class def, look in parent (for
inherited value)
4) if still not found, look all the way up to global scope
---
for example: chuck/src/test/01-Basic/194-value-lookup-order.ck
---
- (fixed) using => to connect from/to empty UGen array declaration no
longer results in a crash; instead there is now a compiler error:
```
a.ck:8:17: error: cannot connect '=>' to empty array '[ ]' declaration...
[8] [foo] => SinOsc bars[];
^
a.ck: ...(hint: declare 'bars' as an non-empty array)
a.ck: ...(or if assignment was the intent, use '@=>' instead)
```
- (fixed) duplicate function declaration no longer causes a crash after
reporting the error
```
// example of duplicate function declarations
fun void bar() { }
fun void bar() { }
```
- (fixed) assigning to constants such as `pi`, `second`, or `Math.PI` now
results in a compiler error; previously the outcome was undefined and
in certain case could cause a crash.
- (fixed) concatenating a function reference with a string now produces a
compiler error; previously this would lead to a runtime crash.
```
a.ck:17:9: error: cannot perform '+' on string and '[function]'
[17] <<< " " + f.getFoo >>>;
^
a.ck:17:13: error: ...(hint: to call the function, add '()' and any arguments)
[17] <<< " " + f.getFoo >>>;
^
```
- (fixed) an issue appending arrays to arrays for non-integer types
```
float foo[0][0]; float bar[0];
foo << bar;
```
- (fixed) an issue with OscOut on Windows, which can crash on object cleanup
due to incorrect windows-specific socket closing
- (fixed; reworked) OSC dispatch for multiple OscIn clients listening on
the same OSC address; the crash has bee resolved, and the OSC
incoming server message dispatch has been reworked
- (re-added) 'Chubgraph' has been "re-deprecated", which actually means
older code that use 'Chubgraph' instead of 'Chugraph" will now work
again, with the deprecation warning (previously `Chubgraph` would
result in a compiler error):
`deprecated: 'Chubgraph' --> use: 'Chugraph' instead`
- (updated) minor improvements in compiler error reporting; more
accurate position accuracy for binary operators, including =>,
@=>, and =^
- (updated) log level 3 (SEVERE) has been renamed to (HERALD)
- (updated) improved stability on ctrl-c shutdown for real-time audio
and HID management
- (added) examples/effects/autotune.ck
---
- (added) WebChucK support for Machine.add()/replace()/remove()/removeAll()
- (added) WebChucK IDE now supports the ability to upload .ck files for
Machine (@terryzfeng) https://chuck.stanford.edu/ide/
- (updated) for Chugin developers, the `chuginate` tool has been
modernized (spencer and ge) -- 0) chuginate updated from using
python2 to python3; 1) in addition to a boilerplate C++ project for
a chugin, chuginate now also generates a boilerplate NAME-test.ck
ChucK program; 2) more informative comments in the boilerplate C++
code; 3) updated makefiles for all platforms.
1.5.1.2 (August 2023)
=======
- (updated) the long-time and often cryptic "cannot bind to port: 8888"
message has been reworked: 1) an explanation has been added to the
possible cause (e.g., another chuck VM is running and currently
has the port open) and implication (this chuck VM will not receive
OTF commands over the network); 2) the printing of this message has
been moved by default to log level 2 (SYSTEM) with further information
on log level 5 (INFO) UNLESS the '--loop` flag is present, which
signals intention to use the VM as an OTF command listener (and the
warning is more likely to be relevant information). This should
hopefully reduce confusion, as well as improve automations that
examine the output of chuck. (thanks to @barak for elucidating the
issue!)
- (added) --cmd-listener:{on|off} enables or disables listening for
network OTF (on-the-fly programming) command messages (e.g., add,
replace, remove, etc.). The default is ON; setting to OFF will prevent
chuck VM from attempting to open network server listener. (NOTE: this
option does NOT affect in-language networking, e.g., with Open Sound
Control.)
1.5.1.1 (August 2023)
=======
(note) this patch release fixes a number of issues related to recently added
language features; it also adds some "syntactic sugar" in the form of
allowing trailing commas in array initializer lists, as well as a set
of range() functions for generating arrays of ranges of value.
- (added) trailing commas in array initializer lists are now permitted
```
// an array initializer list (aka array literal), as usual
[1,2,3] @=> int foo[];
// now also permitted: trailing comma after last element
[1,2,3,] @=> int bar[];
```
- (added) Std functions for generating arrays containing a range of
values (nshaheed)
static int[] Std.range( int stop );
Return array containing the range [0,stop).
static int[] Std.range( int start, int stop );
Return array containing the range [start,stop).
static int[] Std.range( int start, int stop, int step );
Return array containing values from start up to (but not including) stop,
hopping by step.
- (re-added) backtick(`)-delimited strings; context: needed for FaucK
(FAUST in ChucK) through the Faust chugin
- (fixed) issue related to multiple empty statements (e.g., ;;;;) being
incorrectly handled by the function control path analysis
- (fixed) issue related to incorrect out-of-order dependencies across
different files / contexts (thanks Michael Heuer for investigating)
- (fixed) class member/static variables can now be accessed, as before,
from anywhere in the same file, regardless of order of declaration
(thanks Michael Heuer for investigating)
```
Foo foo;
// using val above declaration is part of language semantics
// (but due to regression bug was broken in 1.5.0.8)
// this should work once again
5 => foo.val;
class Foo
{
int val;
}
```
- (updated) 'auto' type is now disallowed as a top-level class variables,
instance or static; since these variables could be used from outside the class,
1) this potentially leads to more intentional code and 2) currently there is no
mechanism to resolve the 'auto' until type checking stage such that out-of-order
access of class variables are resolved.
```
// class definition
class Foo
{
// ok
for( auto x : [1,2,3] ) { <<< x >>>; }
// ok
fun void bar() { 4 => auto y; }
// ok
if( true ) { 5 => auto x; }
// ok
{ 6 => auto x; }
// not ok *** compiler should report error
7 => auto m_var;
// not ok *** compiler should report error
8 => static auto m_var;
}
```
- (fixed) a memory leak associated with array declarations
- (fixed) chout and cherr now properly accounts for IO redirect out of
chuck; this addresses issue with miniAudicle console output, and
also affects other C++ hosts embedding chuck core.
1.5.1.0 (August 2023)
=======
(note) this release (1.5.1.0) updates a long-standing policy regarding
`return`statements in function declarations; adds @array.sort(), a new
command-line option, general bug fixes and stability improvements.
(note) much has been added between 1.5.0.0 and 1.5.1.0, including:
* new for-each loop syntax for iterating through arrays (1.5.0.8)
* enhanced and more accurate compiler error reporting; now