Source

Coin / docs / api-wish-list.txt

Full commit
  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
WHAT'S THIS?
============

Beyond Coin: Gold (v1.0, the Open Inventor compatibility release), we
intend to extend the original Open Inventor API where we think it
lacks needed functionality.  This file contains a collection of such
API extension ideas that we will consider to implement in the future.

The listing of an API change or API extension in this file does not
mean that it will be implemented, only that it will be considered for
implementation.

Ideas for this wish list can be submitted by anyone.


THE WISH LIST
=============

* missing base class fields
  2000-12-05  Lars J. Aas  <larsa@sim.no>
  [upwards compatible extension]

  The following base classes have no corresponding fields:
    SbBox2f, SbBox2s, SbBox3f, SbColor4f, SbCylinder, SbLine, SbSphere,
    SbXfBox3f

  A field for every base class is probably not worth implementing, but
  some would be...


* SbVec2i
  2000-12-07  Peder Blekken  <pederb@sim.no>
  [upwards compatible extension]

  It would be very useful to have this class for storing
  2D integer vectors.

  The corresponding field classes should also be added.

  [How about implementing classes SbVec[Single|Double]Float[2|3|4] and
  SbVec[16|32|64]Integer[2|3|4] (perhaps also with "unsigned"
  mutations?), and mapping the original Inventor API classes to these?
  (We'd need some code in a sensible language for autogenerating all
  the C++ code for the class implementations.) 2000-12-07 mortene]

  See also item "SbReal typedef" further down in this file.


* SoGLPrimitiveSet node.
  2000-12-07  Peder Blekken  <pederb@sim.no>
  [upwards compatible extension]

  A node designed for fast rendering, since it's an exact mapping
  on how OpenGL renders shapes, and all information (except current
  material and texture) is stored inside the node. This might be our
  alternative to the (IMHO) silly SoVertexProperty node.

  The node has the following fields:

    SoMFInt32 coordIndex;
    SoMFInt32 rgbaIndex;
    SoMFInt32 normalIndex;
    SoMFInt32 textureCoordIndex;

    SoMFVec3f point;
    SoMFVec3f normal;
    SoMFVec2f texCoord;  // or possibly SbVec4f to support 3D textures
    SoMFUInt32 orderedRGBA;

  All geometry information is inside the node. This will lead to much
  less overhead for each rendered node, which might be important if
  you have lots of nodes in a scene.  Also, this makes it very easy to
  create a display list inside the node, and a much simpler notification
  scheme.

  This node can contain triangles, triangle strips, triangle fans,
  quads, quad strips or polygons. All geometry must be initialized
  with a negative code, and the geometry type will be rendered until
  the next negative code. Since this scheme is an exact mapping of the
  way OpenGL renders geometry, this will lead to maximum performance
  OpenGL rendering. Polygons must of course be convex; polygon
  tessellation will not be performed by this node, as it is designed
  for speed, not flexibility.

  Default texture coordinates will not be generated. If you want
  texture coordinates, supply them yourself. The same goes for normals;
  they will not be generated.

  For material nodes with multiple values per field, only the first
  value per field will be used. Diffuse color and transparency can be
  replaced using an orderedRGBA field inside the node.

  Normal bindings:

  NONE               : when normal and normalIndex are empty
  PER_VERTEX         : when normalIndex is empty
  PER_VERTEX_INDEXED : otherwise

  color and texture bindings use the same scheme.

  For INDEXED bindings, you should put a -1 in the normalIndex,
  rgbaIndex and texCoordIndex fields when there's a negative index
  code in the coordIndex field. This is mostly to make the node a little
  more readable for the human eye.

  It is not possible to specify normals, colors or texcoords
  per face, but this can be achieved with very little overhead using the
  index-fields (it is very rarely used anyway, I think).

  I guess this node is most suited to be computer generated since
  it is easy to make mistakes with all the different coordIndex codes.
  But, experienced OpenGL programmers should be able to use it quite easily.


* More nodes and elements to control GL state.
  2000-12-07  Peder Blekken  <pederb@sim.no>
  [upwards compatible extension]

  Alpha test, blending, stencil etc. We should at least have an
  SoGLAlphaTestElement, since Coin supports alpha test rendering of
  textures.


