Add extra pointer types to keep things tidy

[flowCRANE]

The source code for these headers uses various data types, with aliases included. I don't know exactly how many of them there are, but some of them don't have declared pointer equivalents, so you have to declare them yourself, apart from the code of the headers library.

One such example is TSDL_JoystickPowerState. This is a dedicated integer type, but there is no pointer equivalent — there is no PSDL_JoystickPowerLevel declared anywhere. A good practice would be to add missing pointer types to the library for each existing non-pointer data type.

---

BTW: Why the TSDL_JoystickPowerState is declared as Integer?

type
  TSDL_JoystickPowerLevel = type Integer;

The same with TSDL_JoystickType:

type
  TSDL_JoystickType = type Integer;

If cint* and cuint* types are used everywhere else, it's fine to actually use them everywhere to keep things tidy.

[Free-Pascal-meets-SDL-Website]

Well, in principle I agree. As we try to stay as close as possible to the header code we don't declare pointer types if they are not explicitly declared or (actually) used in any function or other structure. I wonder if your good practice point (which is very valid) should be considered though. @suve

I fully agree about the Integer types, thanks for the hint. Please, feel invited to craft a patch.

Best regards

[suve]

My impression is that so far, pointer types were added as needed, i.e. if the C headers contained *SDL_Something somewhere, we'd add PSDL_Something = ^TSDL_Something. In C, pointers are not a problem, since you an just write SDL_Something *variable and there you go; but Var Variable: ^TSDL_Something is not valid syntax in Pascal and you *need* a separate pointer type declaration. So yes, we could sweep through the code and add a pointer type definition for every SDL typedef; it might not be needed for the units to work, but if it makes it easier to use them, then it's still worth it.

[flowCRANE]

[…] but Var Variable: ^TSDL_Something is not valid syntax in Pascal and you need a separate pointer type declaration.

Wait, it is a valid syntax for Pascal languages — you can declare a variable in such a way. However, this syntax is only available for variables. For function parameters, such a syntax is unacceptable — you must have a separate pointer type declared.

That is why I propose to add the pointer equivalents of all non-built-in types that are used in the header library. Thanks to this, you will be able to use this headers in any way and use all types of data without having to declare it yourself.

In my code, if I declare some main datatype, I automatically declare two pointer types as well. Example:

type
  TGame_Stick = record // main data type
    // some data
  end;

type                          
  PGame_Stick  = ^TGame_Stick; // single pointer
  PPGame_Stick = ^PGame_Stick; // double pointer

If I need to use a pointer type, I will always have it available. And if I never use it, it is not a problem — its existence does not interfere with the operation of the code in any way. It is better to have a complete set of data types and not use all of them than to have too few and have to create them yourself.

[Free-Pascal-meets-SDL-Website]

That is why I propose to add the pointer equivalents of all non-built-in types that are used in the header library. Thanks to this, you will be able to use this headers in any way and use all types of data without having to declare it yourself.

its existence does not interfere with the operation of the code in any way. It is better to have a complete set of data types and not use all of them than to have too few and have to create them yourself.

I understand and agree that an additional pointer type is very convenient.

The drawbacks are:

• they introduce the declaration of pointer types which are not explicitly found in the original headers (which may make the process of translation confusing sometimes)
• the units would have to be updated to add all the missing pointer types
• translators need to know that they always should add the pointer type

The following proposal stems from the idea that it is more important to have a new typedef introduced at all, rather than having the corresponding pointer type ready for convencience.

Proposal to handle convenient pointer types:

• we add a hint to the translation guidelines that we encourage everybody to add the pointer types (but it is no must atm.) - so we are free to merge pull requests which may not follow this hint
• add the pointer type in the cheatsheet code examples
• we try to follow this rule as much as possible ourselves
• in the long run the hint could be transformed into a rule

Should we do it this way?

Btw.: I wonder if the double pointer is also necessary?

Best regards Matthias

[flowCRANE]

The drawbacks are:

• they introduce the declaration of pointer types which are not explicitly found in the original headers (which may make the process of translation confusing sometimes)

And the library doesn't have to contain only those data types that are originally declared. Pascal is not C — you can't do it like in C (declare parameters as typed pointers), so the SDL headers should not only be ported, but also adapted to a different technology, which Pascal definitely is.

I don't consider it a drawback, but a solution to the problem with the different specificity of these languages.

Btw.: I wonder if the double pointer is also necessary?

See what the Free Pascal standard library looks like — it has pointer types as well as double pointers and even triple pointers (eg PPPAnsiChar ond others). It doesn't matter if the library somewhere uses these types or not. They exist because the user may need such types. Transferring the obligation to declare data types onto the user may harm this user — it is better to declare these types yourself in such a way that they are always compatible with the operation of the library.

