X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=lily%2Fpage-breaking.cc;h=4e386b81832186cf48f7014f0b879b025cb616db;hb=e3a15ec3c1951dd16f6ee71fbd79870d9e2fb3a0;hp=993bfa459256c51c10fa57cb03678a018b103983;hpb=bd5233c02b1ba97029810ced58b8ea2c8ea0e759;p=lilypond.git diff --git a/lily/page-breaking.cc b/lily/page-breaking.cc index 993bfa4592..4e386b8183 100644 --- a/lily/page-breaking.cc +++ b/lily/page-breaking.cc @@ -1,7 +1,7 @@ /* This file is part of LilyPond, the GNU music typesetter. - Copyright (C) 2006--2010 Joe Neeman + Copyright (C) 2006--2011 Joe Neeman LilyPond is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by @@ -71,6 +71,60 @@ discarded after a call to set_current_breakpoints, since that Line_division refers to a subset of chunks which might be different from the current subset of chunks under consideration. + + HOW TO WRITE A PAGE BREAKING ALGORITHM + All page breakers supported by this class work more-or-less in the same way. + First, they request a particular number of systems by saying + set_current_breakpoints (0, last_break_position (), system_count) + (never mind what the first two arguments do, I'll get to them later). + Alternatively, you can do + set_to_ideal_line_configuration (0, last_break_position ()), + and the number of systems will be automatically chosen according to what + the line breaker wants. + + If there are multiple scores, there will be many different ways to achieve + a certain number of lines. You can see how many alternatives are available + with current_configuration_count (). For every i from 0 to + current_configuration_count ()-1, you can see the line division of the + corresponding configuration with current_configuration (i), or you can try + out various page configurations with one of the space_systems_xxx or + pack_systems_xxx functions. The first argument to each of these functions + is the configuration index. + + When you're done trying out configurations and you've picked the one + you want, do + break_into_pieces (0, last_break_position (), line_division_that_you_want); + return make_pages (systems_per_page, systems ()); + where systems_per_page is a vector of numbers telling how many systems are + on each page. You can get your systems_per_page vector by looking inside + the Page_spacing_results that are returned by space_systems_xxx or + pack_systems_xxx. + + A note on performance: set_current_breakpoints is EXPONENTIALLY SLOW unless + you constrain it by giving it a lower or an upper bound on the configurations + it looks for. Optimal_page_breaking, for example, works by trying + out a bunch of configurations, increasing the system count by one, trying + again and so on. Each time we increase the system count, we assume that the + best new configurations are going to be elementwise larger than the + best configuration for the previous system count (in other words, we're going + to get a new configuration just by adding an extra line to sone score + and leaving the rest the same). Therefore, we pass the best previous line + division as an lower bound to set_current_breakpoints. + + Now you should be in a position to understand Optimal_page_breaking::solve. + Go ahead and read that before finding out, in the next paragraph, + what the first two arguments to set_current_breakpoints do. + + "BREAKS" + Sometimes, it's useful to run this whole page-breaking machinery on a subset + of the book. To do this, you can mark certain "breaks" in the book (a poor + choice of name, perhaps, since a "break" here is different from a page break) + and you can run page breaking between any two breaks. You mark your breaks + by providing a Break_predicate (and, if you want, a Prob_break_predicate) + to Page_breaking's constructor. You then choose a subset of your book + by passing the starting and ending breaks to set_current_breakpoints. You + can see an example of this in Page_turn_page_breaking, where there is a break + everywhere that a page turn is allowed. */ #include "page-breaking.hh" @@ -529,6 +583,11 @@ Page_breaking::make_pages (vector lines_per_page, SCM systems) ret = scm_cons (page, ret); --page_num; } + + // By reversing the table, we ensure that duplicated labels (eg. those + // straddling a page turn) will appear in the table with their last + // occurence first. + label_page_table = scm_reverse_x (label_page_table, SCM_EOL); book_->top_paper ()->set_variable (ly_symbol2scm ("label-page-table"), label_page_table); return ret; } @@ -671,6 +730,7 @@ Page_breaking::chunk_list (vsize start_index, vsize end_index) return ret; } +// Returns the minimum number of _non-title_ lines. vsize Page_breaking::min_system_count (vsize start, vsize end) { @@ -683,6 +743,7 @@ Page_breaking::min_system_count (vsize start, vsize end) return ret; } +// Returns the maximum number of _non-title_ lines. vsize Page_breaking::max_system_count (vsize start, vsize end) { @@ -695,6 +756,9 @@ Page_breaking::max_system_count (vsize start, vsize end) return ret; } +// The numbers returned by this function represent either +// the maximum or minimum number of _non-title_ lines +// per chunk. Page_breaking::Line_division Page_breaking::system_count_bounds (vector const &chunks, bool min) @@ -702,7 +766,7 @@ Page_breaking::system_count_bounds (vector const &chunks, assert (chunks.size () >= 2); Line_division ret; - ret.resize (chunks.size () - 1, 1); + ret.resize (chunks.size () - 1, 0); for (vsize i = 0; i + 1 < chunks.size (); i++) { @@ -802,7 +866,7 @@ Page_breaking::set_to_ideal_line_configuration (vsize start, vsize end) div.push_back (line_breaking_[sys].best_solution (start, end).size ()); } else - div.push_back (1); + div.push_back (0); system_count_ += div.back (); } @@ -839,7 +903,7 @@ Page_breaking::cache_line_details (vsize configuration_index) } else { - assert (div[i] == 1); + assert (div[i] == 0); uncompressed_line_details_.push_back (system_specs_[sys].prob_ ? Line_details (system_specs_[sys].prob_, book_->paper_) : Line_details ()); @@ -877,7 +941,7 @@ Page_breaking::line_divisions_rec (vsize system_count, int real_min = max ((int) min_sys[my_index], (int) system_count - others_max); int real_max = min ((int) max_sys[my_index], (int) system_count - others_min); - if (real_min > real_max || real_min <= 0) + if (real_min > real_max || real_min < 0) { /* this should never happen within a recursive call. If it happens at all, it means that we were called with an unsolvable problem