* Add SoMFMatrix input fields in SoCalculator
  2001-03-29  Peder Blekken  <pederb@sim.no>
  [upwards compatible extension]

  It could be useful to do matrix operations in the calculator, and
  by adding some SoMFMatrix input fields we could do just that.
  Some new functions would be needed of course, such as
  multvecmatrix(), multdirmatrix(), multleft(), multright(),
  inverse() and identity().


* A better hash/dict class than SbDict.
  2001-03-29  Morten Eriksen  <mortene@sim.no>
  [upwards compatible extension]

  Perhaps something like

        SbDictT (templatized key type, void* value type)
          +- SbDict32 (key type == uint32_t)
          +- SbDict64 (key type == uint64_t)
          +- SbDict (key type == unsigned long, for backwards API compatibility)

  Comment by pederb:
    Remember that all template code should be inline, in the SbDict.h
    header file. Otherwise we will run into tons of problems on
    different compilers.

  Update, mortene:
    Perhaps it would be better in the long run to use a "code
    generating" set of #define macros in pure C as the basis for
    SbDict (ie "templatize" our hash-classes the "C-way").  I believe
    they do something like this for hashes in the Linux kernel
    sources.

  Update, mortene 2003-09-12:
    We now have a C hash ADT. (But it is not generic.)

  Update, larsa 2003-11-04:
    Inventor/misc/SbHash.h


* SoGestureEvent
  2001-04-29  Lars J. Aas  <larsa@sim.no>
  [upwards compatible extension]

  Derived from SoEvent, this class would be a container for a gesture type
  indicator (SbName) and a variable set of parameters (name + value).
  Something like this should be implemented to make it easier to create
  gesture-based interfaces...


* SoText2::verticalAlignment / verticalJustification
  2001-04-30  Peder Blekken  <pederb@sim.no>
  [upwards compatible extension]

  I wish for this new field in the node, to be able to control the
  vertical alignment of the strings. Useful if you want to align
  strings at the bottom or centre of something. We could also consider
  adding this field in SoAsciiText and SoText3.


* 3D GUI Components
  2001-05-01  Peder Blekken  <pederb@sim.no>

  It would be very useful to have a set of classes to build simple 3D
  GUIs. A nice approach might be to do something similar to how
  draggers are created -- as nodekits -- with default geometry that
  can be replaced by supplying your own geometry files.

  Examples of useful components: PushButton, ScrollBar, ComboBox,
  RadioButton, LineEdit, Menu?...

  Update, mortene@sim.no 2001-05-01:

    I think we also need to write a "panel" class aswell as layout
    handling to do this properly.

  Update, mortene@sim.no 2001-05-01:

    Or how about "tuning" these common 2D components to better (?) fit
    a 3D environment? I.e. instead of a pushbutton, we could make a
    "pushball", a set of radiobuttons would be a set of "radioballs",
    etc etc.

    Many components are inherently 2D and would be hard to re-make in
    3D, though.

  Update, pederb@sim.no 2001-05-02

    The thought was that the look of the components should be 100%
    configurable through geometry files. If you want to, you should be
    able to create a PushButton that looks like a ball by supplying
    the appropriate geometry file.

    Also, I would like to be able to use the components as 2D GUI
    components. It is very useful for creating an overlay GUI.  I
    wouldn't want to have buttons that looks like a ball for a 2D GUI.


* Less environment pollution
  2001-05-02  Lars J. Aas  <larsa@sim.no>

  Instead of having one environment variable for each togglable option, we
  could use one one variable containing several options.  For instance:

    export COIN_RENDER_CACHING=1
    export COIN_TEX2_BUILD_MIPMAP_FAST=1

  could become:

    export COIN_OPTIONS="+RENDER_CACHING,+TEX2_BUILD_MIPMAP_FAST"

  You could use + (optional) to turn an option on, and - to turn it off.
  One could use ! instead of -, but bash (readline?) doesn't handle use of
  ! as gracefully as it ought to.

  The last ocurrence of an option would be the result of a lookup.  That
  way, you can override previous settings by writing:

    COIN_OPTIONS="$COIN_OPTIONS,-RENDER_CACHING"

  Using a list to assign values (integers and strings) can also be done
  quite easily.  (COIN_OPTIONS="ARBITRARY_LIMIT=512").

  If there are limits to the length of the contents of an environment
  variable, an option is to search the environment for COIN_OPTIONS,
  COIN_OPTIONS2, COIN_OPTIONS3, etc. until there is no environment
  variable with the name of the next variable.  This will unfortunately
  not work with the above scheme of appending overriding options at the
  end of COIN_OPTIONS since you need to know which variable is parsed last.

  ** Comment, mortene 2001-05-02:

    This sounds like a bad idea to me -- trading off env-var pollution
    for obfuscation.

    The pollution doesn't look to be bad, as long as we keep a "COIN_"
    prefix to simulate a separate namespace. And besides, querying and
    setting the single COIN_OPTIONS environment variable would be a
    lot harder from within application /code/ -- think about it..

  ** Answer, larsa

    I was thinking along the lines of having a simple API for this
    functionality.  It's not "a lot harder", and we could add flexibility
    by making variables watchable (callbacks) and other things.

    Another possibility is to have an SoOptions node (or some similar name)
    that could be placed in the scene graph to control some of these options.
    This can be complimentary to the current envvar-scheme.


