TODO: Implement function "SDL_SetWindowMouseRect" and others (introduced in older SDL2 releases) + DISCUSSION: How to handle opaque structures

[flowCRANE]

Functions to implement:

• SDL_GetWindowMouseRect
• SDL_SetWindowMouseRect
• SDL_GetWindowMouseGrab
• SDL_SetWindowMouseGrab
• SDL_GetWindowKeyboardGrab
• SDL_SetWindowKeyboardGrab

[suve]

sdlvideo.inc needs a thorough rewrite, overall. One of the most notable things is that in the C headers, SDL_Window is an opaque struct, whereas in our headers we expose the fields.

I've started working on this some time ago, but I've still got some way to go. Could add the missing functions as a separate PR, though.

[flowCRANE]

Just use the {$MODESWITCH ADVANCEDRECORDS} modifier and in the declaration of a given structure, mark fields as private:

type
  TSDL_Window = record private  // voilà
    magic: Pointer;
    id: cuint32;
    title: PAnsiChar;
    icon: PSDL_Surface;
    {...}

SDL headers will see the fields, while the user of the headers will see the structures as empty. Of course, using advanced records will not change the size of the structures. The whole point here is to force encapsulation on regular structures and keeping typed pointers.

[suve]

The point is, unless you're compiling the SDL library itself, you don't need to know what's inside TSDL_Window. All the library functions return or receive pointers, so the compiler doesn't even need to know the size of TSDL_Window. Like I said, in the original C headers, it's an opaque struct.

[flowCRANE]

I understand it. And that's why I suggest you to use {$MODESWITCH ADVANCEDRECORDS} and mark all record fields as private. This will make pointers to structures opaque, and you don't have to declare additional data types and perform casts. This only makes sense if the SDL headers itself needs to see the fields of the structures, and the API user should not see them.

If Pascal headers do not explicitly use the fields of these structures, and the size of the structures is not used anywhere, then these types can be normal pointers, rather than pointers to empty records (such as TSDL_Joystick).

[Free-Pascal-meets-SDL-Website]

I understand it. And that's why I suggest you to use {$MODESWITCH ADVANCEDRECORDS} and mark all record fields as private. This will make pointers to structures opaque, and you don't have to declare additional data types and perform casts. This only makes sense if the SDL headers itself needs to see the fields of the structures, and the API user should not see them.

Although I understand your solution, I see no benefit in keeping the structure if it is not necessary for the purpose of the Pascal headers. Hence, I agree with both of you, we should just provide a TSDL_Window pointer, typed or not.

EDIT: Added an issue #65 for this.

[flowCRANE]

I see no benefit in keeping the structure if it is not necessary for the purpose of the Pascal headers.

There is also no advantage of declaring the type TSDL_Window at all, since only a pointer is used in the headers. So the declaration should look like this:

type
  PSDL_Window = {type} Pointer;

Nothing more. The same goes for other data types, which are also only used in pointer form, where the content of the structure has to be hidden — e.g. PSDL_Renderer, PSDL_Joystick etc.

[Free-Pascal-meets-SDL-Website]

There is also no advantage of declaring the type TSDL_Window at all, since only a pointer is used in the headers.

In principle I agree, see also this convert typedef struct question.

I guess from a Pascal translator point of view, if you find a construct like this in the header

typedef struct SDL_Window SDL_Window;

it more intuitivly translates to a record type at first rather than a pure Pointer type (as no indication for a pointer declaration is found here anyway, although not necessary in C).

type
  TSDL_Window = record end;

The other way round, if checking a Pascal inc file for updates and you find this

type
  PSDL_Window = {type} Pointer;

it is not obvious to translate it back to this

typedef struct SDL_Window SDL_Window;

So, has anything changed in the header? (The translator may ask.)

From a clarity standpoint I vote for keeping the empty records.

[flowCRANE]

My opinion is that if something is not needed, it is not declared. The TSDL_Window type is not needed for anything, because it neither has to be used to declare a pointer type, nor is it used in any function in this API (headers). Its existence in itself erroneously suggests that this type is needed (but is not).

Second, there is a fundamental difference between the library code and the API code that has imports from that library, so do not try to translate the library code 1:1 (the more that Pascal and C have significant differences). It doesn't matter how it is implemented on the library side, because the headers shouldn't even know that the window is represented by a structure.

So, what I suggest is as follows. Remove any non-pointer data types that are not used by header functions but exist only for pointer type declarations. Declare pointer types as general pointers so that they are untyped and opaque. Of course, do as you like and if you prefer to have empty records, just remove all fields from the structures.

[Free-Pascal-meets-SDL-Website]

I understand your point and, as written before, in principle I agree, too.

I would like to wait for @suve 's opinion on this issue.