Rather, I'd be inclined to do the same, which is to declare single, double, and triple pointers. But that's just my opinion and I don't want to interfere with your work or force anything, so take it just as a suggestion.

[Free-Pascal-meets-SDL-Website]

so the SDL headers should not only be ported, but also adapted to a different technology, which Pascal definitely is.

Again, I see your points and basically agree. I tried to lay out in my last response that it is not about if having additional pointer types would be preferable but rather that we as a community project have limited resources and the focus should lay on adding missing and new declarations. - Hence the idea to propose adding pointer types but not to force it by rule for the moment.

I don't consider it a drawback, but a solution to the problem with the different specificity of these languages.

The term "drawback" was not directed at the solution with the pointer declaration itself, but solely at the process of the translation as it complicates some aspects and needs more resources.

@furious-programming What are the undefined pointer types you use most regularly which are not available in the units, yet?

it might not be needed for the units to work, but if it makes it easier to use them, then it's still worth it.

@suve To which pointer level we should support them: single, double, triple pointers?

[flowCRANE]

Again, I see your points and basically agree. I tried to lay out in my last response that it is not about if having additional pointer types would be preferable but rather that we as a community project have limited resources and the focus should lay on adding missing and new declarations. - Hence the idea to propose adding pointer types but not to force it by rule for the moment.

Yep, I get it.

What are the undefined pointer types you use most regularly which are not available in the units, yet?

It's not the point. The thing is, I needed to use a pointer type whose declaration I expected to be in the headers, but I didn't find it. A type that is not used in function headers, but that is strongly related to the types that are actually used. I was surprised that there is no such type, because I expect the API to meet my needs. On the other hand, your library contains a declaration of simple type aliases, which are plentiful and I doubt they are all used. So I notice a slight inconsistency.

I suggested adding pointer types for all SDL header-specific data types for two reasons. The first is that we don't know what the header user will need, so it's a good idea to take care of the full set of data types. Secondly, because these are headers for Pascal, and in Pascal we can't declare parameters like in C, i.e. by adding any number of * characters and having a pointer to any type and of any level.

But it's just a suggestion, no pressure. :)

[flowCRANE]

I'm coming back to this topic because the more code I write for my game project, the more I miss the double pointer types.

For example, recently I've been working on an API for custom bitmap fonts, that my game supports (custom format). The font stream contains the font parameters as well as the atlas textures. I have a function that I can use to search for a glyph of a specific character and return two pieces of information — the area occupied by the glyph (called ”stamp”) and the SDL texture handle (which is a pointer) of the atlas containing the requested glyph:

function Game_FontGetStamp(AFont: PGame_Font; ACode: TGame_SInt32; ARect: PGame_RectS32; AAtlas: PPSDL_Texture): TGame_Bool;

Parameters must be declared as a pointer to data, because I can use this function to retrieve specific information — only a rect, only a texture, or both. Which information I don't need is specified in the nil parameter:

// Get the rect of the character stamp for text measurement purposes (texture is not needed).
if Game_FontGetStamp(SomeFont, SomeCode, @SomeRect, nil) then

Many SDL functions do this, and that's a great thing — since we don't need all the information, there's no point in returning it.

As you can see in the example above, in order to be able to declare a function parameter as a pointer to a SDL texture, I need a pointer to a pointer, which is of type PPSDL_Texture. There is no such double pointer in these headers — I have to manually declare it.

Whenever I create a function with this type of optional parameters that is supposed to return a pointer to any type from the headers (e.g. pointer to the PSDL_Texture, PSDL_Joystick, PSDL_Window and so on), I need double pointers (with PPSDL_ prefix), and no such type does not exist in the headers.

So please add double pointer declarations for all data types declared in the header files. They are super-useful!

[Free-Pascal-meets-SDL-Website]

Nice to see you back again :-)!

Please, just craft a quick patch and PR with these double pointers and we will be happy to integrate them. No harm done, if we add them step by step and not all at once, to my mind.

Best regards Matthias

[flowCRANE]

I think it's better to prepare a patch with all the missing types added, so as to end this topic and so that something will not happen again in the future. It's better to do it once and do it right, instead of dragging the topic indefinitely.

If you don't mind, I can prepare such a patch.

[Free-Pascal-meets-SDL-Website]

Sure, that would be great and I would really like to see such a patch!

[flowCRANE]

I've added all missing double-pointer types and created PR — #122. There are some conflicts needed to resolve.

Edit: ok, it looks like all conflicts are now fixed and ready to merge.

[Free-Pascal-meets-SDL-Website]

Thanks, that was quick. Gonna review it soon.