* SbBool SbMatrix::inversePossible(void) const
  2001-07-02  Peder Blekken <pederb@sim.no>

  It would be useful to have a method to test if it is possible to
  calculate the inverse of a matrix. Right now we check if det4() is
  equal or very close to zero, but I've seen algorithms in GGems
  that use the floating point precision constant (FLT_EPSILON) to
  determine if it's possible to calculate the inverse.

  Update 2001-07-03 mortene: just want to mention that
  SbMatrix::invertible() would be a somewhat smoother name. :-)


* SbList::setEqTester()
  2001-07-03  Marius Bugge Monsen <mariusbu@sim.no>
  (write-up by mortene)

  SbList::find() (and indirectly all methods of SbList using find())
  could be made more flexible if it was possible to register a
  callback function which did the equality testing against the list
  items.

  The full method signature would look something like this:

  class SbList {
    [...]
    typedef SbBool (*SbListEqTester)(const Type item0, const Type item1);
    SbListEqTester * setEqTester(SbListEqTester * neweqtester);
    [...]
  };

  (BTW, the name for this function is crap -- should think of
  something better.)


* SoNode::setOverride() should be made persistent
  2001-07-03  Marius Kintel <kintel@sim.no>
  (write-up by mortene)

  It is now not possible to store override information for nodes
  permanently in scenegraph "dumps" to .iv-files.  Being able to make
  this information persistance would be more convenient for the
  application programmer.

  Note that it is very probable that fixing this would force us to
  break downward and "cross-over" compatibility with earlier Coin
  versions and TGS / SGI Inventor versions of the file format, so it
  is unlikely that we will do anything about this until we'd made our
  own additional file export / import format from scratch.

  Update 2001-07-03 pederb: It would also be nice if setOverride()
  could be done field-by-field, and not just for the entire node.


* SoDB::registerImporter()
  2001-07-06  Marius Kintel <kintel@sim.no>, Peder Blekken <pederb@sim.no>
  (write-up by mortene@sim.no)

  Instead of (or at least in addition to) the silly
  SoDB::registerHeader() function (bad design, as it can only handle
  files with a header looking like the original Inventor and VRML
  stuff) we should perhaps make available a function
  registerImporter() for generally supporting any file format for
  import to Coin scenegraphs.

  Update 2001-09-19 larsa:  I'm experimenting with an ImportKit nodekit
  that could deal with import/export.  Registration (or simply typesystem
  hierarchy traversal) can probably be used in a factory approach for
  supporting foreign formats in an abstract way.


* New node TextureAttribute
  2001-06-07  Peder Blekken <pederb@sim.no>, Morten Eriksen <mortene@sim.no>

  Complexity's textureQuality is kind of outdated, since most OpenGL
  drivers now support linear filtering and mipmapping at no additional
  performance cost when enabled. It would be more useful to be able to
  specify when you want to enable linear filtering and/or mipmapping.

  A TextureAttribute node might contain these fields:

    SoSFBool linearFiltering;
    SoSFBool mipmapping;

    enum ScalePolicy {
      SCALE_DOWN,
      SCALE_UP,        // default
      DONT_SCALE
    };
    SoSFEnum scalePolicy;

    enum LoadPolicy {
      IMMEDIATELY,    // default
      DELAY_LOAD,
      DELAY_LOAD_AND_UNLOAD
    };
    SoSFEnum loadPolicy;


