Wiki improvements

Forum for discussion about the documentation project.
fxm
Posts: 9310
Joined: Apr 22, 2009 12:46
Location: Paris suburbs, FRANCE

Re: Wiki improvements

Postby fxm » Nov 16, 2019 7:39

@admins and others,

  • Similarly to the page "EVENT (message data from ScreenEvent)" at "/wiki/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
Posts: 272
Joined: Mar 07, 2018 13:59
Location: Germany

Re: Wiki improvements

Postby Juergen Kuehlwein » Nov 16, 2019 17:52

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

And ... thanks for your efforts getting and keeping the help files up-to date!
fxm
Posts: 9310
Joined: Apr 22, 2009 12:46
Location: Paris suburbs, FRANCE

Re: Wiki improvements

Postby fxm » Nov 17, 2019 7:52

fxm wrote:Similarly to the page "EVENT (message data from ScreenEvent)" at "/wiki/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
Posts: 9310
Joined: Apr 22, 2009 12:46
Location: Paris suburbs, FRANCE

Re: Wiki improvements

Postby fxm » Nov 17, 2019 14:45

fxm wrote:Similarly to the page "EVENT (message data from ScreenEvent)" at "/wiki/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
Posts: 272
Joined: Mar 07, 2018 13:59
Location: Germany

Re: Wiki improvements

Postby Juergen Kuehlwein » Nov 17, 2019 21:58

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
Posts: 9310
Joined: Apr 22, 2009 12:46
Location: Paris suburbs, FRANCE

Re: Wiki improvements

Postby fxm » Nov 17, 2019 22:30

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

Done.
fxm
Posts: 9310
Joined: Apr 22, 2009 12:46
Location: Paris suburbs, FRANCE

Re: Wiki improvements

Postby fxm » Nov 18, 2019 6:32

fxm wrote: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
Posts: 9310
Joined: Apr 22, 2009 12:46
Location: Paris suburbs, FRANCE

Re: Wiki improvements

Postby fxm » Nov 21, 2019 7:16

fxm wrote: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.
coderJeff wrote:- 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
Posts: 1617
Joined: May 24, 2007 22:10
Location: The Netherlands

Re: Wiki improvements

Postby badidea » Nov 21, 2019 22:20

fxm wrote:
fxm wrote: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.
coderJeff wrote:- 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
Site Admin
Posts: 3135
Joined: Nov 04, 2005 14:23
Location: Ontario, Canada
Contact:

Re: Wiki improvements

Postby coderJeff » Nov 30, 2019 13:01

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
Posts: 9310
Joined: Apr 22, 2009 12:46
Location: Paris suburbs, FRANCE

Re: Wiki improvements

Postby fxm » Nov 30, 2019 13:25

Do you want to go back by deleting the new page '/wiki/KeyPgFBArray' and restoring the paragraph "Array Descriptor" in the page '/wiki/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
Site Admin
Posts: 3135
Joined: Nov 04, 2005 14:23
Location: Ontario, Canada
Contact:

Re: Wiki improvements

Postby coderJeff » Nov 30, 2019 16:41

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
Posts: 9310
Joined: Apr 22, 2009 12:46
Location: Paris suburbs, FRANCE

Re: Wiki improvements

Postby fxm » Nov 30, 2019 17:38

In the "Description" section of this new page (/wiki/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:
      Dim pd As FBARRAY Ptr
      ...
      pd = ArrayDescriptorPtr ( array() )
    ' or safer:
      Dim pd As Const FBARRAY Ptr
      ...
      pd = ArrayConstDescriptorPtr ( array() )

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
Posts: 9310
Joined: Apr 22, 2009 12:46
Location: Paris suburbs, FRANCE

Re: Wiki improvements

Postby fxm » Dec 01, 2019 5:51

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

Return to “Documentation”

Who is online

Users browsing this forum: No registered users and 1 guest