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-requ...@ffmpeg.org with subject "unsubscribe".