* void SbRotation::getAsEuler(SbVec3f &), void SbRotation::setAsEuler(const SbVec3f &)
  2001-07-15 <mortene@sim.no>

  Should be simple enough, see quateuler.cpp in this directory for the
  code we need for the getAsEuler() method.

  See also SmallChange's Rot2Heading engine.

* SoFocusEvent
  2001-08-15  Lars J. Aas  <larsa@sim.no>
  [upwards compatible extension]

  Derived from SoEvent, this event class would notify the scene when the
  renderarea/viewer has input (event) focus and not.  FOCUS_IN and FOCUS_OUT
  would be the focus change event values.


* SoMarkerSet scaling
  2001-08-24  suggested by Coin-user Nigel Murry, write-up by <mortene@sim.no>
  [upwards compatible extension]

  Add functionality to the SoMarkerSet node to make it possible to
  scale the marker bitmaps.


* SbReal typedef
  2001-09-05  Lars J. Aas  <larsa@sim.no>
  [will force incompatible changes in the API if we want to do this in
  a way which permeates the whole library (which we probably do)]

  SbReal could be either defined as float or double (and even "long double"),
  depending on what precision the developer decided upon at configure time.
  Lots of the API and internals should then be changed to use SbReals instead
  of the fixed float-precision types.  Default would be float, since double
  will break ABI-compatibility.

  Similarly, SbVec2f and SbVec2d would both be fixed to float and double,
  while SbVec2r could change, depending on the definition of SbReal.

  See also item "SbVec2i, SbVec2d, SbVec4d" earlier in this file.


* The SbBool typedef
  2001-09-05  Lars J. Aas  <larsa@sim.no>
  [ABI-incompatible change (mangled function signatures will not be
  the same on converting from int->bool)]

  The SbBool type is always int.  Consider detecting if the bool type exists
  and use it instead when available.  How does this work across multiple
  C++ compilers?  Since they're not ABI-compatible in the first place, this
  change won't hinder anything, will it?

  Update 2001-09-05 mortene: See also FIXME comment near the top of
  include/Inventor/SbBasic.h.in.

  Update 2002-04-18 mortene: Perhaps not such a good idea after all,
  as SbBasic.h should also be available to use from C code.


* Make APIs for engine classes more consistent.
  2001-09-11  Karin Kosina <kyrah@sim.no>, write-up by <mortene@sim.no>

  Instead of a field called "enable" for some engines, "disable" in
  others and yet again "on" in others, use a consistent single name
  (but provide backward compatibility).

  Update 2001-09-19 larsa:  You also have inconsistencies in method names
  wrt the notification mechanism, I think.


* SoInput::setStrings(char **)
  2001-09-16  Lars J. Aas  <larsa@sim.no>
  [ABI-incompatible change (all things in SoInput is virtual, so this should
   probably be virtual too]

  Writing out scene graphs in strings and creating scene graphs of them by
  reading them with SoInput::setBuffer() is very convenient, but very long
  strings is not portable, meaning you have to implement buffer allocation
  and string concatenation before using SoInput::setBuffer().
  The idea behind setStrings() is that you create a NULL-terminated string
  array of shorter strings, and read from that array as if it was a buffer
  of concatenated strings.


* SoInput/SoOutput alternative
  2001-09-16  Lars J. Aas  <larsa@sim.no>

  The SoInput / SoOutput classes are very messy.  Although they have
  lots of virtual methods, they are almost impossible to derive to
  change their behaviour (like I/O through network connections and
  compression libraries).  A simpler, cleaner, more flexible /
  extendible alternative should be created and allowed to be used as
  an alternative to these classes.

  Update 2002-04-18 mortene: I think I would prefer the following
  actions when solving this: 1) extract the functionality of these
  classes into "pure" C constructions / code with cleaner & better
  design, 2) layer the old SoInput and SoOutput classes on top of
  these new implementations.


* SoAction::apply(SoAction * beingApplied)
  2001-09-20  Lars J. Aas  <larsa@sim.no>
  [upwards compatible extension]

  If you need to apply an action as a result of an event during an action
  traversal, it is very inconvenient to have to figure out what that action
  was applied to and then apply the other action to the same thing.

  This method should be a shortcut for calling beingApplied->getWhatAppliedTo()
  and then switch/case the correct this->apply(beingApplied->get*AppliedTo())
  method.

  Method does not need to be virtual (no ABI problems) since it only forwards
  to three other virtual methods.


