Git Inbox Mirror of the ffmpeg-devel mailing list - see https://ffmpeg.org/mailman/listinfo/ffmpeg-devel
 help / color / mirror / Atom feed
From: "softworkz ." <softworkz-at-hotmail.com@ffmpeg.org>
To: "ffmpeg-devel@ffmpeg.org" <ffmpeg-devel@ffmpeg.org>
Subject: [FFmpeg-devel] [RFC] Shaping the AVTextFormat API Surface
Date: Tue, 22 Apr 2025 04:20:26 +0000
Message-ID: <DM8P223MB036504CFC0521633C2ADCCE3BABB2@DM8P223MB0365.NAMP223.PROD.OUTLOOK.COM> (raw)

Hi Stefano, Andreas, Nicolas
and of course, anybody who's interested in the AVTextFormat APIs,


let me start by saying that I have no intention to rush the 
publicization of those APIs. I think there's still a way to go.
But it's also true that when you don't have a clear understanding
of where you actually want to go, you'll hardly arrive there.

At the implementation level, I sensed that "you" ("FFmpeg")
are following some principles which are somewhat contradictive to 
those that I'm usually adhering to (e.g. "parameter validation
being a responsibility of the call site, crashing otherwise 
being acceptable"). Nonetheless, I'm the one who has to adapt,
and I'm not going to question that.

I'm addressing this to the three of you, due to your review 
comments and while I wouldn't call them contradictive, these
are heading into slightly different directions (removing 
checks altogether, replacing with assertions or printing a log
message in cases).
The one personal thought that I'd like to add, is that I 
think that parameter treatment (which checks to apply
or not) should depend on the access level of a specific API,
whether it's public, internal or private. That's something
where we don't have a plan for yet.

The AVTextFormatContext structure is all open at the moment,
means it gives everybody access to everything:

- You can call the text format api functions
- You can access the section definitions, the BPrint buffers
  and all other state and config values
- You can access and invoke the AVTextFormatter directly via
  its registered functions
- You can access AVTextWriterContext and the writers
  directly, again allowing direct invocation of their 
  functions

I did that intentionally to avoid any blockage during 
migration and also for being in a position later (=now)
where everything remains doable. 
Now that we've approached at this point, it would probably
be good to come to a clearer picture of the intended 
directions for the API.
Based on that, it should be easier to determine consistent
patterns for parameter validation for each category of API
functions - then I can apply that once and for all, 
cleanly and consistently everywhere.


This is how I'd categorize the current functions:


AVTextFormatter Implementations

- print_section_header
- print_section_footer
- print_integer
- print_string

(default, compact, csv, json, xml, ini, etc.)


AVTextWriter Implementations

- writer_w8
- writer_put_str
- writer_printf

(avio, stdout, buffer)
        

TextFormat API

- avtext_context_open
- avtext_context_close
- avtext_print_section_header
- avtext_print_section_footer
- avtext_print_integer
- avtext_print_integer_flags
- avtext_print_string
- avtext_print_unit_int
- avtext_print_rational
- avtext_print_time
- avtext_print_ts
- avtext_print_data
- avtext_print_data_hash
- avtext_print_integers
- avtext_get_formatter_by_name


TextWriter API

- avtextwriter_context_open
- avtextwriter_context_close
- avtextwriter_create_stdout
- avtextwriter_create_avio
- avtextwriter_create_file
- avtextwriter_create_buffer


Please let me know what you think,
thanks,
sw


_______________________________________________
ffmpeg-devel mailing list
ffmpeg-devel@ffmpeg.org
https://ffmpeg.org/mailman/listinfo/ffmpeg-devel

To unsubscribe, visit link above, or email
ffmpeg-devel-request@ffmpeg.org with subject "unsubscribe".

             reply	other threads:[~2025-04-22  4:20 UTC|newest]

Thread overview: 34+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2025-04-22  4:20 softworkz . [this message]
2025-04-24 14:47 ` [FFmpeg-devel] On errors, asserts and crashing (was: Shaping the AVTextFormat API Surface) Nicolas George
2025-04-25 13:05   ` softworkz .
2025-04-25 14:04     ` Nicolas George
2025-04-25 14:37       ` softworkz .
2025-04-25 14:41         ` Nicolas George
2025-04-25 14:53           ` softworkz .
2025-04-25 14:43     ` [FFmpeg-devel] On errors, asserts and crashing James Almer
2025-04-25 14:49       ` softworkz .
2025-04-25 16:04         ` Michael Niedermayer
2025-04-24 17:12 ` [FFmpeg-devel] [RFC] Shaping the AVTextFormat API Surface Nicolas George
2025-04-25 13:24   ` softworkz .
2025-04-25 13:32   ` softworkz .
2025-04-25 14:05     ` Nicolas George
2025-04-25 14:26       ` softworkz .
2025-04-27 10:07   ` Stefano Sabatini
2025-04-29  8:30     ` Nicolas George
2025-04-29 18:07       ` softworkz .
2025-04-30  2:56         ` softworkz .
2025-05-04 15:32       ` Stefano Sabatini
2025-05-04 20:38         ` softworkz .
2025-05-05 14:32         ` Nicolas George
2025-05-06 10:45           ` softworkz .
2025-05-07 23:18           ` Stefano Sabatini
2025-04-24 18:34 ` Rémi Denis-Courmont
2025-04-25 13:16   ` softworkz .
2025-04-27 10:42     ` Stefano Sabatini
2025-04-27 17:54       ` softworkz .
2025-04-28 22:26         ` Stefano Sabatini
2025-04-28 23:24           ` softworkz .
2025-05-03  8:55             ` softworkz .
2025-05-07 23:30               ` Stefano Sabatini
2025-05-07 23:42                 ` softworkz .
2025-05-08 21:26                   ` Stefano Sabatini

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=DM8P223MB036504CFC0521633C2ADCCE3BABB2@DM8P223MB0365.NAMP223.PROD.OUTLOOK.COM \
    --to=softworkz-at-hotmail.com@ffmpeg.org \
    --cc=ffmpeg-devel@ffmpeg.org \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

Git Inbox Mirror of the ffmpeg-devel mailing list - see https://ffmpeg.org/mailman/listinfo/ffmpeg-devel

This inbox may be cloned and mirrored by anyone:

	git clone --mirror https://master.gitmailbox.com/ffmpegdev/0 ffmpegdev/git/0.git

	# If you have public-inbox 1.1+ installed, you may
	# initialize and index your mirror using the following commands:
	public-inbox-init -V2 ffmpegdev ffmpegdev/ https://master.gitmailbox.com/ffmpegdev \
		ffmpegdev@gitmailbox.com
	public-inbox-index ffmpegdev

Example config snippet for mirrors.


AGPL code for this site: git clone https://public-inbox.org/public-inbox.git