Wiki improvements

[fxm]

@admins and others,

• Similarly to the page "EVENT (message data from ScreenEvent)" at "KeyPgEvent" of documentation, I think we should add a page "FBARRAY (array descriptor structure and access)" at "/wiki/KeyPgFBArray" with description and usage example, usable from fbc version 1.08.
• And therefore probably suppress the last paragraph "Array Descriptor" at the page "Arrays" of development documentation to avoid duplication of the array descriptor structure definition (because all this information will be reported on the future dedicated page).

What do you think?

[Juergen Kuehlwein]

Yes, make an extra page for the decriptor description :-).

And ... thanks for your efforts getting and keeping the help files up-to date!

[fxm]

Similarly to the page "EVENT (message data from ScreenEvent)" at "KeyPgEvent" of documentation, I think we should add a page "FBARRAY (array descriptor structure and access)" at "/wiki/KeyPgFBArray" with description and usage example, usable from fbc version 1.08.

Jeff,

• Presently, './inc/fbc-int/array.bi' only compiles in '-lang fb' dialect.
  Is it definitive?
• But anyway it would be more logical to remove the prefix 'FBC.' everywhere inside the (conditional) namespace, as it is done for all other symbol names (used without prefix):
  declare function ArrayDescriptorPtr alias "fb_ArrayGetDesc" ( array() as any ) as FBC.FBARRAY ptr
  declare function ArrayConstDescriptorPtr alias "fb_ArrayGetDesc" ( array() as const any ) as const FBC.FBARRAY ptr

[fxm]

Similarly to the page "EVENT (message data from ScreenEvent)" at "KeyPgEvent" of documentation, I think we should add a page "FBARRAY (array descriptor structure and access)" at "/wiki/KeyPgFBArray" with description and usage example, usable from fbc version 1.08.

Done:
- KeyPgFBArray → fxm [new page created]
- CatPgFullIndex → fxm [added link to "FBARRAY (array descriptor structure and access)" page]
- CatPgFunctIndex → fxm [added link to "FBARRAY (array descriptor structure and access)" page]
- CatPgArray → fxm [added link to "FBARRAY (array descriptor structure and access)" page]
- PrintToc → fxm [added link to "FBARRAY (array descriptor structure and access)" page]

[Juergen Kuehlwein]

Thanks, explains this topic comprehensive and exhaustive. Maybe you should print the memory addresses (@array descriptor, pd->index_ptr and pd->base_ptr) in your example code in hex?

[fxm]

Maybe you should print the memory addresses (@array descriptor, pd->index_ptr and pd->base_ptr) in your example code in hex?

Done.

[fxm]

And therefore probably suppress the last paragraph "Array Descriptor" at the page "Arrays" of development documentation to avoid duplication of the array descriptor structure definition (because all this information will be reported on the future dedicated page).

Jeff,

Or else replace the contents of this paragraph with only a link to the new page?
That's what I did for now:
- DevArrays → fxm [contents of the paragraph "Array Descriptor" reported in the new page "KeyPgFBArray" and replaced with a link]

[fxm]