* SbFile
  2001-09-26  Morten Eriksen  <mortene@sim.no>
  [upwards compatible extension, internal design cleanup]

  Problem: there's now a fair deal of code spread around in the
  library for doing misc "low-level" file operations which may or may
  not be OS-dependent. Examples: stat() operations (function is named
  differently on UNIX and MSWin systems) for testing presence of files
  or file sizes, path / basename splitting (different for UNIX and
  MSWin), etc etc.

  These operations should be abstracted into a common class to handle
  certain file and directory operations, because it would clean up the
  design and make the chance for bugs slimmer by collecting all the
  different OS-specific code in a common place.

  A couple of advices for any designer and / or implementer of this
  class:

     0) I _think_ it'd be wise to use a single class for both the
        "file" abstraction and the "directory" abstraction -- like all
        UNIX systems do (ie; directories are just files with other
        files in them). So we only need a "SbFile", not a
        "SbDirectory".

     1) Please check the design of available software units of this
        type before starting the implementation -- I've at least heard
        good things about the abstractions employed in the Common Lisp
        specification.  There's no point in reinventing the wheel
        _completely_ from scratch, and constructing something which is
        capable of working on the more obscure platforms out there
        also is not as trivial as it may seem.

     2) It would IMO be preferrable to have this class implemented in
        "pure" C, for easier duplication into any other project /
        library, plus because we'd like to re-write many of the Sb*
        classes, So*Error classes and some other Coin classes in C
        some time in the future for various reasons.

  (If #2 is heeded, "SbFile" should be just a wrapper C++ class around
  the C struct(s) and functions of the "real" implementation.)


* SoField::setValidator(SoValidator *)
  2001-12-05  Morten Eriksen & Peder Blekken
  [upwards compatible extension]

  A generic mechanism for controlling the valid range of a field would
  be *very* useful. It could for instance help application programmers
  better limit the end-users' freedom to do stupid things with the
  dragger classes.


* SoKeyboardEvent::Key enums
  2002-01-04  Lars J. Aas  <larsa@sim.no>
  [upwards compatible extension]

  The Key enum is lacking lots of keys, and seems to be designed for the
  US keyboard map.  It should at least be extended to include the full
  7bit ASCII set of characters so e.g. non-keypad '+' can be used.
  A more dynamic scheme would be preferable, but as a first measure this
  should be fixed.

  UPDATE 2005-06-09 mortene: below follows a good example of typical
  problems with the current code/interface. Try hitting SHIFT + '0'
  and SHIFT + '9' on a Norwegian keyboard -- the results are very
  confusing.

  ---------8<--------------- [snip] ---------------------8<---------------
  #include <Inventor/@Gui@/So@Gui@.h>
  #include <Inventor/@Gui@/viewers/So@Gui@ExaminerViewer.h>
  #include <Inventor/nodes/SoEventCallback.h>
  #include <Inventor/nodes/SoSeparator.h>
  #include <Inventor/nodes/SoCube.h>
  #include <Inventor/events/SoKeyboardEvent.h>

  static void
  event_cb(void * userdata, SoEventCallback * node)
  {
    const SoEvent * event = node->getEvent();
    SoKeyboardEvent *keyboardEvent;
    SbBool ctrl = event->wasCtrlDown();
    SbBool shift = event->wasShiftDown();

    if (event->isOfType(SoKeyboardEvent::getClassTypeId())) {
      keyboardEvent = (SoKeyboardEvent*) event;

      const char c = keyboardEvent->getPrintableCharacter();
      printf("keyboardEvent->getPrintableCharacter() == %c\n", c);

      if (SoKeyboardEvent::isKeyPressEvent (keyboardEvent,SoKeyboardEvent::NUMBER_0)) {
        if (ctrl) {
          fprintf(stderr,"ctrl 0\n");
        }
        else {
          if(shift) {
            fprintf(stderr,"shift 0\n");
          } else {
            fprintf(stderr,"key 0\n");
          }
        }
        return;
      }
    }
  }

  int main(int argc, char ** argv)
  {
    @WIDGET@ window = So@Gui@::init(argv[0]);

    SoSeparator * root = new SoSeparator;
    root->ref();
    root->addChild(new SoCube);

    // create an Inventor viewer
    So@Gui@ExaminerViewer * ex1 = new So@Gui@ExaminerViewer(window);

    SoEventCallback * event = new SoEventCallback;
    event->addEventCallback(SoKeyboardEvent::getClassTypeId(),
                            event_cb, ex1);
    root->addChild(event);

    ex1->setSceneGraph(root);
    ex1->show();
    So@Gui@::show(window);
    So@Gui@::mainLoop(); // go
    delete ex1;

    root->unref();

    return 0;
  }
  ---------8<--------------- [snip] ---------------------8<---------------

  The behavior is strange, but I believe this is actually how SGI
  Inventor works aswell, so it's not exactly a bug.

  To go ahead and fix it properly, I believe the correct thing to do
  would be to add a replacement for SoKeyboardEvent in Coin (keeping
  backward compatibility, so I guess it must _supplement_
  SoKeyboardEvent, not really replace it).


* SoSwitch::whichChild as an SoMFBool
  2002-01-15  Morten Eriksen  <mortene@sim.no>
  [compatibility-breaking change]

  This field should really have been a set of boolean ON / OFF values
  from the start if it was designed properly, IMNSHO. As it is now, it
  is basically limited to show just a single of the children subgraphs
  (with the added enum-define "design hacks" to also show all or none,
  with SO_SWITCH_ALL and SO_SWITCH_NONE).

  With a set of booleans, it would be completely flexible in the sense
  that one would get full control over the visibility of each and
  every child subgraph, plus we could get rid of the enum-define
  hacks.

  I guess we should consider implementing this scheme in a new
  switch-type node instead of breaking compatibility in such a severe
  way (which would be bad for file format compatibility, among other
  reasons).

  Update 2002-02-06 larsa:

  * A "Switchboard" node with these properties has been implemented, and
    is awaiting future inclusion in the Coin library.


* SoMouseButtonEvent::isDoubleClick()
  2002-01-16  Lars J. Aas  <larsa@sim.no>
  [probably upwards compatible]

  Must be accompanied with some double-click preference/config setting
  functions too.  Might even consider putting it on the SoButtonEvent
  level.

  Update 2002-01-20 mortene:

    * See So*/src/Inventor/*/common/docs/api-wish-list.txt for
      additional information.

    * About the suggested config setting: the doubleclick rate should
      preferably be extracted from the underlying OS or GUI-toolkit by
      the So* library when converting a native event into an
      SoMouseButtonEvent.


* SbBigNum type
  2002-01-17  Lars J. Aas  <larsa@sim.no>
  [upwards compatible extension]

  ...with corresponding SbVec and field types.


* SoOffscreenRenderer::render(SoPathList &)
  2002-02-13  Peder Blekken  <pederb@sim.no>, write-up by <mortene@sim.no>

  Would of course be extremely useful for rendering selected parts of
  the scenegraph, and should even be part of the API just for
  consistency reasons versus SoGLRenderAction.

  (Perhaps a better, more general solution would be to just add
  SoOffscreenRenderer::prepareForRendering(), and let the application
  programmer apply his own SoGLRenderAction?)


* Support for field value expressions in Inventor ascii files
  2002-03-18  Peder Blekken <pederb@sim.no>

  It would be very useful to allow field value expressions. E.g. for
  an SoSFVec3f, you should be able to write:

  SomeNode {
    somefield (3500+4500) (1300+5600) (2300/3.0-1230*1.2)
  }

  In this example I just used parentheses to signal begin/end expression.
  I'm not sure if this is the best solution though.


* SoGLTeaPot
  2002-04-01  Lars J. Aas  <larsa@sim.no>
  [upwards compatible extension]

  A node that will render the commonly used tea pot shape.

  Update, mortene 2004-07-10: should be an easter egg, i.e. not
  disclosed in API-doc on doc.coin3d.org, don't install header file,
  etc.  Would be a cool and good learning introduction task for a new
  developer, e.g. a summer intern.


* SoSearchPathAction (which is part of the TGS Inventor API)
  2002-04-19  Morten Eriksen  <mortene@sim.no>

  Requested by Matt Verona on comp.graphics.api.inventor. Matt
  suggests using the tokenizer classes from the Boost freeware class
  library (see the Coin/docs/misc-resources.txt file).


* Rewrite non-member/friend operator methods for the base classes.
  2002-06-05  Kristian Eide, write-up by <mortene@sim.no>
  [breaks ABI, but API-compatible in both directions]

  This:

    friend SbMatrix operator *(const SbMatrix &m1, const SbMatrix &m2);

  can for instance be rewritten as this, with the exact same
  semantics:

    SbMatrix SbMatrix::operator*(const SbMatrix &m);

  Rewriting these should be done for two reasons: 1) the member
  operator-functions can be made more efficient, as they can access
  the private data of the class-instances directly, 2) it looks
  cleaner.

  Note that not *all* of them can be converted, like for instance this
  one, which has a native type on the left side of the binary
  *-operator:

    friend SbVec3f operator *(float d, const SbVec3f &v);


  Note also that these changes would break the ABI, so this would have
  to be done for the next major release.


* Detect and support libtar if present, and update SoInput accordingly.
  2002-08-30  Lars J. Aas  <larsa@sim.no>

  If you could bundle your inventor model, and all external texture
  files and .iv files in a tar archive (possibly compressed), and
  still load it and its sub-files with Coin, that would be a huge gain.
  The library "libtar" (BSD-licensed, freshmeat) would enable us to do
  this.

  Typically, the basename of the tar-file would be used as the basename
  of the Inventor model file loaded from the archive.  That way, you
  could untar multiple such bundles in the same dir, and not worry
  about overwriting some "default" filename for the root Inventor file.
  This has the disadvantage of making it impossible to rename the bundle
  file though.

  Another option is to load the first .iv-file found in the bundle as
  the root file.  Libtar will probably allow us to inspect this kind
  of stuff quite easily.

  A new write-action (or extensions to the existing one) is needed so
  Coin can generate such bundles automatically, moving referenced files
  and textures into the being-written bundle.  If bundles always had to
  be created manually (which is acceptable in the development phase),
  the point would kind of be gone.

  URL: http://www-dev.cso.uiuc.edu/libtar/

    void SoWriteAction::setTarBundlingEnabled(SbBool bundling);
    SbBool SoWriteAction::isTarBundlingEnabled(void) const;


* Prettier SoWriteAction .iv-formatting
  2002-09-22  Lars J. Aas  <larsa@sim.no>

  I'm not to happy with the spacing/indentation of SoWriteAction.  I
  believe the current output is more or less equivalent on the bit-level
  to what SGI Inventor writes, but it's not the most easy formatting for
  the eyes.  It seems to be designed for a tab-width setting of 4, and lacks
  linebreaks after close brackets, and has line breaks before node
  lines instead or something.

  I therefore propose adding a get/set SbBool flag for TAB-less, properly
  line-broken indentation in SoWriteAction.

  What I want is more or less like this (note the control characters):

   $ sed -e 's/^I/    /g' -e 's/}/}^M/g' <input.iv \
     | tr '\r' '\n' \
     | sed -e '3,$ { /^$/ d; }' >output.iv

    void SoWriteAction::setCoinFormattingEnabled(SbBool bundling);
    SbBool SoWriteAction::isCoinFormattingEnabled(void) const;


* Output .iv-files with CR/LF on Win32 systems
  2002-11-15  Lars J. Aas  <larsa@sim.no>
  [upwards compatible extension]

  On Windows systems, it would be better to write scene graph files with
  \r\n instead of just \n.  This should be configurable through a function
  call somewhere, and the default should be decided by what kind of system
  Coin was configured on.

  This should hopefully go in before the 2.0 release.


* SoViewportEvent
  2003-02-11  Lars J. Aas  <larsa@sim.no>

  If you have scene graphs that have fields that are adjusted in relation
  to the viewport size, the way to detect viewport changes now is to get the
  viewport information from the SoGLRenderAction action since it's the first
  action that happens after the viewport is changed.  Updating fields at that
  time is already too late - the notification mechanism will trigger another
  redraw so you get two redraws when you resize the viewport.  By first
  sending a "viewport" event through the scene, fields can be updated in
  advance and the render pass won't trigger a second one.

* Extending SoInput to support callbacks for file operations
  2003-02-21  Thomas Hammer  <thammer@sim.no>

  I suggest we add a static function to SoInput to set (user-supplied)
  callbacks for opening, reading, (possibly seeking and "telling" file
  position) and closing a datastream (which internally in SoInput
  would be handled allmost identically to a file).

  The callbacks would look something like this:

  void * (*open_func)  (const char *filename,
                        ... maybe some more params here?)
  size_t (*read_func)  (void *ptr, size_t size, size_t nmemb,
                        void *datasource);
        // datasource is whatever open_func returns,
        // could be a filehandle, or not.
  int    (*seek_func)  (void *datasource, int64 offset,
                        int whence);
  int    (*close_func) (void *datasource);
  int64  (*tell_func)  (void *datasource);

  This is approx. how vorbisfile does it. See

  http://www.xiph.org/ogg/vorbis/doc/vorbisfile/callbacks.html

  This way it's the applications responsibility to do file i/o,
  streaming, decompressing, or whatever.

  I use this mechanism in simage to get around any problems with
  passing filehandles to the "normal" (stdio) libvorbisfile API. See
  simage/src/simage_oggvorbis_reader.c.

  I'm not sure this mechanism is sufficient for texture-reading
  though, because the open_func callback might need some more info
  about where the texture file is located.  A relative path might not
  be enough, since the scenegraph might have been generated from
  several VRML2 files with identical textturefilenames (but different
  textures).



IMPLEMENTED, RESIDING IN SmallChange
====================================

* SoDepthBuffer, SoGLDepthBufferElement
  2000-12-07  Peder Blekken  <pederb@sim.no>
  [upwards compatible extension]

  This node and element would really be useful to be able to
  control the depth buffer in a scene graph. It's already
  implemented, and I use it all the time in internal projects.

  In addition, the element would really be useful when rendering
  SoAnnotation nodes.


* SoViewportRegion
  2000-12-07  Peder Blekken  <pederb@sim.no>
  [upwards compatible extension]

  This node could also be useful to a lot of people, I think. I've
  seen postings on comp.graphics.api.inventor on people using
  SoCallback nodes to change the viewport in a scene graph.
  It would be much easier to use a node for doing this. The element
  is already part of the Open Inventor API so it's a really
  simple node.

  This node is implemented and works like a charm.


* Coinboard node
  2000-12-07  Peder Blekken  <pederb@sim.no>
  [upwards compatible extension]

  Silly name for a node, I know, but Billboard is already taken by
  VRML97. In my implementation it is actually a shape node which can
  be directed towards the camera, and the shape can be rendered in
  multiple positions, controlled by an SoMFVec3f. This is very useful
  and much more optimal than using a node derived from SoGroup
  (there is quite a lot of overhead in the GLRender()-method of a
  shape node (initialize material, find bindings, evaluate lazy
  elements etc), and since (usually) all shapes are equal under a
  Billboard shape node, it's just silly to do this repeatedly for all
  shapes. We should have a normal SoGroup-inherited Billboard node
  also, I guess.

  This node is typically used for rendering simple shapes with a
  alpha-transparent texture, such as trees in terrain, particles or
  other billboards. Unfortunately, this will not work properly
  in SGI or TGS Inventor, since they don't support alpha test
  rendering of textured shapes.

  This node is only partly implemented (generatePrimitives() is missing).


* SoEnvironment::fogStart field.
  2000-12-07  Peder Blekken  <pederb@sim.no>
  [upwards compatible extension]

  Why, oh why didn't SGI include this field when designing the
  Environment node? It makes it possible to set the distance at
  which fog starts for linear (HAZE) fog. I've already added support
  for this in SoEnvironmentElement and SoGLEnvironmentElement.


* SoSkyDome node.
  2000-12-07  Peder Blekken  <pederb@sim.no>
  [upwards compatible extension]

  This node renders a skydome which can be connected to the camera
  to create a nice, global environment in your applications. The
  node has the following fields:

    SoSFFloat startAngle;
    SoSFFloat endAngle;
    SoSFInt32 numStacks;
    SoSFInt32 numSlices;
    SoSFFloat height;
    SoSFFloat radius;

  This makes it possible to draw a partial (or full) sphere, and the
  current texture is mapped from startAngle (t=0) to endAngle (t=1).
  The s texture coordinate is mapped in the same way as SoSphere.

  This node is partly implemented (only GLRender()-method so far).