If someone else could fill in the last two remaining pages "Graphics / External Graphics File Formats" and "Making Binaries / Executables" (it's outside of my skills), it would be nice to finally have a complete Programmer's Guide.

- For executables topic: I think this should describe the components: (object modules and/or import library and/or library) => executable.
- For external graphics file formats topic: what is supported by BLOAD & BSAVE. To be cross platform, the QB/BMP formats that can be loaded/saved are hard coded in the rtlib. So, this is will be a description of what is specifically supported by the rtlib.

No volunteers for these 2 pages?
Still, it seems to me that there are skills on these two topics on the forum and that they could (by taking a little bit of their personal time) easily produce at worst a draft that I could then incorporate into the Programmer's Guide.

[badidea]

If someone else could fill in the last two remaining pages "Graphics / External Graphics File Formats" and "Making Binaries / Executables" (it's outside of my skills), it would be nice to finally have a complete Programmer's Guide.

- For executables topic: I think this should describe the components: (object modules and/or import library and/or library) => executable.
- For external graphics file formats topic: what is supported by BLOAD & BSAVE. To be cross platform, the QB/BMP formats that can be loaded/saved are hard coded in the rtlib. So, this is will be a description of what is specifically supported by the rtlib.

No volunteers for these 2 pages?
Still, it seems to me that there are skills on these two topics on the forum and that they could (by taking a little bit of their personal time) easily produce at worst a draft that I could then incorporate into the Programmer's Guide.

Concerning 'external graphics file formats':

When working with a 32-bit screen and bitmaps (BMP-files), which is 90+% of the use I expect, things are simple and the guide can be short.

If however other numbers of bits (and conversion between them), palettes, QB-raw, FB-raw need to be included, it will be a lengthy guide.
I am not too enthusiastic to look into and document that stuff.

Another valuable addition could be how to work with other (non-native) formats (PNG, JPG). Which libraries to use.
But that is not really documentation of freeBASIC?

[coderJeff]

fxm, I think I see what you are going for by including the array descriptor outside of the "dev" pages similar to EVENT structure but I feel there is one major difference compared to EVENT. I think the intent is that the raw array descriptor is targeted towards the advanced/developer user only. Exposing the array descriptor is "safe" but only if the programmer knows how several other fbc internals also work.

[fxm]

Do you want to go back by deleting the new page 'KeyPgFBArray' and restoring the paragraph "Array Descriptor" in the page 'DevArrays'?
(or an intermediate solution?)

Note: for about 2 days, access to the wiki has become much slower than before (the forum access time remains good).

[coderJeff]

No, I don't want you to delete what you have already done. The array descriptor is only the first low level thing we have tried to expose in a somewhat documented and "reliable" way. I put 'reliable' in quotes because hopefully, developers still have some flexibility to change this internal as needed. Let's just see how it works out. If it works out, we keep it. If it doesn't work out, we can try something else. I think that is fair.

[fxm]

In the "Description" section of this new page (KeyPgFBArray), I will add a warning note just before the detailed description of the different descriptor fields.

After updating the page accordingly (update in red):

FBARRAY (array descriptor structure and access)

.....
.....
.....

Usage:

• #include once "fbc-int/array.bi"
  using FBC
  
  ' then:
  [list]
  Dim pd As FBARRAY Ptr
  ...
  pd = ArrayDescriptorPtr ( array() )

' or safer:

• Dim pd As Const FBARRAY Ptr
  ...
  pd = ArrayConstDescriptorPtr ( array() )[/tt]

[/list]
Parameters:

• pd
  • The name of a pointer to the array descriptor
  array
  • The name of the array for which one want to access its descriptor

Description:

• At compile time, fbc allocates an array descriptor to store and track information about the array.
  
  If the number of dimensions is unknown at compile time, then the full FB_MAXDIMENSIONS is allocated in the dimTb() field. Otherwise, if the number dimensions is known at compile time, then only the number of dimensions needed are allocated. Therefore the allocated FBARRAY data may be smaller than the declared FBARRAY structure.
  
  If an array is passed as argument to a procedure, an array descriptor is allocated. However, if the array is static, fixed length, and never passed as an argument, then all information about the array is known at compile time, including memory locations, and the allocation of a descriptor is optimized out, since all expressions involving the array are compile time constant.
  
  The array descriptor may also be allocated at run time, as would be in the case of allocating a new UDT containing a variable-length array field member.
  
  WARNING: It is inadvisable (especially for a non advanced user) to change the data values ​​of the array descriptor (internal structure of the compiler).
  For that, it is safer to use rather the function ArrayConstDescriptorPtr() initializing a pointer declared As Const FBARRAY Ptr (or implicitly declared in this way by Var).
  
  FBARRAY.index_ptr
  • Pointer to the array data @array(0, 0, ...). This pointer may be outside of the actual array data as a kind of virtual pointer to use when calculating offsets using indexes in to the array.
  FBARRAY.base_ptr
  • Pointer to the array's memory at the array's lowest bound. For variable-length arrays allocated at run time, this points to the allocated memory region (i.e. malloc)
  FBARRAY.size
  • Total size in bytes of the array data. Size is equal to total number of elements in the array (all dimensions) multiplied by element length. i.e. size = dimTb(0).elements * element_len + dimTb(1).elements * element_len + ...
  .....
  .....
  .....

[fxm]

Done;
KeyPgFBArray → fxm [Adding warning note on changing values of array descriptor]

[D.J.Peters]

Hello fxm
in the compiled help file there is
base -> constructor like base(1,2,3)
and
base -> member access like base.method(1,2,3)
but what are with
base -> operator access !

is it missing or I'm blind ?

in case of missing can you add it to the online wiki please ?

thank you

Joshy